diff --git a/docs/docs/reference/openid.md b/docs/docs/reference/openid.md index f7b79e3b0..073cb8497 100644 --- a/docs/docs/reference/openid.md +++ b/docs/docs/reference/openid.md @@ -25,7 +25,7 @@ Sure, here is the reordered list presented in a table with three columns: Claim, |-------------|-----------------------------------------------------------|--------------------------------------| | iss | The issuer of the token. The full URL of the organization | `https://.semaphoreci.com` | | aud | The intended audience of the token. The full URL of the organization | `https://.semaphoreci.com` | -| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}` | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | +| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}`

**Note**: This field often exceeds Google Cloud's 127-byte limit for attribute mapping. For Google Cloud integration, use individual claims like `repo`, `branch`, or `prj` instead. | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | | exp | The UNIX timestamp when the token expires | `1660317851` | | iat | The UNIX timestamp when the token was issued | `1660317851` | | nbf | The UNIX timestamp before which the token is not valid | `1660317851` | diff --git a/docs/docs/using-semaphore/openid.md b/docs/docs/using-semaphore/openid.md index 617d992cf..56bb1abe9 100644 --- a/docs/docs/using-semaphore/openid.md +++ b/docs/docs/using-semaphore/openid.md @@ -206,9 +206,11 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att 2. Use the following template to grant Google Cloud access to the identity pool created in Step 1. - Replace: + **Note**: Google Cloud has a 127-byte limit for mapped attributes. Semaphore's JWT subject can exceed this limit, so we'll use shorter JWT claims for the mapping. + + Replace: - `` with your repository name, e.g. `web` - - `` with the branch that can access the cloud resources, e.g. `refs/heads/main` + - `` with the branch that can access the cloud resources, e.g. `main` - `` with your project name on Semaphore ```shell title="Grant access to the identity pool" @@ -217,10 +219,16 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att --workload-identity-pool=$POOL_ID \ --issuer-uri="$ISSUER_URI" \ --allowed-audiences="$ISSUER_URI" \ - --attribute-mapping="google.subject="semaphore::::" \ - --attribute-condition="'semaphore::::' == google.subject" + --attribute-mapping="google.subject=assertion.repo,google.branch=assertion.branch" \ + --attribute-condition="assertion.repo == '' && assertion.branch == '' && assertion.prj == ''" ``` + This configuration: + - Maps the repository name from the JWT to `google.subject` + - Maps the branch name from the JWT to `google.branch` + - Uses attribute conditions to verify the specific repository, branch, and project from the JWT claims + - Avoids the 127-byte limit by using shorter JWT claims instead of the full subject + @@ -238,10 +246,10 @@ Connecting to the pool allows Semaphore to impersonate your Google Cloud service 1. Define environment variables: - `` is the repository name, e.g. `web` - - `` is the branch, e.g. `refs/heads/main` + - `` is the branch, e.g. `main` ```shell - export SUBJECT="semaphore:::: + ## Reference Semaphore generates a unique OIDC token for every job. The token is injected into the job environment as a variable named `SEMAPHORE_OIDC_TOKEN`. @@ -23,7 +25,7 @@ Sure, here is the reordered list presented in a table with three columns: Claim, |-------------|-----------------------------------------------------------|--------------------------------------| | iss | The issuer of the token. The full URL of the organization | `https://.semaphoreci.com` | | aud | The intended audience of the token. The full URL of the organization | `https://.semaphoreci.com` | -| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}` | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | +| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}`

**Note**: This field often exceeds Google Cloud's 127-byte limit for attribute mapping. For Google Cloud integration, use individual claims like `repo`, `branch`, or `prj` instead. | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | | exp | The UNIX timestamp when the token expires | `1660317851` | | iat | The UNIX timestamp when the token was issued | `1660317851` | | nbf | The UNIX timestamp before which the token is not valid | `1660317851` | diff --git a/docs/versioned_docs/version-EE-1.3/using-semaphore/openid.md b/docs/versioned_docs/version-EE-1.3/using-semaphore/openid.md index 2fd554f20..56bb1abe9 100644 --- a/docs/versioned_docs/version-EE-1.3/using-semaphore/openid.md +++ b/docs/versioned_docs/version-EE-1.3/using-semaphore/openid.md @@ -14,6 +14,8 @@ OpenID Connect (OICD) allows you to establish a more secure trust relationship b ## Overview + + Semaphore users traditionally use [secrets](./secrets) to inject credentials or API keys in jobs that need to interact with cloud providers. Every time the CI pipeline needs to deploy an application or fetch resources from a Docker registry or S3 bucket, we need to supply a secret to authorize Semaphore to access your cloud. These long-lived credentials present a challenge to maintain security or face exposure to security threats. Access and usage of these secrets need to be carefully monitored. Secrets need to be regularly rotated and the provided access rights on the cloud should follow the principle of least privilege. @@ -204,9 +206,11 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att 2. Use the following template to grant Google Cloud access to the identity pool created in Step 1. - Replace: + **Note**: Google Cloud has a 127-byte limit for mapped attributes. Semaphore's JWT subject can exceed this limit, so we'll use shorter JWT claims for the mapping. + + Replace: - `` with your repository name, e.g. `web` - - `` with the branch that can access the cloud resources, e.g. `refs/heads/main` + - `` with the branch that can access the cloud resources, e.g. `main` - `` with your project name on Semaphore ```shell title="Grant access to the identity pool" @@ -215,10 +219,16 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att --workload-identity-pool=$POOL_ID \ --issuer-uri="$ISSUER_URI" \ --allowed-audiences="$ISSUER_URI" \ - --attribute-mapping="google.subject="semaphore::::" \ - --attribute-condition="'semaphore::::' == google.subject" + --attribute-mapping="google.subject=assertion.repo,google.branch=assertion.branch" \ + --attribute-condition="assertion.repo == '' && assertion.branch == '' && assertion.prj == ''" ``` + This configuration: + - Maps the repository name from the JWT to `google.subject` + - Maps the branch name from the JWT to `google.branch` + - Uses attribute conditions to verify the specific repository, branch, and project from the JWT claims + - Avoids the 127-byte limit by using shorter JWT claims instead of the full subject + @@ -236,10 +246,10 @@ Connecting to the pool allows Semaphore to impersonate your Google Cloud service 1. Define environment variables: - `` is the repository name, e.g. `web` - - `` is the branch, e.g. `refs/heads/main` + - `` is the branch, e.g. `main` ```shell - export SUBJECT="semaphore:::: + ## Reference Semaphore generates a unique OIDC token for every job. The token is injected into the job environment as a variable named `SEMAPHORE_OIDC_TOKEN`. @@ -23,7 +25,7 @@ Sure, here is the reordered list presented in a table with three columns: Claim, |-------------|-----------------------------------------------------------|--------------------------------------| | iss | The issuer of the token. The full URL of the organization | `https://.semaphoreci.com` | | aud | The intended audience of the token. The full URL of the organization | `https://.semaphoreci.com` | -| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}` | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | +| sub | The subject of the token. A combination of org, project, repository, and git reference for which this token was issued
Template:
`org::`
`project:{project-id}:`
`repo:{repo-name}:`
`ref_type:{branch or pr or tag}:`
`ref:{git_reference}`

**Note**: This field often exceeds Google Cloud's 127-byte limit for attribute mapping. For Google Cloud integration, use individual claims like `repo`, `branch`, or `prj` instead. | `org:{org-name}:`
`project:936a5312-a3b8-4921-8b3f-2cec8baac574:`
`repo:web:`
`ref_type:branch:`
`ref:refs/heads/main` | | exp | The UNIX timestamp when the token expires | `1660317851` | | iat | The UNIX timestamp when the token was issued | `1660317851` | | nbf | The UNIX timestamp before which the token is not valid | `1660317851` | diff --git a/docs/versioned_docs/version-EE/using-semaphore/openid.md b/docs/versioned_docs/version-EE/using-semaphore/openid.md index 2fd554f20..56bb1abe9 100644 --- a/docs/versioned_docs/version-EE/using-semaphore/openid.md +++ b/docs/versioned_docs/version-EE/using-semaphore/openid.md @@ -14,6 +14,8 @@ OpenID Connect (OICD) allows you to establish a more secure trust relationship b ## Overview + + Semaphore users traditionally use [secrets](./secrets) to inject credentials or API keys in jobs that need to interact with cloud providers. Every time the CI pipeline needs to deploy an application or fetch resources from a Docker registry or S3 bucket, we need to supply a secret to authorize Semaphore to access your cloud. These long-lived credentials present a challenge to maintain security or face exposure to security threats. Access and usage of these secrets need to be carefully monitored. Secrets need to be regularly rotated and the provided access rights on the cloud should follow the principle of least privilege. @@ -204,9 +206,11 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att 2. Use the following template to grant Google Cloud access to the identity pool created in Step 1. - Replace: + **Note**: Google Cloud has a 127-byte limit for mapped attributes. Semaphore's JWT subject can exceed this limit, so we'll use shorter JWT claims for the mapping. + + Replace: - `` with your repository name, e.g. `web` - - `` with the branch that can access the cloud resources, e.g. `refs/heads/main` + - `` with the branch that can access the cloud resources, e.g. `main` - `` with your project name on Semaphore ```shell title="Grant access to the identity pool" @@ -215,10 +219,16 @@ Next, we need to map fields from the Semaphore OIDC provider to Google Cloud att --workload-identity-pool=$POOL_ID \ --issuer-uri="$ISSUER_URI" \ --allowed-audiences="$ISSUER_URI" \ - --attribute-mapping="google.subject="semaphore::::" \ - --attribute-condition="'semaphore::::' == google.subject" + --attribute-mapping="google.subject=assertion.repo,google.branch=assertion.branch" \ + --attribute-condition="assertion.repo == '' && assertion.branch == '' && assertion.prj == ''" ``` + This configuration: + - Maps the repository name from the JWT to `google.subject` + - Maps the branch name from the JWT to `google.branch` + - Uses attribute conditions to verify the specific repository, branch, and project from the JWT claims + - Avoids the 127-byte limit by using shorter JWT claims instead of the full subject + @@ -236,10 +246,10 @@ Connecting to the pool allows Semaphore to impersonate your Google Cloud service 1. Define environment variables: - `` is the repository name, e.g. `web` - - `` is the branch, e.g. `refs/heads/main` + - `` is the branch, e.g. `main` ```shell - export SUBJECT="semaphore::::