id: OIDC Identity Generator

1.6.1 · active · verified Thu Apr 09

id is a Python tool for generating OIDC identities, currently at version 1.6.1. It can automatically detect and produce OIDC credentials on various environments, including GitHub Actions, GitLab pipelines, and Google Cloud. The library maintains an active release cadence with frequent updates and improvements.

Common errors

```
ModuleNotFoundError: No module named 'id'
```
cause The 'id-oauth' library is not installed in the Python environment where the code is being executed.

fix Run `pip install id-oauth` in your terminal to install the library.
```
id.exceptions.EnvironmentError: Not running in a supported OpenID Connect environment.
```
cause The 'id-oauth' library failed to detect a recognized OIDC-enabled environment (e.g., GitHub Actions, GitLab CI, Google Cloud) or retrieve necessary environment variables.

fix Ensure your code is running within a supported CI/CD environment with the correct OIDC configuration. If testing locally, you might need to mock environment variables or explicitly provide credentials.
```
id.exceptions.OIDCError: OIDC audience must be provided for the current provider when requesting ID token.
```
cause The OpenID Connect audience parameter, which specifies the intended recipient of the ID token, was not supplied to the 'id-oauth' library for the detected OIDC provider.

fix Pass the `audience` parameter when calling the `id` library's token generation function or ensure it is set via the appropriate environment variable for your OIDC provider.
```
id.exceptions.ConfigurationError: Invalid issuer URL provided.
```
cause The OpenID Connect issuer URL specified for the identity provider is malformed, inaccessible, or does not point to a valid OIDC discovery endpoint.

fix Verify that the `oidc_issuer` URL is correct, includes the full scheme (e.g., `https://`), and is publicly accessible. Check for typos or network connectivity issues.

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
wrong:
```
import id
```
correct:
```
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}")

view raw JSON →