auth0-api-python 1.0.0b1__py3-none-any.whl

auth0_api_python-1.0.0b1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Auth0, Inc. <support@auth0.com> (http://auth0.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auth0_api_python-1.0.0b1.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.3
+Name: auth0-api-python
+Version: 1.0.0b1
+Summary: SDK for verifying access tokens and securing APIs with Auth0, using Authlib.
+License: MIT
+Author: Snehil Kishore snehil.kishore@okta.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: authlib (>=1.0,<2.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+The `auth0-api-python` library allows you to secure APIs running on Python, particularly for verifying Auth0-issued access tokens.
+
+It’s intended as a foundation for building more framework-specific integrations (e.g., with FastAPI, Django, etc.), but you can also use it directly in any Python server-side environment.
+
+![Release](https://img.shields.io/pypi/v/auth0-api-python) ![Downloads](https://img.shields.io/pypi/dw/auth0-api-python) [![License](https://img.shields.io/:license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+
+📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💬 [Feedback](#feedback)
+
+## Documentation
+
+- [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
+
+## Getting Started
+
+### 1. Install the SDK
+
+_This library requires Python 3.9+._
+
+```shell
+pip install auth0-api-python
+```
+
+If you’re using Poetry:
+
+```shell
+poetry install auth0-api-python
+```
+
+### 2. Create the Auth0 SDK client
+
+Create an instance of the `ApiClient`. This instance will be imported and used anywhere we need access to the methods.
+
+```python 
+from auth0_api_python import ApiClient, ApiClientOptions
+
+
+api_client = ApiClient(ApiClientOptions(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>"
+))
+```
+
+- The `AUTH0_DOMAIN` can be obtained from the [Auth0 Dashboard](https://manage.auth0.com) once you've created an application.
+- The `AUTH0_AUDIENCE` is the identifier of the API. You can find this in the [APIs section of the Auth0 Dashboard](https://manage.auth0.com/#/apis/).
+
+### 3. Verify the Access Token
+
+Use the `verify_access_token` method to validate access tokens. The method automatically checks critical claims like `iss`, `aud`, `exp`, `nbf`.
+
+```python
+import asyncio
+
+from auth0_api_python import ApiClient, ApiClientOptions
+
+async def main():
+    api_client = ApiClient(ApiClientOptions(
+        domain="<AUTH0_DOMAIN>",
+        audience="<AUTH0_AUDIENCE>"
+    ))
+    access_token = "..."
+
+    decoded_and_verified_token = await api_client.verify_access_token(access_token=access_token)
+    print(decoded_and_verified_token)
+
+asyncio.run(main())
+```
+
+In this example, the returned dictionary contains the decoded claims (like `sub`, `scope`, etc.) from the verified token.
+
+#### Requiring Additional Claims
+
+If your application demands extra claims, specify them with `required_claims`:
+
+```python
+decoded_and_verified_token = await api_client.verify_access_token(
+    access_token=access_token,
+    required_claims=["my_custom_claim"]
+)
+```
+
+If the token lacks `my_custom_claim` or fails any standard check (issuer mismatch, expired token, invalid signature), the method raises a `VerifyAccessTokenError`.
+
+## Feedback
+
+### Contributing
+
+We appreciate feedback and contribution to this repo! Before you get started, please read the following:
+
+- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
+- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
+- [This repo's contribution guide](./../../CONTRIBUTING.md)
+
+### Raise an issue
+
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-server-python/issues).
+
+## Vulnerability Reporting
+
+Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.
+
+## What is Auth0?
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
+    <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+    <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+  </picture>
+</p>
+<p align="center">
+  Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
+</p>
+<p align="center">
+  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-server-python/blob/main/packages/auth0_api_python/LICENSE"> LICENSE</a> file for more info.
+</p>

auth0_api_python-1.0.0b1.dist-info/RECORD

@@ -0,0 +1,10 @@
+src/__init__.py,sha256=CTj82tGIXF0ypzAjMeCZ3cuAfKF472ZsZ0bdorGPh7E,291
+src/api_client.py,sha256=59_aYUMXGv1JTJosDjZnOteLeEmT_XPX589FzG5Gnsk,4578
+src/config.py,sha256=CjqJ1nTO1XT9bJZgoLUbCGp3SSFkKYItoV1eE9V_Gr4,651
+src/errors.py,sha256=PG5NSZqTR8JJhFtWsxZPQwC-BNmKhtFwvCS1vE3Dcc0,671
+src/token_utils.py,sha256=2sa0m4y8Mgnh2mIbI0-VN-UUUTysYmS1Gk255xpeUHc,3817
+src/utils.py,sha256=D38wC2Wan3fMF25TqqTZzyrRo0EUkk3XDCX-ADTQQJo,2905
+auth0_api_python-1.0.0b1.dist-info/LICENSE,sha256=EEi9tibVAgKdGU1DmXmHjZFOwMfYXDV45mabfEmULkQ,1116
+auth0_api_python-1.0.0b1.dist-info/METADATA,sha256=ZhXRmHrcyXStcXjr8rSKZrjO2s0RdvpJ4LHfeS_bFu8,5167
+auth0_api_python-1.0.0b1.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+auth0_api_python-1.0.0b1.dist-info/RECORD,,

auth0_api_python-1.0.0b1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.0.1
+Root-Is-Purelib: true
+Tag: py3-none-any

src/__init__.py

@@ -0,0 +1,14 @@
+"""
+auth0-api-python
+
+A lightweight Python SDK for verifying Auth0-issued access tokens
+in server-side APIs, using Authlib for OIDC discovery and JWKS fetching.
+"""
+
+from .api_client import ApiClient
+from .config import ApiClientOptions
+
+__all__ = [
+    "ApiClient",
+    "ApiClientOptions"
+]

src/api_client.py

@@ -0,0 +1,128 @@
+import time
+from typing import Optional, List, Dict, Any
+
+from authlib.jose import JsonWebToken, JsonWebKey
+
+from .config import ApiClientOptions
+from .errors import MissingRequiredArgumentError, VerifyAccessTokenError
+from .utils import fetch_oidc_metadata, fetch_jwks, get_unverified_header
+
+class ApiClient:
+    """
+    The main class for discovering OIDC metadata (issuer, jwks_uri) and verifying
+    Auth0-issued JWT access tokens in an async environment.
+    """
+
+    def __init__(self, options: ApiClientOptions):
+
+        if not options.domain:
+            raise MissingRequiredArgumentError("domain")
+        if not options.audience:
+            raise MissingRequiredArgumentError("audience")
+
+        self.options = options
+        self._metadata: Optional[Dict[str, Any]] = None
+        self._jwks_data: Optional[Dict[str, Any]] = None
+
+        self._jwt = JsonWebToken(["RS256"])
+
+    async def _discover(self) -> Dict[str, Any]:
+        """Lazy-load OIDC discovery metadata."""
+        if self._metadata is None:
+            self._metadata = await fetch_oidc_metadata(
+                domain=self.options.domain,
+                custom_fetch=self.options.custom_fetch
+            )
+        return self._metadata
+
+    async def _load_jwks(self) -> Dict[str, Any]:
+        """Fetches and caches JWKS data from the OIDC metadata."""
+        if self._jwks_data is None:
+            metadata = await self._discover()
+            jwks_uri = metadata["jwks_uri"]
+            self._jwks_data = await fetch_jwks(
+                jwks_uri=jwks_uri, 
+                custom_fetch=self.options.custom_fetch
+            )
+        return self._jwks_data
+
+    async def verify_access_token(
+        self,
+        access_token: str,
+        required_claims: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Asynchronously verifies the provided JWT access token.
+        
+        - Fetches OIDC metadata and JWKS if not already cached.
+        - Decodes and validates signature (RS256) with the correct key.
+        - Checks standard claims: 'iss', 'aud', 'exp', 'iat'
+        - Checks extra required claims if 'required_claims' is provided.
+
+        Returns:
+            The decoded token claims if valid.
+
+        Raises:
+            MissingRequiredArgumentError: If no token is provided.
+            VerifyAccessTokenError: If verification fails (signature, claims mismatch, etc.).
+        """
+        if not access_token:
+            raise MissingRequiredArgumentError("access_token")
+
+        required_claims = required_claims or []
+
+    
+        try:
+            header = await get_unverified_header(access_token)
+            kid = header["kid"]
+        except Exception as e:
+            raise VerifyAccessTokenError(f"Failed to parse token header: {str(e)}") from e
+
+        jwks_data = await self._load_jwks()
+        matching_key_dict = None
+        for key_dict in jwks_data["keys"]:
+            if key_dict.get("kid") == kid:
+                matching_key_dict = key_dict
+                break
+
+        if not matching_key_dict:
+            raise VerifyAccessTokenError(f"No matching key found for kid: {kid}")
+
+        public_key = JsonWebKey.import_key(matching_key_dict)
+
+        if isinstance(access_token, str) and access_token.startswith("b'"):
+            access_token = access_token[2:-1]
+        try:
+            claims = self._jwt.decode(access_token, public_key)
+        except Exception as e:
+            raise VerifyAccessTokenError(f"Signature verification failed: {str(e)}") from e
+
+        metadata = await self._discover()
+        issuer = metadata["issuer"]
+
+
+        if claims.get("iss") != issuer:
+            raise VerifyAccessTokenError("Issuer mismatch")
+        
+        expected_aud = self.options.audience
+        actual_aud = claims.get("aud")
+
+        if isinstance(actual_aud, list):
+            if expected_aud not in actual_aud:
+                raise VerifyAccessTokenError("Audience mismatch (not in token's aud array)")
+        else:
+            if actual_aud != expected_aud:
+                raise VerifyAccessTokenError("Audience mismatch (single aud)")
+
+        now = int(time.time())
+        if "exp" not in claims or now >= claims["exp"]:
+            raise VerifyAccessTokenError("Token is expired")
+        if "iat" not in claims:
+            raise VerifyAccessTokenError("Missing 'iat' claim in token")
+
+        #Additional required_claims
+        for rc in required_claims:
+            if rc not in claims:
+                raise VerifyAccessTokenError(f"Missing required claim: {rc}")
+
+        return claims

src/config.py

@@ -0,0 +1,24 @@
+"""
+Configuration classes and utilities for auth0-api-python.
+"""
+
+from typing import Optional, Callable
+
+class ApiClientOptions:
+    """
+    Configuration for the ApiClient.
+
+    Args:
+        domain: The Auth0 domain, e.g., "my-tenant.us.auth0.com".
+        audience: The expected 'aud' claim in the token.
+        custom_fetch: Optional callable that can replace the default HTTP fetch logic.
+    """
+    def __init__(
+        self,
+        domain: str,
+        audience: str,
+        custom_fetch: Optional[Callable[..., object]] = None
+    ):
+        self.domain = domain
+        self.audience = audience
+        self.custom_fetch = custom_fetch

src/errors.py

@@ -0,0 +1,21 @@
+"""
+Custom exceptions for auth0-api-python SDK
+"""
+
+class MissingRequiredArgumentError(Exception):
+    """Error raised when a required argument is missing."""
+    code = "missing_required_argument_error"
+
+    def __init__(self, argument: str):
+        super().__init__(f"The argument '{argument}' is required but was not provided.")
+        self.argument = argument
+        self.name = self.__class__.__name__
+
+
+class VerifyAccessTokenError(Exception):
+    """Error raised when verifying the access token fails."""
+    code = "verify_access_token_error"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = self.__class__.__name__

src/token_utils.py

@@ -0,0 +1,84 @@
+import time
+from typing import Optional, Dict, Any, Union
+from authlib.jose import JsonWebKey, jwt
+
+
+# A private RSA JWK for test usage.
+
+PRIVATE_JWK = {
+    "kty": "RSA",
+    "alg": "RS256",
+    "use": "sig",
+    "kid": "TEST_KEY",
+    "n": "whYOFK2Ocbbpb_zVypi9SeKiNUqKQH0zTKN1-6fpCTu6ZalGI82s7XK3tan4dJt90ptUPKD2zvxqTzFNfx4HHHsrYCf2-FMLn1VTJfQazA2BvJqAwcpW1bqRUEty8tS_Yv4hRvWfQPcc2Gc3-_fQOOW57zVy-rNoJc744kb30NjQxdGp03J2S3GLQu7oKtSDDPooQHD38PEMNnITf0pj-KgDPjymkMGoJlO3aKppsjfbt_AH6GGdRghYRLOUwQU-h-ofWHR3lbYiKtXPn5dN24kiHy61e3VAQ9_YAZlwXC_99GGtw_NpghFAuM4P1JDn0DppJldy3PGFC0GfBCZASw",
+    "e": "AQAB",
+    "d": "VuVE_KEP6323WjpbBdAIv7HGahGrgGANvbxZsIhm34lsVOPK0XDegZkhAybMZHjRhp-gwVxX5ChC-J3cUpOBH5FNxElgW6HizD2Jcq6t6LoLYgPSrfEHm71iHg8JsgrqfUnGYFzMJmv88C6WdCtpgG_qJV1K00_Ly1G1QKoBffEs-v4fAMJrCbUdCz1qWto-PU-HLMEo-krfEpGgcmtZeRlDADh8cETMQlgQfQX2VWq_aAP4a1SXmo-j0cvRU4W5Fj0RVwNesIpetX2ZFz4p_JmB5sWFEj_fC7h5z2lq-6Bme2T3BHtXkIxoBW0_pYVnASC8P2puO5FnVxDmWuHDYQ",
+    "p": "07rgXd_tLUhVRF_g1OaqRZh5uZ8hiLWUSU0vu9coOaQcatSqjQlIwLW8UdKv_38GrmpIfgcEVQjzq6rFBowUm9zWBO9Eq6enpasYJBOeD8EMeDK-nsST57HjPVOCvoVC5ZX-cozPXna3iRNZ1TVYBY3smn0IaxysIK-zxESf4pM",
+    "q": "6qrE9TPhCS5iNR7QrKThunLu6t4H_8CkYRPLbvOIt2MgZyPLiZCsvdkTVSOX76QQEXt7Y0nTNua69q3K3Jhf-YOkPSJsWTxgrfOnjoDvRKzbW3OExIMm7D99fVBODuNWinjYgUwGSqGAsb_3TKhtI-Gr5ls3fn6B6oEjVL0dpmk",
+    "dp": "mHqjrFdgelT2OyiFRS3dAAPf3cLxJoAGC4gP0UoQyPocEP-Y17sQ7t-ygIanguubBy65iDFLeGXa_g0cmSt2iAzRAHrDzI8P1-pQl2KdWSEg9ssspjBRh_F_AiJLLSPRWn_b3-jySkhawtfxwO8Kte1QsK1My765Y0zFvJnjPws",
+    "dq": "KmjaV4YcsVAUp4z-IXVa5htHWmLuByaFjpXJOjABEUN0467wZdgjn9vPRp-8Ia8AyGgMkJES_uUL_PDDrMJM9gb4c6P4-NeUkVtreLGMjFjA-_IQmIMrUZ7XywHsWXx0c2oLlrJqoKo3W-hZhR0bPFTYgDUT_mRWjk7wV6wl46E",
+    "qi": "iYltkV_4PmQDfZfGFpzn2UtYEKyhy-9t3Vy8Mw2VHLAADKGwJvVK5ficQAr2atIF1-agXY2bd6KV-w52zR8rmZfTr0gobzYIyqHczOm13t7uXJv2WygY7QEC2OGjdxa2Fr9RnvS99ozMa5nomZBqTqT7z5QV33czjPRCjvg6FcE",
+}
+
+
+async def generate_token(
+    domain: str,
+    user_id: str,
+    audience: Optional[str] = None,
+    issuer: Union[str, bool, None] = None,
+    iat: bool = True,
+    exp: bool = True,
+    claims: Optional[Dict[str, Any]] = None,
+    expiration_time: int = 3600,
+) -> str:
+    """
+    Generates a real RS256-signed JWT using the private key above.
+
+    Args:
+        domain: The Auth0 domain (used if issuer is not False).
+        user_id: The 'sub' claim in the token.
+        audience: The 'aud' claim in the token. If omitted, 'aud' won't be included.
+        issuer:
+            - If a string, it's placed in 'iss' claim.
+            - If None, default is f"https://{domain}/".
+            - If False, skip 'iss' claim entirely.
+        iat: Whether to set the 'iat' (issued at) claim. If False, skip it.
+        exp: Whether to set the 'exp' claim. If False, skip it.
+        claims: Additional custom claims to merge into the token.
+        expiration_time: If exp is True, how many seconds from now until expiration.
+
+    Returns:
+        A RS256-signed JWT string.
+
+    Example usage:
+        token = generate_token(
+            domain="example.us.auth0.com",
+            user_id="user123",
+            audience="my-api",
+            issuer=False,
+            iat=False,
+            exp=False,
+            claims={"scope": "read:stuff"}
+        )
+    """
+    token_claims = dict(claims or {})
+    token_claims.setdefault("sub", user_id)
+
+    if iat:
+        token_claims["iat"] = int(time.time())
+
+    if exp:
+        token_claims["exp"] = int(time.time()) + expiration_time
+
+    if issuer is not False:
+        token_claims["iss"] = issuer if isinstance(issuer, str) else f"https://{domain}/"
+
+    if audience:
+        token_claims["aud"] = audience
+
+
+    key = JsonWebKey.import_key(PRIVATE_JWK)
+
+    header = {"alg": "RS256", "kid": PRIVATE_JWK["kid"]}
+    token = jwt.encode(header, token_claims, key)
+    return token

src/utils.py

@@ -0,0 +1,88 @@
+"""
+Utility functions for OIDC discovery and JWKS fetching (asynchronously) 
+using httpx or a custom fetch approach.
+"""
+
+import httpx
+import base64
+import json
+from typing import Any, Dict, Optional, Callable, Union
+
+async def fetch_oidc_metadata(
+    domain: str, 
+    custom_fetch: Optional[Callable[..., Any]] = None
+) -> Dict[str, Any]:
+    """
+    Asynchronously fetch the OIDC config from https://{domain}/.well-known/openid-configuration.
+    Returns a dict with keys like issuer, jwks_uri, authorization_endpoint, etc.
+    If custom_fetch is provided, we call it instead of httpx.
+    """
+    url = f"https://{domain}/.well-known/openid-configuration"
+    if custom_fetch:
+        response = await custom_fetch(url)
+        return response.json() if hasattr(response, "json") else response
+    else:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            return resp.json()
+
+
+async def fetch_jwks(
+    jwks_uri: str, 
+    custom_fetch: Optional[Callable[..., Any]] = None
+) -> Dict[str, Any]:
+    """
+    Asynchronously fetch the JSON Web Key Set from jwks_uri.
+    Returns the raw JWKS JSON, e.g. {'keys': [...]}
+
+    If custom_fetch is provided, it must be an async callable 
+    that fetches data from the jwks_uri.
+    """
+    if custom_fetch:
+        response = await custom_fetch(jwks_uri)
+        return response.json() if hasattr(response, "json") else response
+    else:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(jwks_uri)
+            resp.raise_for_status()
+            return resp.json()
+        
+
+async def get_unverified_header(token: Union[str, bytes]) -> dict:
+    """
+    Parse the first segment (header) of a JWT without verifying signature.
+    Ensures correct Base64 padding before decode to avoid garbage bytes.
+    """
+    if isinstance(token, bytes):
+        token = token.decode("utf-8")
+    try:
+        header_b64, _, _ = token.split(".", 2)
+    except ValueError:
+        raise ValueError("Not enough segments in token")
+    
+    header_b64 = remove_bytes_prefix(header_b64)
+
+    header_b64 = fix_base64_padding(header_b64)
+
+    header_data = base64.urlsafe_b64decode(header_b64)
+    return json.loads(header_data)
+
+
+
+def fix_base64_padding(segment: str) -> str:
+    """
+    If `segment`'s length is not a multiple of 4, add '=' padding 
+    so that base64.urlsafe_b64decode won't produce nonsense bytes.
+    No extra '=' added if length is already a multiple of 4.
+    """
+    remainder = len(segment) % 4
+    if remainder == 0:
+        return segment  # No additional padding needed
+    return segment + ("=" * (4 - remainder))
+
+def remove_bytes_prefix(s: str) -> str:
+    """If the string looks like b'eyJh...', remove the leading b' and trailing '."""
+    if s.startswith("b'"):
+        return s[2:]  # cut off the leading b'
+    return s