Skip to content

Commit 1000771

Browse files
Copilotsunbryejc-clarksalilsub
authored
OIDC custom properties as claims [GA] (#60543)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: sunbrye <56200261+sunbrye@users.noreply.github.com> Co-authored-by: sunbrye <sunbrye@github.com> Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> Co-authored-by: Salil <salilsub@users.noreply.github.com>
1 parent 5dfa958 commit 1000771

2 files changed

Lines changed: 62 additions & 22 deletions

File tree

‎content/actions/concepts/security/openid-connect.md‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -120,43 +120,49 @@ For more information, see [AUTOTITLE](/actions/reference/openid-connect-referenc
120120

121121
## Using repository custom properties as OIDC claims
122122

123-
> [!NOTE]
124-
> This feature is currently in public preview and is subject to change.
123+
Organization and enterprise admins can include repository custom properties as claims in OIDC tokens. This enables attribute-based access control (ABAC) policies in your cloud provider, artifact registry, or secrets manager that are driven by repository metadata rather than hard-coded allow lists.
125124

126-
Organization and enterprise admins can include repository custom properties as claims in OIDC tokens. Once added, every repository in the organization or enterprise that has a value set for that custom property will automatically include it in its OIDC tokens, prefixed with `repo_property_`.
125+
### How custom property claims work
127126

128-
This allows you to create granular access policies that bind directly to your repository metadata, reducing configuration drift and eliminating the need to duplicate governance information across multiple systems.
127+
The end-to-end flow for using custom properties as OIDC claims is as follows:
128+
129+
1. **Define custom properties.** An organization or enterprise admin creates custom properties (for example, `business_unit`, `data_classification`, or `environment_tier`) and assigns values to repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) and [AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens).
130+
1. **Enable properties in OIDC tokens.** An organization or enterprise admin selects which custom properties should be included in OIDC tokens, using the settings UI or the REST API.
131+
1. **Claims appear automatically.** Every workflow run in a repository that has a value set for an enabled property will include that value in its OIDC token, prefixed with `repo_property_`. No workflow-level configuration changes are required.
132+
1. **Update cloud trust policies.** You update your cloud provider's trust conditions to evaluate the new `repo_property_*` claims, enabling fine-grained, attribute-based access decisions.
133+
134+
Because this builds on {% data variables.product.prodname_dotcom %}'s existing OIDC short-lived credential model, no long-lived secrets are required, and every token is scoped, auditable, and automatically rotated per workflow run.
129135

130136
### Prerequisites
131137

132-
* Custom properties must already be defined at the organization or enterprise level.
138+
* Custom properties must already be defined at the organization or enterprise level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).
133139
* You must be an organization admin or enterprise admin.
134140

135141
### Adding a custom property to OIDC token claims
136142

137143
To include a custom property in OIDC tokens, use the REST API or the settings UI for your organization or enterprise.
138144

139-
**Using the settings UI:** Navigate to your organization or enterprise's Actions OIDC settings page to view and manage which custom properties are included in OIDC tokens.
140-
141-
![Screenshot of the OIDC settings for an organization or enterprise.](/assets/images/help/actions/actions-oidc-settings.png)
145+
* **Using the settings UI:** Navigate to your organization or enterprise's Actions OIDC settings page to view and manage which custom properties are included in OIDC tokens.
142146

147+
* **Using the REST API:** Send a `POST` request to the `/orgs/{org}/actions/oidc/customization/properties/repo` endpoint to add a custom property to the OIDC token claims for your organization. For request parameters and full details, see the REST API documentation for managing OIDC custom properties: [AUTOTITLE](/rest/actions/oidc).
143148

144-
* **Using the REST API:** Send a `POST` request to add a custom property to the OIDC token claims for your organization:
149+
### Example OIDC token with custom properties
145150

146-
### Example OIDC token with a custom property
147-
148-
The following example shows an OIDC token that includes the `workspace_id` custom property:
151+
The following example shows an OIDC token that includes two custom properties: a single-select property `business_unit` and a string property `workspace_id`. Each custom property appears in the token with the `repo_property_` prefix.
149152

150153
```json
151154
{
152155
"sub": "repo:my-org/my-repo:ref:refs/heads/main",
153156
"aud": "https://github.com/my-org",
154157
"repository": "my-org/my-repo",
158+
"repository_owner": "my-org",
159+
"ref": "refs/heads/main",
160+
"repo_property_business_unit": "payments",
155161
"repo_property_workspace_id": "ws-abc123"
156162
}
157163
```
158164

159-
You can use the `repo_property_*` claims in your cloud provider's trust conditions to create flexible, attribute-based access control policies. For more information, see [AUTOTITLE](/actions/reference/openid-connect-reference#including-repository-custom-properties-in-oidc-tokens).
165+
You can use the `repo_property_*` claims in your cloud provider's trust conditions to create flexible, attribute-based access control policies. For more information about the claim format, supported property types, and limits, see [AUTOTITLE](/actions/reference/openid-connect-reference#including-repository-custom-properties-in-oidc-tokens).
160166

161167
{% endif %}
162168

‎content/actions/reference/security/oidc.md‎

Lines changed: 43 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -227,40 +227,74 @@ After this setting is applied, the JWT will contain the updated `iss` value. In
227227

228228
### Including repository custom properties in OIDC tokens
229229

230-
> [!NOTE]
231-
> This feature is currently in public preview and is subject to change.
232-
233-
Organization and enterprise admins can select repository custom properties to include as claims in Actions OIDC tokens. Once a custom property is added to the OIDC configuration, every repository in the organization or enterprise that has a value set for that property will automatically include it in its OIDC tokens. The property name appears in the token prefixed with `repo_property_`.
230+
Organization and enterprise admins can select repository custom properties to include as claims in {% data variables.product.prodname_actions %} OIDC tokens. Once a custom property is added to the OIDC configuration, every repository in the organization or enterprise that has a value set for that property will automatically include it in its OIDC tokens. The property name appears in the token prefixed with `repo_property_`.
234231

235232
This allows you to create attribute-based access control (ABAC) policies in your cloud provider that bind directly to your repository metadata, reducing configuration drift and eliminating the need to manage separate access configuration for each repository.
236233

234+
#### Claim format
235+
236+
Each enabled custom property appears as a separate claim in the OIDC token. The claim name is the property name prefixed with `repo_property_`.
237+
238+
| Custom property name | Claim name in OIDC token |
239+
| --- | --- |
240+
| `business_unit` | `repo_property_business_unit` |
241+
| `workspace_id` | `repo_property_workspace_id` |
242+
| `data_classification` | `repo_property_data_classification` |
243+
244+
#### Supported property types
245+
246+
The following custom property types are supported as OIDC claims. The value representation in the token depends on the property type.
247+
248+
| Property type | Example value in OIDC token | Notes |
249+
| --- | --- | --- |
250+
| String | `"repo_property_team": "platform-eng"` | Value appears as a plain string. |
251+
| Single select | `"repo_property_env_tier": "production"` | The selected option appears as a plain string. |
252+
| Multi select | `"repo_property_regions": "us-east-1,eu-west-1"` | Multiple selected values are joined into a single comma-separated string. |
253+
| True/false | `"repo_property_pci_compliant": "true"` | Boolean values appear as the string `"true"` or `"false"`. |
254+
255+
#### Multi-select value representation
256+
257+
When a repository has a multi-select custom property with multiple values selected, the values are joined into a single comma-separated string in the OIDC token. For example, if a repository has a `regions` property with the values `us-east-1` and `eu-west-1`, the claim appears as:
258+
259+
```json
260+
{
261+
"repo_property_regions": "us-east-1,eu-west-1"
262+
}
263+
```
264+
265+
When configuring trust policies in your cloud provider, use string matching or contains checks to evaluate multi-select claims.
266+
237267
#### Prerequisites for including custom properties
238268

239-
* Custom properties must already be defined at the organization or enterprise level.
269+
* Custom properties must already be defined at the organization or enterprise level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).
240270
* You must be an organization admin or enterprise admin.
241271
* After adding a custom property to the OIDC configuration, all repositories in the organization or enterprise that have a value set for that property will automatically include it in their OIDC tokens.
242272

243273
#### Adding a custom property to OIDC token claims
244274

245275
You can manage which custom properties are included in OIDC tokens using the settings UI or the REST API.
246276

247-
* **Using the settings UI:**
277+
* **Using the settings UI:**
248278

249279
Navigate to your organization's or enterprise's Actions OIDC settings to view and configure which custom properties are included in OIDC tokens.
250280

251281
* **Using the REST API:**
252282

253-
To add a custom property to your organization's or enterprise's OIDC token claims, use the REST API. For more information, see [AUTOTITLE](/rest/actions/oidc).
283+
To add a custom property to your organization's OIDC token claims, send a `POST` request to the appropriate OIDC custom-property inclusion endpoint. For example:
284+
* For an organization: `POST /orgs/{org}/actions/oidc/customization/properties/repo`
285+
* For an enterprise: `POST /enterprises/{enterprise}/actions/oidc/customization/properties/repo`
286+
For request parameters and full details, see the REST API documentation for managing OIDC custom properties: [AUTOTITLE](/rest/actions/oidc).
254287

255-
#### Example token with a custom property
288+
#### Example token with custom properties
256289

257-
After a custom property is added to the OIDC configuration, repositories with a value set for that property will include it in their tokens. In the following example, the `workspace_id` custom property appears as `repo_property_workspace_id` in the token:
290+
After a custom property is added to the OIDC configuration, repositories with a value set for that property will include it in their tokens. In the following example, two custom properties (`business_unit` and `workspace_id`) are included in the token:
258291

259292
```json
260293
{
261294
"sub": "repo:my-org/my-repo:ref:refs/heads/main",
262295
"aud": "https://github.com/my-org",
263296
"repository": "my-org/my-repo",
297+
"repo_property_business_unit": "payments",
264298
"repo_property_workspace_id": "ws-abc123"
265299
}
266300
```

0 commit comments

Comments
 (0)