rfc9068 0.1.0__tar.gz

rfc9068-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.3
+Name: rfc9068
+Version: 0.1.0
+Summary: Validates OIDC/OAuth2 access tokens following RC9068
+Requires-Dist: pydantic>=2.11.9
+Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Python: >=3.11, <4.0
+Description-Content-Type: text/markdown
+
+# RFC9068 Access Token Validator
+This library provides a means to validate access tokens following the rules laid out in
+[RFC9068](https://datatracker.ietf.org/doc/rfc9068/).
+
+## Rationale
+Both [OIDC](https://openid.net/specs/openid-authentication-2_0.html) and
+[OAuth2](https://datatracker.ietf.org/doc/rfc6749/) do not clearly specify *how* to validate access tokens
+as a resource server. This poses a risk as the implementation of choice might differ across applications and
+may be insecure.
+
+In order to resolve this issue [RFC7662](https://datatracker.ietf.org/doc/rfc7662/) was published in 2015.
+This method involves the resource server sending the access token to the authorization server to verify it.
+This comes with a big performance penalty, as the resource server needs to make its own request to the
+authorization server everytime it needs to validate a token, which basically needs to happen for every
+authenticated request.
+
+To overcome the performance penalty, systems started using access tokens in the form of JSON Web Tokens, which
+can be parsed and validated. However, considering there was no formal definition of what the contents of the
+token should look like, tokens issued by one provider were not necessarily compatible with tokens provided by
+another provider, leading to different implementations of token validation.
+
+[RFC9068](https://datatracker.ietf.org/doc/rfc9068/) aims to overcome that obstacle by providing a specification
+on what the contents of the access tokens should look like and how to validate the access tokens.
+
+## Installation
+Install using uv:
+```shell
+uv add rfc9068
+```
+or using pip:
+```shell
+pip install rfc9068
+```
+
+## Usage
+The validator itself is nothing more than a composition, its dependencies do the actual work.
+That means that we need to construct the validator and it's recommended to use dependency injection to do that,
+otherwise perhaps implement a factory.
+
+### Factory example
+```python
+from rfc9068 import RFC9068AccessTokenValidator, RFC9068AccessTokenValidatorInterface
+from rfc9068.parser import AccessTokenParser
+from rfc9068.payload import (
+  IssuerValidator,
+  AudienceValidator,
+  ExpirationValidator
+)
+from rfc9068.signature import PyJwtSignatureValidator, PyJwtJWKResolver
+from jwt import PyJWKClient, PyJWS
+
+class ValidatorFactory:
+  def __call__(
+    self,
+    jwks_url: str,
+    issuer: str,
+    audience: str,
+    algorithms: list[str] = ["RS256"],
+  ): RFC9068AccessTokenValidatorInterface:
+    return RFC9068AccessTokenValidator(
+        AccessTokenParser(),
+        PyJwtSignatureValidator(
+            PyJwtJWKResolver(
+                PyJWKClient(jwks_url),
+            ),
+            PyJWS(),
+        ),
+        IssuerValidator(),
+        AudienceValidator(),
+        ExpirationValidator(),
+        algorithms,
+        issuer,
+        audience,
+    )
+
+factory = ValidatorFactory()
+validate = factory(
+  "http://keycloak:8002/realms/rfc9068/protocol/openid-connect/certs",
+  "http://keycloak:8002/realms/rfc9068",
+  "test-audience",
+  ["RS256"],
+)
+```
+
+### Validator
+Now that we have a validator we can use it to validate access tokens.
+```python
+from rfc9068.core import InvalidTokenError
+
+try:
+  validate(access_token)
+except InvalidTokenError as e:
+  # Token is not valid
+  print(e)
+  raise e
+
+# When no exceptions are raised the token is valid
+```
+
+## Development
+For development of this package we provide a container setup.
+
+### Building
+```shell
+docker compose build
+```
+
+### Starting containers
+```shell
+docker compose run --rm validator sh
+```
+
+This will also open a shell where we can run our dev tools:
+```shell
+uv run ruff check
+uv run mypy .
+uv run pytest -v --cov --cov-fail-under=100
+```

rfc9068-0.1.0/README.md

@@ -0,0 +1,118 @@
+# RFC9068 Access Token Validator
+This library provides a means to validate access tokens following the rules laid out in
+[RFC9068](https://datatracker.ietf.org/doc/rfc9068/).
+
+## Rationale
+Both [OIDC](https://openid.net/specs/openid-authentication-2_0.html) and
+[OAuth2](https://datatracker.ietf.org/doc/rfc6749/) do not clearly specify *how* to validate access tokens
+as a resource server. This poses a risk as the implementation of choice might differ across applications and
+may be insecure.
+
+In order to resolve this issue [RFC7662](https://datatracker.ietf.org/doc/rfc7662/) was published in 2015.
+This method involves the resource server sending the access token to the authorization server to verify it.
+This comes with a big performance penalty, as the resource server needs to make its own request to the
+authorization server everytime it needs to validate a token, which basically needs to happen for every
+authenticated request.
+
+To overcome the performance penalty, systems started using access tokens in the form of JSON Web Tokens, which
+can be parsed and validated. However, considering there was no formal definition of what the contents of the
+token should look like, tokens issued by one provider were not necessarily compatible with tokens provided by
+another provider, leading to different implementations of token validation.
+
+[RFC9068](https://datatracker.ietf.org/doc/rfc9068/) aims to overcome that obstacle by providing a specification
+on what the contents of the access tokens should look like and how to validate the access tokens.
+
+## Installation
+Install using uv:
+```shell
+uv add rfc9068
+```
+or using pip:
+```shell
+pip install rfc9068
+```
+
+## Usage
+The validator itself is nothing more than a composition, its dependencies do the actual work.
+That means that we need to construct the validator and it's recommended to use dependency injection to do that,
+otherwise perhaps implement a factory.
+
+### Factory example
+```python
+from rfc9068 import RFC9068AccessTokenValidator, RFC9068AccessTokenValidatorInterface
+from rfc9068.parser import AccessTokenParser
+from rfc9068.payload import (
+  IssuerValidator,
+  AudienceValidator,
+  ExpirationValidator
+)
+from rfc9068.signature import PyJwtSignatureValidator, PyJwtJWKResolver
+from jwt import PyJWKClient, PyJWS
+
+class ValidatorFactory:
+  def __call__(
+    self,
+    jwks_url: str,
+    issuer: str,
+    audience: str,
+    algorithms: list[str] = ["RS256"],
+  ): RFC9068AccessTokenValidatorInterface:
+    return RFC9068AccessTokenValidator(
+        AccessTokenParser(),
+        PyJwtSignatureValidator(
+            PyJwtJWKResolver(
+                PyJWKClient(jwks_url),
+            ),
+            PyJWS(),
+        ),
+        IssuerValidator(),
+        AudienceValidator(),
+        ExpirationValidator(),
+        algorithms,
+        issuer,
+        audience,
+    )
+
+factory = ValidatorFactory()
+validate = factory(
+  "http://keycloak:8002/realms/rfc9068/protocol/openid-connect/certs",
+  "http://keycloak:8002/realms/rfc9068",
+  "test-audience",
+  ["RS256"],
+)
+```
+
+### Validator
+Now that we have a validator we can use it to validate access tokens.
+```python
+from rfc9068.core import InvalidTokenError
+
+try:
+  validate(access_token)
+except InvalidTokenError as e:
+  # Token is not valid
+  print(e)
+  raise e
+
+# When no exceptions are raised the token is valid
+```
+
+## Development
+For development of this package we provide a container setup.
+
+### Building
+```shell
+docker compose build
+```
+
+### Starting containers
+```shell
+docker compose run --rm validator sh
+```
+
+This will also open a shell where we can run our dev tools:
+```shell
+uv run ruff check
+uv run mypy .
+uv run pytest -v --cov --cov-fail-under=100
+```

rfc9068-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "rfc9068"
+version = "0.1.0"
+description = "Validates OIDC/OAuth2 access tokens following RC9068"
+readme = "README.md"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "pydantic>=2.11.9",
+    "pyjwt[crypto]>=2.10.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx[http2]>=0.28.1",
+    "mypy>=1.18.1",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.13.0",
+]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D100", "D101", "D102", "D103", "D104", "D107", "D401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004"]
+
+[tool.coverage.run]
+omit = ["tests/**"]

rfc9068-0.1.0/src/rfc9068/__init__.py

@@ -0,0 +1,62 @@
+from abc import ABCMeta, abstractmethod
+from collections.abc import Sequence
+
+from rfc9068.parser import AccessTokenParserInterface, ParsedAccessToken
+from rfc9068.payload import (
+    AudienceValidatorInterface,
+    ExpirationValidatorInterface,
+    IssuerValidatorInterface,
+)
+from rfc9068.signature import SignatureValidatorInterface
+
+
+class RFC9068AccessTokenValidatorInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, access_token: str) -> ParsedAccessToken: ...
+
+
+class RFC9068AccessTokenValidator(RFC9068AccessTokenValidatorInterface):
+    _parse_access_token: AccessTokenParserInterface
+    _validate_signature: SignatureValidatorInterface
+    _validate_issuer: IssuerValidatorInterface
+    _validate_audience: AudienceValidatorInterface
+    _validate_expiration: ExpirationValidatorInterface
+    _algorithms: Sequence[str]
+    _issuer: str
+    _audience: str
+
+    def __init__(  # noqa: PLR0913
+        self,
+        access_token_parser: AccessTokenParserInterface,
+        signature_validator: SignatureValidatorInterface,
+        issuer_validator: IssuerValidatorInterface,
+        audience_validator: AudienceValidatorInterface,
+        expiration_validator: ExpirationValidatorInterface,
+        algorithms: Sequence[str],
+        issuer: str,
+        audience: str,
+    ) -> None:
+        self._parse_access_token = access_token_parser
+        self._validate_signature = signature_validator
+        self._validate_issuer = issuer_validator
+        self._validate_audience = audience_validator
+        self._validate_expiration = expiration_validator
+        self._algorithms = algorithms
+        self._issuer = issuer
+        self._audience = audience
+
+    def __call__(self, access_token: str) -> ParsedAccessToken:
+        parsed_token = self._parse_access_token(access_token)
+
+        self._validate_signature(
+            parsed_token.header,
+            parsed_token.raw_header,
+            parsed_token.raw_payload,
+            parsed_token.signature,
+            self._algorithms,
+        )
+        self._validate_issuer(parsed_token.payload, self._issuer)
+        self._validate_audience(parsed_token.payload, self._audience)
+        self._validate_expiration(parsed_token.payload)
+
+        return parsed_token

rfc9068-0.1.0/src/rfc9068/core.py

@@ -0,0 +1 @@
+class InvalidTokenError(Exception): ...

rfc9068-0.1.0/src/rfc9068/parser.py

@@ -0,0 +1,77 @@
+import base64
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pydantic import BaseModel, ValidationError
+
+from rfc9068.core import InvalidTokenError
+from rfc9068.payload import InvalidPayloadError, Payload
+
+
+class InvalidHeaderError(InvalidTokenError): ...
+
+
+class ValidTypHeaderValues(StrEnum):
+    AT_JWT = "at+jwt"
+    APPLICATION_AT_JWT = "application/at+jwt"
+
+
+class ValidAlgHeaderValues(StrEnum):
+    RS256 = "RS256"
+
+
+class JWTHeader(BaseModel):
+    typ: ValidTypHeaderValues
+    alg: ValidAlgHeaderValues
+    kid: str
+
+
+@dataclass
+class ParsedAccessToken:
+    header: JWTHeader
+    raw_header: str
+    payload: Payload
+    raw_payload: str
+    signature: bytes
+
+
+class AccessTokenParserInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, access_token: str) -> ParsedAccessToken: ...
+
+
+class AccessTokenParser(AccessTokenParserInterface):
+    def __call__(self, access_token: str) -> ParsedAccessToken:
+        raw_header, raw_payload, signature = access_token.split(".")
+
+        padded_header = self._add_padding(raw_header)
+        padded_payload = self._add_padding(raw_payload)
+        padded_signature = self._add_padding(signature)
+
+        decoded_header = base64.urlsafe_b64decode(padded_header)
+        try:
+            header = JWTHeader.model_validate_json(decoded_header)
+        except ValidationError as e:
+            raise InvalidHeaderError(str(e)) from e
+
+        decoded_payload = base64.urlsafe_b64decode(padded_payload)
+        try:
+            payload = Payload.model_validate_json(decoded_payload)
+        except ValidationError as e:
+            raise InvalidPayloadError(str(e)) from e
+
+        decoded_signature = base64.urlsafe_b64decode(padded_signature)
+
+        return ParsedAccessToken(
+            header,
+            raw_header,
+            payload,
+            raw_payload,
+            decoded_signature,
+        )
+
+    def _add_padding(self, value: str) -> str:
+        padding_required = 4 - (len(value) % 4)
+        value += "=" * padding_required
+        return value

rfc9068-0.1.0/src/rfc9068/payload.py

@@ -0,0 +1,78 @@
+from abc import ABCMeta, abstractmethod
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from rfc9068.core import InvalidTokenError
+
+
+class Payload(BaseModel):
+    model_config = {"extra": "allow"}
+
+    iss: str
+    exp: int
+    aud: str | list[str]
+    sub: str
+    client_id: str
+    iat: int
+    jti: str
+
+
+class InvalidPayloadError(InvalidTokenError): ...
+
+
+class InvalidIssuerError(InvalidPayloadError): ...
+
+
+class IssuerValidatorInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, claims: Payload, expected_issuer: str) -> None:
+        """Implementations should raise InvalidIssuerError if invalid."""
+
+
+class IssuerValidator(IssuerValidatorInterface):
+    def __call__(self, claims: Payload, expected_issuer: str) -> None:
+        issuer = claims.iss
+        if issuer != expected_issuer:
+            msg = f"Expected issuer '{expected_issuer}', got '{issuer}'!"
+            raise InvalidIssuerError(msg)
+
+
+class InvalidAudienceError(InvalidPayloadError): ...
+
+
+class AudienceValidatorInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, claims: Payload, expected_audience: str) -> None:
+        """Implementations should raise InvalidAudienceError if invalid."""
+
+
+class AudienceValidator(AudienceValidatorInterface):
+    def __call__(self, claims: Payload, expected_audience: str) -> None:
+        audience = claims.aud
+        if isinstance(audience, str) and audience != expected_audience:
+            msg = f"Expected audience '{expected_audience}', got '{audience}'!"
+            raise InvalidAudienceError(msg)
+
+        if expected_audience not in audience:
+            msg = (f"Expected audience '{expected_audience}' not in "
+                   f"'{', '.join(aud for aud in audience)}'")
+            raise InvalidAudienceError(msg)
+
+
+class ExpiredTokenError(InvalidPayloadError): ...
+
+
+class ExpirationValidatorInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, claims: Payload) -> None:
+        """Implementations should raise ExpiredTokenError if invalid."""
+
+
+class ExpirationValidator(ExpirationValidatorInterface):
+    def __call__(self, claims: Payload) -> None:
+        now = datetime.now(UTC).timestamp()
+        exp = claims.exp
+        if exp <= now:
+            msg = "The token is expired!"
+            raise ExpiredTokenError(msg)

rfc9068-0.1.0/src/rfc9068/signature.py

@@ -0,0 +1,77 @@
+from abc import ABCMeta, abstractmethod
+from collections.abc import Sequence
+
+from cryptography.hazmat.primitives._serialization import Encoding, PublicFormat
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
+from jwt import InvalidSignatureError as PyJWTInvalidSignatureError
+from jwt import PyJWKClient, PyJWS
+
+from rfc9068.core import InvalidTokenError
+from rfc9068.parser import JWTHeader
+
+
+class JWKResolverInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(self, kid: str) -> bytes: ...
+
+
+class PyJwtJWKResolver(JWKResolverInterface):
+    _jwks_client: PyJWKClient
+
+    def __init__(self, jwks_client: PyJWKClient) -> None:
+        self._jwks_client = jwks_client
+
+    def __call__(self, kid: str) -> bytes:
+        key = self._jwks_client.get_signing_key(kid).key
+        if not isinstance(key, RSAPublicKey):
+            msg = "Key should be an RSA public key!"
+            raise TypeError(msg)
+
+        return key.public_bytes(Encoding.OpenSSH, PublicFormat.OpenSSH)
+
+
+class InvalidSignatureError(InvalidTokenError): ...
+
+
+class SignatureValidatorInterface(metaclass=ABCMeta):
+    @abstractmethod
+    def __call__(
+        self,
+        header: JWTHeader,
+        raw_header: str,
+        raw_payload: str,
+        signature: bytes,
+        algorithms: Sequence[str],
+    ) -> None:
+        """Implementations should raise InvalidSignatureError if invalid."""
+
+
+class PyJwtSignatureValidator(SignatureValidatorInterface):
+    _get_signing_key: JWKResolverInterface
+    _jws: PyJWS
+
+    def __init__(self, jwk_resolver: JWKResolverInterface, jws: PyJWS) -> None:
+        self._get_signing_key = jwk_resolver
+        self._jws = jws
+
+    def __call__(
+        self,
+        header: JWTHeader,
+        raw_header: str,
+        raw_payload: str,
+        signature: bytes,
+        algorithms: Sequence[str],
+    ) -> None:
+        signing_key = self._get_signing_key(header.kid)
+
+        try:
+            self._jws._verify_signature(  # noqa: SLF001
+                f"{raw_header}.{raw_payload}".encode(),
+                header.model_dump(),
+                signature,
+                signing_key,
+                algorithms,
+            )
+        except PyJWTInvalidSignatureError as e:
+            msg = "Invalid signature, the token may have been tampered with!"
+            raise InvalidSignatureError(msg) from e