id: OIDC Identity Generator

1.6.1 verified Tue May 12 auth: no python install: verified

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.

pip install id

Common errors

error 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.

error 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.

error 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.

error 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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 18.8M

3.10 alpine (musl) - - 0.01s 18.8M

3.10 slim (glibc) wheel 1.6s 0.01s 19M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.02s 20.8M

3.11 alpine (musl) - - 0.03s 20.8M

3.11 slim (glibc) wheel 1.7s 0.02s 21M

3.11 slim (glibc) - - 0.02s 21M

3.12 alpine (musl) wheel - 0.02s 12.6M

3.12 alpine (musl) - - 0.03s 12.6M

3.12 slim (glibc) wheel 1.6s 0.02s 13M

3.12 slim (glibc) - - 0.02s 13M

3.13 alpine (musl) wheel - 0.01s 12.4M

3.13 alpine (musl) - - 0.02s 12.3M

3.13 slim (glibc) wheel 1.6s 0.01s 13M

3.13 slim (glibc) - - 0.01s 13M

3.9 alpine (musl) wheel - 0.01s 18.3M

3.9 alpine (musl) - - 0.01s 18.3M

3.9 slim (glibc) wheel 1.9s 0.01s 19M

3.9 slim (glibc) - - 0.01s 19M

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 last tested: 2026-04-24

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}")