{"id":24234930,"url":"https://github.com/jenkinsci/oidc-provider-plugin","last_synced_at":"2026-02-17T16:03:08.269Z","repository":{"id":37893422,"uuid":"475776036","full_name":"jenkinsci/oidc-provider-plugin","owner":"jenkinsci","description":"OpenID Connect Provider Plugin for Jenkins","archived":false,"fork":false,"pushed_at":"2026-02-09T07:15:21.000Z","size":240,"stargazers_count":23,"open_issues_count":24,"forks_count":20,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-02-11T19:04:58.774Z","etag":null,"topics":["aws","google-cloud","security"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/oidc-provider/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-30T07:54:13.000Z","updated_at":"2026-02-09T07:15:25.000Z","dependencies_parsed_at":"2025-02-12T15:41:18.608Z","dependency_job_id":"50817d9a-df93-4c6d-8385-1e7cc75b3976","html_url":"https://github.com/jenkinsci/oidc-provider-plugin","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/jenkinsci/oidc-provider-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Foidc-provider-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Foidc-provider-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Foidc-provider-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Foidc-provider-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/oidc-provider-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Foidc-provider-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29549225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T14:33:00.708Z","status":"ssl_error","status_checked_at":"2026-02-17T14:32:58.657Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","google-cloud","security"],"created_at":"2025-01-14T17:38:45.731Z","updated_at":"2026-02-17T16:03:08.263Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenID Connect Provider Plugin\n\n## Introduction\n\nThis plugin allows Jenkins builds to be issued “id tokens” in a JSON Web Token (JWT) format\naccording to OpenID Connect (OIDC) Discovery conventions.\nThe purpose is to permit Jenkins to authenticate keylessly to external systems such as AWS or GCP.\n\nFor example, if you wished to access GCP services (such as to deploy to Cloud Run),\nyou could create a long-lived static service account key and store this secret inside Jenkins.\nBut anyone who manages to steal the secret value could quietly access GCP on their own,\nso you would need to periodically rotate the secret and institute special controls over its usage.\nSome organizations may even prohibit you from creating such static keys at all.\n\nOr if Jenkins itself were running on GCP (say in a GKE cluster),\nyou could configure “workload identity” so that the Jenkins agent process is preauthenticated\nto be able to use a specific service account.\nThis is more secure and manageable.\nIt only works within the one vendor, however.\n\nUsing OIDC, you can instead rely on what is sometimes referred to as “web identity federation”.\nRather than a secret value, what the external service trusts is that\nthe Jenkins administrator is in control over what is served from the known (HTTPS) URL.\nInternally Jenkins maintains an asymmetric cryptographic keypair.\nBuilds receive a temporary (timestamped) id token signed with the private key;\nJenkins serves the public key (anonymously) for anyone to verify the authenticity of the tokens.\nThe service might trust any token from Jenkins,\nor might match specific “claims” such as the identity of the project or Git branch name.\n\nAs a special case, the service being accessed may in fact be a secret store such as Vault or Conjur.\nThen the Jenkins build can use its id token to access the secret store and retrieve a secret,\nwhich _then_ can be used to access something else\nsuch as a database which only supports traditional passwords.\nThe advantage is that the database password need not be stored in the Jenkins controller\n(it would only be used transiently by an agent process),\nso administrators can apply audit controls, rotation policies, etc. in a full-featured storage service.\n\nThe [Conjur Secrets plugin](https://plugins.jenkins.io/conjur-credentials/)\nuses a similar system, tailored specifically to Conjur.\nThe [OpenId Connect Authentication plugin](https://plugins.jenkins.io/oic-auth/)\nallows OIDC to be used to authenticate users _to_ Jenkins and is completely unrelated to this use case.\n\n## Configuring\n\nSetting up keyless authentication requires a few steps.\n\n### Picking an issuer\n\nFirst, decide what the “issuer” of the tokens should be.\nBy default, Jenkins itself will issue tokens.\nThis is appropriate if it served from an HTTPS URL visible to the Internet\n(or at least the relevant vendor service).\n\nIf the service cannot physically access Jenkins,\nyou may instead designate another issuer URI.\nIn this case you must find a way to host two small, static JSON files under that URL.\nJenkins will still sign id tokens with its private key;\nthe public key, which does not normally change, gets served by the alternate issuer.\n(The `iss` claim in the id token will also be updated to match.)\n\n### Creating Jenkins credentials\n\nIn Jenkins, create one of two types of credentials:\n* **OpenID Connect id token** (yields the id token directly as “secret text”)\n* **OpenID Connect id token as file** (saves the id token to a temporary file and yields its path)\n\nThe credentials id is recommended for scripted access in your pipelines, or you may let one be chosen at random.\nYou may enter an audience URI at this time (see below) but it is optional.\n\nThe credential may be created at the Jenkins root, or in a folder. If you leave the field empty, it will create\nthe credential at the root, typically under the URI `https://YOUR_JENKINS_HOST/oidc`\nAfter saving, click on the **Update** Link to see the generated issuer URI.\nIf you picked the external issuer option or entered any value in the issuer URI field,\nyou will be given instructions on what static files to serve from it and their values.\n\nTo rotate the keypair, simply **Update** and re-**Save** (or otherwise recreate) the credentials.\n\n### Registering the identity provider\n\nRefer to service-specific documentation for creating an “identity provider” or “pool” etc.\nYou will need to enter at least the issuer URI.\nYou may ask the service to recognize a particular “audience” URI,\nor the service may specify an audience you should use.\nThe service may allow authorization decisions to be made based on various claims:\nthe `iss` (issuer),\nthe `aud` (audience),\nthe `sub` (subject—in this context, by default the URL of a Jenkins job),\nor others (currently a Jenkins build number is included by default).\n\nThe service may associate an identity provider with a service account, role, etc.\nThis is normally how specific privileges for specific objects are granted.\n\n### Use id tokens from builds\n\nWhen the id token credentials are accessed during a build\n(typically via the [Credentials Binding plugin](https://plugins.jenkins.io/credentials-binding/)),\nJenkins will generate a fresh id token scoped to that build with a limited validity.\nRefer to service-specific documentation to see how the token can be used to authenticate.\n\n### Configuring claims\n\nIf the default claims are not sufficient, you can customize them.\nGo to **Manage Jenkins** » **Configure Global Security**\nand under **OpenID Connect** edit the **Claim templates…** to your liking.\n\nEach template represent a claim (JSON property) to be set in id tokens.\nYou must include at least \u003ccode\u003esub\u003c/code\u003e (subject) in the list.\nThe value may be a fixed string, or it may be use substitutions from build variables.\nFor example, `jenkins:${BRANCH_NAME}:${BUILD_NUMBER}` might expand to `jenkins:master:123`.\nNormally the claim will be set to a **string** but you may choose a **boolean** (`true` or `false`)\nor an **integer** if you prefer these types in the JWT.\n\nYou can add claims to all id tokens, those used during builds,\nor those used outside of builds (for example by other Jenkins plugins accepting string credentials).\nAll applicable kinds of claim templates will be merged.\n\n## Examples\n\nSome tested usage examples follow. Please contribute others!\n\n### Accessing AWS\n\nYou will need to create a web identity federation provider,\nincluding a role with a trust policy offering `sts:AssumeRoleWithWebIdentity`\nand a permissions policy granting specific abilities.\nThe audience should conventionally be `sts.amazonaws.com`.\nAWS requires the TLS certificate fingerprint of the issuer to be saved.\n\nHere is an example of such trust policy with account `1234567890` and Jenkins instance running on `https://jenkins.acme.com/`, using the default issuer URL, restricting access to a job named `my-job`:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Principal\": {\n                \"Federated\": \"arn:aws:iam::1234567890:oidc-provider/jenkins.acme.com/oidc\"\n            },\n            \"Action\": \"sts:AssumeRoleWithWebIdentity\",\n            \"Condition\": {\n                \"StringEquals\": {\n                    \"jenkins.acme.com/oidc:aud\": \"sts.amazonaws.com\",\n                    \"jenkins.acme.com/oidc:sub\": \"https://jenkins.acme.com/job/my-job/\"\n                }\n            }\n        }\n    ]\n}\n```\n\nIf you set the environment variable `AWS_ROLE_ARN`\nand bind `AWS_WEB_IDENTITY_TOKEN_FILE` to a temporary file containing an id token,\nyou can run `aws` CLI commands without further ado.\nEvery time the role is assumed, AWS contacts the issuer to retrieve the public key.\n\nA fully automated, end-to-end demo is available.\nThis also demonstrates configuration of Jenkins as code.\nSee [instructions](demo/aws/README.md).\n\n### Accessing GCP\n\nYou will create a workload identity pool and bind it to a service account\n(which should have already been created with the desired permissions).\nSketch of setup:\n\n```bash\nISSUER=https://jenkins/oidc\nPROJECT=12345678\nPOOL=your-pool-name\nPROVIDER=static\nSA=some-sa@your-project.iam.gserviceaccount.com\ngcloud iam workload-identity-pools create $POOL \\\n  --location=global\ngcloud iam workload-identity-pools providers create-oidc $PROVIDER \\\n  --workload-identity-pool=$POOL \\\n  --issuer-uri=$ISSUER \\\n  --location=global \\\n  --attribute-mapping=google.subject=assertion.sub\ngcloud iam service-accounts add-iam-policy-binding $SA \\\n  --role=roles/iam.workloadIdentityUser \\\n  --member=\"principalSet://iam.googleapis.com/projects/$PROJECT/locations/global/workloadIdentityPools/$POOL/*\"\necho audience must be https://iam.googleapis.com/projects/$PROJECT/locations/global/workloadIdentityPools/$POOL/providers/$PROVIDER\n```\n\nUsing the id token is currently more awkward than from AWS, unfortunately.\nSketch of usage from a build:\n\n```groovy\nwithCredentials([file(variable: 'ID_TOKEN_FILE', credentialsId: 'gcp')]) {\n  writeFile file: \"$WORKSPACE_TMP/creds.json\", text: \"\"\"\n    {\n      \"type\": \"external_account\",\n      \"audience\": \"//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/your-pool-name/providers/static\",\n      \"subject_token_type\": \"urn:ietf:params:oauth:token-type:jwt\",\n      \"token_url\": \"https://sts.googleapis.com/v1/token\",\n      \"service_account_impersonation_url\": \"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/some-sa@your-project.iam.gserviceaccount.com:generateAccessToken\",\n      \"credential_source\": {\n        \"file\": \"$ID_TOKEN_FILE\",\n        \"format\": {\n          \"type\": \"text\"\n        }\n      }\n    }\n  \"\"\"\n  sh '''\n    gcloud auth login --brief --cred-file=$WORKSPACE_TMP/creds.json\n    gcloud --project your-project run deploy …\n  '''\n}\n```\n\nGCP contacts the issuer periodically (every few minutes) to retrieve the public key,\nwhether or not the pool is in use.\n(Your access log will show the user agent as `google-thirdparty-credentials`.)\nGCP seems to tolerate any TLS certificate that can validate against a root chain.\n\n### Accessing HashiCorp Vault\n\nYou will enable and configure `jwt` authentication and use a role for a specific pipeline job.\nThis way access to required secrets can be granted on a job level.\nThe pipeline will exchange the JWT against a Vault token and then use that token to access a secret.\nIn this example the ID token (JWT) credential will be created in a folder.\n\nAssume there is a kv v2 secret `my-secret` with the secret engine mounted at `kv` and a policy\n`my-policy` granting read capability to this secret.\n\nIn Jenkins, in folder `oidc-folder`, create an `OpenID Connect id token` credential with ID `id-token`.\nCopy the `Issuer URI`.\n\nIn the same folder, create a pipeline job `oidc-job`:\n\n```groovy\npipeline {\n  agent {\n    kubernetes {\n      yaml '''\n        apiVersion: v1\n        kind: Pod\n        spec:\n          containers:\n          - name: vault\n            image: hashicorp/vault\n            command:\n            - cat\n            tty: true\n      '''\n    }\n  }\n\n  stages {\n    stage('vault') {\n      environment {\n        VAULT_ADDR=\"\u003cVault API server address\u003e\"\n        VAULT_NAMESPACE=\"\u003conly for Vault Enterprise / HCP, remove otherwise\u003e\"\n      }\n      steps {\n        withCredentials([string(credentialsId: 'id-token', variable: 'IDTOKEN')]) {\n          container('vault') {\n            sh 'vault write -field=token auth/jwt/login jwt=${IDTOKEN} \u003e token'\n            sh 'set +x ; VAULT_TOKEN=$(cat token) vault read -field=data -format=json kv/data/my-secret'\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nConfigure Vault:\n```bash\nvault auth enable jwt\nvault write auth/jwt/role/my-role name=my-role role_type=jwt policies=my-policy \\\n    bound_subject=\"https://jenkins/job/oidc-folder/job/oidc-job/\" user_claim=sub\nvault write auth/jwt/config oidc_discovery_url=\"\u003cIssuer URI\u003e\" \\\n    bound_issuer=\"\u003cIssuer URI\u003e\" default_role=my-role\n```\n\n## References\n\nSome relevant background reading. Not intended to be exhaustive.\n\n### AWS\n\n* [About web identity federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)\n\n### GCP\n\n* [Introductory video](https://youtu.be/4vajaXzHN08)\n* [Workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation) (introduction)\n* [Access resources from an OIDC identity provider](https://cloud.google.com/iam/docs/configuring-workload-identity-federation#oidc) (detailed guide)\n\n### Security considerations\n\n* [Tweet re: workload identity vs. “sops”](https://twitter.com/lorenc_dan/status/1420188842703958020) (from a founder/CEO of Chainguard, active in supply-chain security)\n* [Article on Codecov credentials leak](https://www.theregister.com/2021/04/19/codecov_warns_of_stolen_credentials/)\n\n### Analogous features in other CI systems\n\n* [GitHub Actions: Secure cloud deployments with OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/)\n* [Connecting Bitbucket to resources via OIDC](https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/)\n* [Connecting GitLab to Vault via OIDC](https://docs.gitlab.com/ee/ci/examples/authenticating-with-hashicorp-vault/)\n\n### Secret stores accessible ultimately via OIDC\n\n* [AWS](https://aws.amazon.com/secrets-manager/)\n* [GCP](https://cloud.google.com/secret-manager)\n* [CyberArk Conjur: OIDC Authenticator](https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/OIDC/OIDC.htm)\n* [Using JWT/OIDC from Vault](https://www.vaultproject.io/docs/auth/jwt)\n\n## LICENSE\n\nLicensed under MIT, see [LICENSE](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Foidc-provider-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Foidc-provider-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Foidc-provider-plugin/lists"}