jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-30 12:02:01 -05:00
Code Issues Projects Releases Wiki Activity

Repository level customisation for OpenID Connect configuration (#31706)

Browse Source
This commit is contained in:
Martin Lopes
2022-10-19 07:47:17 +10:00
committed by GitHub
parent 7fe89141b3
commit 5836957166
2 changed files with 20 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
content/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md
View File

@@ -279,19 +279,21 @@ After this setting is applied, the JWT will contain the updated `iss` value. In
{% endif %}
### Customizing the subject claims for an organization
### Customizing the subject claims for an organization or repository
To configure organization-wide security, compliance, and standardization, you can customize the standard claims to suit your required access conditions. If your cloud provider supports conditions on subject claims, you can create a condition that checks whether the `sub` value matches the path of the reusable workflow, such as `"job_workflow_ref: "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main""`. The exact format will vary depending on your cloud provider's OIDC configuration. To configure the matching condition on {% data variables.product.prodname_dotcom %}, you can can use the REST API to require that the `sub` claim must always include a specific custom claim, such as `job_workflow_ref`. For more information, see "[Set the customization template for an OIDC subject claim for an organization](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)."
To help improve security, compliance, and standardization, you can customize the standard claims to suit your required access conditions. If your cloud provider supports conditions on subject claims, you can create a condition that checks whether the `sub` value matches the path of the reusable workflow, such as `"job_workflow_ref: "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main""`. The exact format will vary depending on your cloud provider's OIDC configuration. To configure the matching condition on {% data variables.product.prodname_dotcom %}, you can can use the REST API to require that the `sub` claim must always include a specific custom claim, such as `job_workflow_ref`. You can use the [OIDC REST API](/rest/actions/oidc) to apply a customization template for the OIDC subject claim; for example, you can require that the `sub` claim within the OIDC token must always include a specific custom claim, such as `job_workflow_ref`.
Customizing the claims results in a new format for the entire `sub` claim, which replaces the default predefined `sub` format in the token described in "[Example subject claims](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims)."
The following example templates demonstrate various ways to customize the subject claim. To configure these settings on {% data variables.product.prodname_dotcom %}, organization admins use the REST API to specify a list of claims that must be included in the subject (`sub`) claim. {% data reusables.actions.use-request-body-api %}
The following example templates demonstrate various ways to customize the subject claim. To configure these settings on {% data variables.product.prodname_dotcom %}, admins use the REST API to specify a list of claims that must be included in the subject (`sub`) claim.
{% data reusables.actions.use-request-body-api %}
To customize your subject claims, you should first create a matching condition in your cloud provider's OIDC configuration, before customizing the configuration using the REST API. Once the configuration is completed, each time a new job runs, the OIDC token generated during that job will follow the new customization template. If the matching condition doesn't exist in the cloud provider's OIDC configuration before the job runs, the generated token might not be accepted by the cloud provider, since the cloud conditions may not be synchronized.
{% note %}
**Note**: When the organization template is applied, it will not affect any existing repositories that already use OIDC. For existing repositories, as well as any new repositories that are created after the template has been applied, the repository owner will need to opt-in to receive this configuration. For more information, see "[Set the opt-in flag of an OIDC subject claim customization for a repository](/rest/actions/oidc#set-the-opt-in-flag-of-an-oidc-subject-claim-customization-for-a-repository)."
**Note**: When the organization template is applied, it will not affect any action workflows in existing repositories that already use OIDC. For existing repositories, as well as any new repositories that are created after the template has been applied, the repository owner will need to opt-in to receive this configuration, or alternatively could apply a different configuration specific to the repo. For more information, see "[Set the customization template for an OIDC subject claim for a repository](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)."
{% endnote %}
@@ -312,7 +314,9 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re
#### Example: Allowing access to all repositories with a specific owner
This example template enables the `sub` claim to have a new format with only the value of `repository_owner`. {% data reusables.actions.use-request-body-api %}
This example template enables the `sub` claim to have a new format with only the value of `repository_owner`.
{% data reusables.actions.use-request-body-api %}
```json
{
@@ -343,7 +347,9 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re
#### Example: Requiring a reusable workflow and other claims
The following example template combines the requirement of a specific reusable workflow with additional claims. {% data reusables.actions.use-request-body-api %}
The following example template combines the requirement of a specific reusable workflow with additional claims.
{% data reusables.actions.use-request-body-api %}
This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the [default `sub` format](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). For example, when the job references an environment, the context contains: `environment:<environmentName>`.
@@ -380,7 +386,9 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re
#### Example: Using system-generated GUIDs
This example template enables predictable OIDC claims with system-generated GUIDs that do not change between renames of entities (such as renaming a repository). {% data reusables.actions.use-request-body-api %}
This example template enables predictable OIDC claims with system-generated GUIDs that do not change between renames of entities (such as renaming a repository).
{% data reusables.actions.use-request-body-api %}
```json
{
@@ -406,7 +414,9 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re
#### Resetting your customizations
This example template resets the subject claims to the default format. {% data reusables.actions.use-request-body-api %} This template effectively opts out of any organization-level customization policy.
This example template resets the subject claims to the default format. This template effectively opts out of any organization-level customization policy.
{% data reusables.actions.use-request-body-api %}
```json
{
@@ -421,7 +431,7 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re
#### Using the default subject claims
For repositories that can receive a subject claim policy from their organization, the repository owner can later choose to opt-out and instead use the default `sub` claim format. To configure this, the repository admin must use the REST API endpoint at "[Set the opt-out flag of an OIDC subject claim customization for a repository](/rest/actions/oidc#set-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository)" with the following request body:
For repositories that can receive a subject claim policy from their organization, the repository owner can later choose to opt-out and instead use the default `sub` claim format. To configure this, the repository admin must use the REST API endpoint at "[Set the customization template for an OIDC subject claim for a repository](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)" with the following request body:
```json
{

2
data/reusables/actions/use-request-body-api.md
View File

@@ -1 +1 @@
To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For more information, see "[Set the customization template for an OIDC subject claim for an organization](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)".
To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, see "[Set the customization template for an OIDC subject claim for an organization](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization), and for repositories, see "[Set the customization template for an OIDC subject claim for a repository](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)."