id: OIDC Identity Generator

Warnings

• gotcha The library name `id` collides with Python's built-in `id()` function. Importing `import id` could shadow the built-in function or lead to confusion. Always use explicit imports like `from id import detect_credential` to prevent this conflict.
  Fix: Always import specific functions or classes from the `id` library (e.g., `from id import detect_credential`) instead of performing a wildcard or full module import.
• breaking Python 3.8 is no longer supported starting from version 1.6.0. The library now requires Python 3.9 or newer.
  Fix: Upgrade your Python environment to version 3.9 or higher to use `id` v1.6.0 and subsequent releases.
• breaking The internal dependency on `pydantic` was removed in version 1.5.0. If your project indirectly relied on `pydantic` being installed via `id`, this change could lead to `ModuleNotFoundError` if `pydantic` is not explicitly listed in your project's dependencies.
  Fix: If your application had an implicit dependency on `pydantic` through the `id` library, explicitly add `pydantic` to your project's `requirements.txt` or `pyproject.toml`.
• breaking Version 1.6.0 internally replaced the `requests` library with `urllib3` for HTTP operations. While this change might not directly affect users of `detect_credential`, applications that relied on `requests`' specific behavior (e.g., monkey-patching `requests`, or assumptions about `requests`' session management) when using the `id` library might experience unexpected changes.
  Fix: Review any code that might interact with `id`'s underlying HTTP client or relies on transitive `requests` behavior. Direct API calls to `detect_credential` are generally unaffected, but custom HTTP integrations might need adjustment.
• gotcha When detecting OIDC tokens in GitLab CI/CD environments, the token is provided via an environment variable. This variable is named `<AUD>_ID_TOKEN`, where `<AUD>` is the uppercased audience argument with all non-alphanumeric characters replaced by underscores, and leading digits also replaced by an underscore. Incorrectly forming this environment variable name will lead to token detection failure.
  Fix: Ensure the environment variable for GitLab OIDC tokens adheres to the `<AUD>_ID_TOKEN` naming convention based on your specified audience.

Install

• pip install id Install with pip

Imports

• detect_credential

  from id import detect_credential

  The 'id' namespace conflicts with Python's built-in `id()` function. Always import specific symbols like `detect_credential` to avoid name collisions and confusion.

Quickstart

This quickstart demonstrates how to programmatically detect an OIDC credential using the `detect_credential` function. It attempts to retrieve an OIDC token for a specified audience, falling back to a default if the `OIDC_AUDIENCE` environment variable is not set. It then prints the token if successful, or a message indicating no token was found or an error occurred.

from id import detect_credential
import os

audience = os.environ.get('OIDC_AUDIENCE', 'my-oidc-audience')

try:
    token = detect_credential(audience=audience)
    if token:
        print(f"Successfully detected OIDC token for audience '{audience}':\n{token}")
    else:
        print(f"No OIDC token detected for audience '{audience}' in the current environment.")
except Exception as e:
    print(f"An error occurred: {e}")