id


Nameid JSON
Version 1.5.0 PyPI version JSON
download
home_pageNone
SummaryA tool for generating OIDC identities
upload_time2024-12-04 19:53:05
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            id
==

<!--- @begin-badges@ --->
![CI](https://github.com/di/id/workflows/CI/badge.svg)
[![PyPI version](https://badge.fury.io/py/id.svg)](https://pypi.org/project/id)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/di/id/badge)](https://api.securityscorecards.dev/projects/github.com/di/id)
[![SLSA](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev/)
<!--- @end-badges@ --->

`id` is a Python tool for generating OIDC identities. It can automatically
detect and produce OIDC credentials on a number of environments, including
GitHub Actions, GitLab pipelines and Google Cloud.

## Installation

`id` requires Python 3.8 or newer, and can be installed directly via `pip`:

```console
python -m pip install id
```

## Usage

You can run `id` as a Python module via `python -m`:

```console
python -m id --help
```

Top-level:

<!-- @begin-id-help@ -->
```
usage: id [-h] [-V] [-v] [-d] audience

a tool for generating OIDC identities

positional arguments:
  audience       the OIDC audience to use

optional arguments:
  -h, --help     show this help message and exit
  -V, --version  show program's version number and exit
  -v, --verbose  run with additional debug logging; supply multiple times to
                 increase verbosity (default: 0)
  -d, --decode   decode the OIDC token into JSON (default: False)
```
<!-- @end-id-help@ -->

For Python API usage, there is a single importable function, `detect_credential`:

```pycon
>>> from id import detect_credential
>>> detect_credential(audience='something')
'<OIDC token>'
```

This function requires an `audience` parameter, which is used when generating
the OIDC token. This should be set to the intended audience for the token.

If no supported environment is found, `detect_credential` returns `None`. If a supported
environment is found but `detect_credential` fails to retrieve a token, it raises
`AmbientCredentialError`.

## Supported environments

`id` currently supports ambient credential detection in the following environments:

* [GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
* Google Cloud
  * [Cloud Run](https://cloud.google.com/run/docs/securing/service-identity)
  * [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
  * [Compute Engine](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)
  * and more
* [Buildkite](https://buildkite.com/docs/agent/v3/cli-oidc)
* [GitLab](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html) (See _environment variables_ below)
* [CircleCI](https://circleci.com/docs/oidc-tokens-with-custom-claims/)

### Tokens in environment variables

GitLab provides OIDC tokens through environment variables. The variable name must be
`<AUD>_ID_TOKEN`  where `<AUD>` is the uppercased audience argument where all
characters outside of ASCII letters and digits are replaced with "\_". A leading digit
must also be replaced with a "\_".

## Licensing

`id` is licensed under the Apache 2.0 License.

## Contributing

See [the contributing docs](https://github.com/di/id/blob/main/CONTRIBUTING.md) for details.

### SLSA Provenance
This project emits a SLSA provenance on its release! This enables you to verify the integrity
of the downloaded artifacts and ensured that the binary's code really comes from this source code.

To do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verify-provenance).


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "id",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": null,
    "author": null,
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/22/11/102da08f88412d875fa2f1a9a469ff7ad4c874b0ca6fed0048fe385bdb3d/id-1.5.0.tar.gz",
    "platform": null,
    "description": "id\n==\n\n<!--- @begin-badges@ --->\n![CI](https://github.com/di/id/workflows/CI/badge.svg)\n[![PyPI version](https://badge.fury.io/py/id.svg)](https://pypi.org/project/id)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/di/id/badge)](https://api.securityscorecards.dev/projects/github.com/di/id)\n[![SLSA](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev/)\n<!--- @end-badges@ --->\n\n`id` is a Python tool for generating OIDC identities. It can automatically\ndetect and produce OIDC credentials on a number of environments, including\nGitHub Actions, GitLab pipelines and Google Cloud.\n\n## Installation\n\n`id` requires Python 3.8 or newer, and can be installed directly via `pip`:\n\n```console\npython -m pip install id\n```\n\n## Usage\n\nYou can run `id` as a Python module via `python -m`:\n\n```console\npython -m id --help\n```\n\nTop-level:\n\n<!-- @begin-id-help@ -->\n```\nusage: id [-h] [-V] [-v] [-d] audience\n\na tool for generating OIDC identities\n\npositional arguments:\n  audience       the OIDC audience to use\n\noptional arguments:\n  -h, --help     show this help message and exit\n  -V, --version  show program's version number and exit\n  -v, --verbose  run with additional debug logging; supply multiple times to\n                 increase verbosity (default: 0)\n  -d, --decode   decode the OIDC token into JSON (default: False)\n```\n<!-- @end-id-help@ -->\n\nFor Python API usage, there is a single importable function, `detect_credential`:\n\n```pycon\n>>> from id import detect_credential\n>>> detect_credential(audience='something')\n'<OIDC token>'\n```\n\nThis function requires an `audience` parameter, which is used when generating\nthe OIDC token. This should be set to the intended audience for the token.\n\nIf no supported environment is found, `detect_credential` returns `None`. If a supported\nenvironment is found but `detect_credential` fails to retrieve a token, it raises\n`AmbientCredentialError`.\n\n## Supported environments\n\n`id` currently supports ambient credential detection in the following environments:\n\n* [GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)\n* Google Cloud\n  * [Cloud Run](https://cloud.google.com/run/docs/securing/service-identity)\n  * [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)\n  * [Compute Engine](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)\n  * and more\n* [Buildkite](https://buildkite.com/docs/agent/v3/cli-oidc)\n* [GitLab](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html) (See _environment variables_ below)\n* [CircleCI](https://circleci.com/docs/oidc-tokens-with-custom-claims/)\n\n### Tokens in environment variables\n\nGitLab provides OIDC tokens through environment variables. The variable name must be\n`<AUD>_ID_TOKEN`  where `<AUD>` is the uppercased audience argument where all\ncharacters outside of ASCII letters and digits are replaced with \"\\_\". A leading digit\nmust also be replaced with a \"\\_\".\n\n## Licensing\n\n`id` is licensed under the Apache 2.0 License.\n\n## Contributing\n\nSee [the contributing docs](https://github.com/di/id/blob/main/CONTRIBUTING.md) for details.\n\n### SLSA Provenance\nThis project emits a SLSA provenance on its release! This enables you to verify the integrity\nof the downloaded artifacts and ensured that the binary's code really comes from this source code.\n\nTo do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verify-provenance).\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A tool for generating OIDC identities",
    "version": "1.5.0",
    "project_urls": {
        "Homepage": "https://pypi.org/project/id/",
        "Issues": "https://github.com/di/id/issues",
        "Source": "https://github.com/di/id"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9fcb18326d2d89ad3b0dd143da971e77afd1e6ca6674f1b1c3df4b6bec6279fc",
                "md5": "5b3c537482f1119131e0604f6b48d493",
                "sha256": "f1434e1cef91f2cbb8a4ec64663d5a23b9ed43ef44c4c957d02583d61714c658"
            },
            "downloads": -1,
            "filename": "id-1.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5b3c537482f1119131e0604f6b48d493",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 13611,
            "upload_time": "2024-12-04T19:53:03",
            "upload_time_iso_8601": "2024-12-04T19:53:03.020899Z",
            "url": "https://files.pythonhosted.org/packages/9f/cb/18326d2d89ad3b0dd143da971e77afd1e6ca6674f1b1c3df4b6bec6279fc/id-1.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2211102da08f88412d875fa2f1a9a469ff7ad4c874b0ca6fed0048fe385bdb3d",
                "md5": "0dfa778f2fc740c95abd990209aa0036",
                "sha256": "292cb8a49eacbbdbce97244f47a97b4c62540169c976552e497fd57df0734c1d"
            },
            "downloads": -1,
            "filename": "id-1.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0dfa778f2fc740c95abd990209aa0036",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 15237,
            "upload_time": "2024-12-04T19:53:05",
            "upload_time_iso_8601": "2024-12-04T19:53:05.575450Z",
            "url": "https://files.pythonhosted.org/packages/22/11/102da08f88412d875fa2f1a9a469ff7ad4c874b0ca6fed0048fe385bdb3d/id-1.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-04 19:53:05",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "di",
    "github_project": "id",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "circle": true,
    "lcname": "id"
}
        
Elapsed time: 1.00750s