| Name | verify-oidc-identity JSON |
| Version |
0.4.17
JSON |
| download |
| home_page | None |
| Summary | Verify OIDC JWT identity tokens using OIDC discovery |
| upload_time | 2025-01-30 19:11:49 |
| maintainer | None |
| docs_url | None |
| author | Rich Wareham |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python library to verify id tokens using OIDC discovery
[](https://pypi.org/p/verify-oidc-identity/)
[](https://github.com/rjw57/verify-oidc-identity/releases)
[](https://github.com/rjw57/verify-oidc-identity/actions/workflows/main.yml?query=branch%3Amain)
[OpenID connect][oidc] identity tokens are a popular choice for federating identity between
different systems without the need to share secrets. For example [Trusted publishing on
PyPI](https://docs.pypi.org/trusted-publishers/) 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](https://cloud.google.com/iam/docs/workload-identity-federation),
[AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles)
and
[Azure](https://learn.microsoft.com/en-us/graph/api/resources/federatedidentitycredentials-overview?view=graph-rest-1.0)
from any OIDC identity provider.
The [jwt.io](https://jwt.io/) and [jwt.ms](https://jwt.ms/) tools allow validating OIDC
id tokens without first configuring public keys by means of the [OpenID connect
discovery][oidc-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.
[oidc]: https://openid.net/specs/openid-connect-core-1_0.html
[oidc-discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html
## Example
Suppose you created a [GitLab OIDC
token](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html) as part of a
CI job to make an authenticated HTTP GET request to some service:
```yaml
# .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:
```py
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](https://rjw57.github.io/verify-oidc-identity/) for more
examples.
Raw data
{
"_id": null,
"home_page": null,
"name": "verify-oidc-identity",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Rich Wareham",
"author_email": "rich.verify-oidc-identity@richwareham.com",
"download_url": "https://files.pythonhosted.org/packages/c2/cb/45ee964ce4b1517f5aa953f5d9c8f6bdc74db8ccc7b5238a8969c76050b8/verify_oidc_identity-0.4.17.tar.gz",
"platform": null,
"description": "# Python library to verify id tokens using OIDC discovery\n\n[](https://pypi.org/p/verify-oidc-identity/)\n\n[](https://github.com/rjw57/verify-oidc-identity/releases)\n[](https://github.com/rjw57/verify-oidc-identity/actions/workflows/main.yml?query=branch%3Amain)\n\n[OpenID connect][oidc] identity tokens are a popular choice for federating identity between\ndifferent systems without the need to share secrets. For example [Trusted publishing on\nPyPI](https://docs.pypi.org/trusted-publishers/) allows use of OIDC tokens created by\nGitHub or GitLab CI jobs to be used to authenticate when uploading new Python packages.\nSimilarly, OIDC tokens can be used to authenticate to [Google\nCloud](https://cloud.google.com/iam/docs/workload-identity-federation),\n[AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles)\nand\n[Azure](https://learn.microsoft.com/en-us/graph/api/resources/federatedidentitycredentials-overview?view=graph-rest-1.0)\nfrom any OIDC identity provider.\n\nThe [jwt.io](https://jwt.io/) and [jwt.ms](https://jwt.ms/) tools allow validating OIDC\nid tokens without first configuring public keys by means of the [OpenID connect\ndiscovery][oidc-discovery] protocol.\n\nThis library implements the OpenID Connect discovery standard in Python to allow\nverification of OpenID Connect id tokens without previous configuration of public keys,\netc.\n\nBoth synchronous and asynchronous (`asyncio`) implementations are provided.\n\n[oidc]: https://openid.net/specs/openid-connect-core-1_0.html\n[oidc-discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html\n\n## Example\n\nSuppose you created a [GitLab OIDC\ntoken](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html) as part of a\nCI job to make an authenticated HTTP GET request to some service:\n\n```yaml\n# .gitlab-ci.yml within https://gitlab.com/my-group/my-project\n\njob_with_id_token:\n id_tokens:\n ID_TOKEN:\n aud: https://my-service.example.com\n script:\n - curl -X GET -H \"Authorization: Bearer $ID_TOKEN\" https://my-service.example.com\n```\n\nThe following example shows how to verify the OIDC token came from a specific project\nwithin a backend implementation:\n\n```py\nfrom typing import Any\nfrom federatedidentity import Issuer, verifiers, verify_id_token\n\n# Use OIDC discovery to fetch public keys for verifying GitLab tokens.\nGITLAB_ISSUER = Issuer.from_discovery(\"https://gitlab.com\")\n\n# Expected project path for id token\nEXPECTED_PROJECT_PATH = \"my-group/my-project\"\n\n# Expected audience claim for id token.\nEXPECTED_AUDIENCE_CLAIM = \"https://my-service.example.com\"\n\ndef verify_gitlab_token(token: str) -> dict[str, Any]:\n \"\"\"\n Verify an OIDC token from GitLab and return the dictionary of claims. Raises\n federatedidentity.exceptions.FederatedIdentityError if the token failed verification.\n \"\"\"\n return verify_id_token(\n token,\n valid_issuers=[GITLAB_ISSUER],\n valid_audiences=[EXPECTED_AUDIENCE_CLAIM],\n required_claims=[\n # The \"project_path\" claim must match the expected project.\n {\"project_path\": EXPECTED_PROJECT_PATH},\n ],\n )\n```\n\nSee [the full documentation](https://rjw57.github.io/verify-oidc-identity/) for more\nexamples.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Verify OIDC JWT identity tokens using OIDC discovery",
"version": "0.4.17",
"project_urls": {
"Changelog": "https://github.com/rjw57/verify-oidc-identity/blob/main/CHANGELOG.md",
"Documentation": "https://rjw57.github.io/verify-oidc-identity",
"Homepage": "https://github.com/rjw57/verify-oidc-identity",
"Issues": "https://github.com/rjw57/verify-oidc-identity/issues",
"Repository": "https://github.com/rjw57/verify-oidc-identity.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb8aedf546659f797e8f5cce00add63eeadce8e4d0d292eb750977783927ce4c",
"md5": "b30ebf1894ec2ad42d706aa962e29c00",
"sha256": "9b3f546d14cbfbda3af365cd52268a2e088210ded1d955df20a4c6a4a6e92fc1"
},
"downloads": -1,
"filename": "verify_oidc_identity-0.4.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b30ebf1894ec2ad42d706aa962e29c00",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 10544,
"upload_time": "2025-01-30T19:11:47",
"upload_time_iso_8601": "2025-01-30T19:11:47.098168Z",
"url": "https://files.pythonhosted.org/packages/bb/8a/edf546659f797e8f5cce00add63eeadce8e4d0d292eb750977783927ce4c/verify_oidc_identity-0.4.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2cb45ee964ce4b1517f5aa953f5d9c8f6bdc74db8ccc7b5238a8969c76050b8",
"md5": "0fc869f249114cbe0a3c7ba986fd57d0",
"sha256": "a9eaed804a37d203b926e4a7168276202ed48415463a2aa0bde20ef268502fa7"
},
"downloads": -1,
"filename": "verify_oidc_identity-0.4.17.tar.gz",
"has_sig": false,
"md5_digest": "0fc869f249114cbe0a3c7ba986fd57d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 7915,
"upload_time": "2025-01-30T19:11:49",
"upload_time_iso_8601": "2025-01-30T19:11:49.104553Z",
"url": "https://files.pythonhosted.org/packages/c2/cb/45ee964ce4b1517f5aa953f5d9c8f6bdc74db8ccc7b5238a8969c76050b8/verify_oidc_identity-0.4.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-30 19:11:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rjw57",
"github_project": "verify-oidc-identity",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "verify-oidc-identity"
}
