README.md

Python library to verify id tokens using OIDC discovery

OpenID connect identity tokens are a popular choice for federating identity between different systems without the need to share secrets. For example Trusted publishing on PyPI allows use of OIDC tokens created by GitHub or GitLab CI jobs to be used to authenticate when uploading new Python packages. Similarly, OIDC tokens can be used to authenticate to Google Cloud, AWS and Azure from any OIDC identity provider.

The jwt.io and jwt.ms tools allow validating OIDC id tokens without first configuring public keys by means of the OpenID connect discovery protocol.

This library implements the OpenID Connect discovery standard in Python to allow verification of OpenID Connect id tokens without previous configuration of public keys, etc.

Both synchronous and asynchronous (asyncio) implementations are provided.

Example

Suppose you created a GitLab OIDC token as part of a CI job to make an authenticated HTTP GET request to some service:

# .gitlab-ci.yml within https://gitlab.com/my-group/my-project

job_with_id_token:
  id_tokens:
    ID_TOKEN:
      aud: https://my-service.example.com
  script:
    - curl -X GET -H "Authorization: Bearer $ID_TOKEN" https://my-service.example.com

The following example shows how to verify the OIDC token came from a specific project within a backend implementation:

from typing import Any
from federatedidentity import Issuer, verifiers, verify_id_token

# Use OIDC discovery to fetch public keys for verifying GitLab tokens.
GITLAB_ISSUER = Issuer.from_discovery("https://gitlab.com")

# Expected project path for id token
EXPECTED_PROJECT_PATH = "my-group/my-project"

# Expected audience claim for id token.
EXPECTED_AUDIENCE_CLAIM = "https://my-service.example.com"

def verify_gitlab_token(token: str) -> dict[str, Any]:
    """
    Verify an OIDC token from GitLab and return the dictionary of claims. Raises
    federatedidentity.exceptions.FederatedIdentityError if the token failed verification.
    """
    return verify_id_token(
        token,
        valid_issuers=[GITLAB_ISSUER],
        valid_audiences=[EXPECTED_AUDIENCE_CLAIM],
        required_claims=[
            # The "project_path" claim must match the expected project.
            {"project_path": EXPECTED_PROJECT_PATH},
        ],
    )

See the full documentation for more examples.