Merge pull request #48 from buildkite/oidc-policy-v2

Update docs for Package Registry OIDC Policies v2
buildkite · Oct 4, 2024 · 3b6b1b3 · 3b6b1b3
2 parents 3cd1ee3 + 621a287
commit 3b6b1b3
Show file tree

Hide file tree

Showing 7 changed files with 202 additions and 53 deletions.
diff --git a/pages/agent/v3/cli_oidc.md b/pages/agent/v3/cli_oidc.md
@@ -24,6 +24,8 @@ For specific endpoints for OpenID or JWKS, use:
 
 ## Claims
 
+All of the following claims (with the exception of the [`aud` claim](#aud), which is usually overridden by the [`--audience` option](#audience)) are automatically generated by the Buildkite Agent, and are based on metadata from the pipeline job it is currently building.
+
 <table data-attributes data-attributes-required>
   <thead>
     <tr>
@@ -53,7 +55,7 @@ For specific endpoints for OpenID or JWKS, use:
       <p><em>Example:</em><code>organization:acme-inc:pipeline:super-duper-app:ref:refs/heads/main:commit:9f3182061f1e2cca4702c368cbc039b7dc9d4485:step:build</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="aud">
     <td><code>aud</code></td>
     <td>
       <p>Audience</p>
@@ -63,7 +65,7 @@ For specific endpoints for OpenID or JWKS, use:
         --audience</code> flag</p>
     </td>
   </tr>
-   <tr>
+   <tr id="exp">
     <td><code>exp</code></td>
     <td>
       <p>Expiration time</p>
@@ -73,7 +75,7 @@ For specific endpoints for OpenID or JWKS, use:
       <p><em>Example:</em> <code>1669015898</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="nbf">
     <td><code>nbf</code></td>
     <td>
       <p>Not before</p>
@@ -82,7 +84,7 @@ For specific endpoints for OpenID or JWKS, use:
       <p><em>Example:</em> <code>1669014898</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="iat">
     <td><code>iat</code></td>
     <td>
       <p>Issued at</p>
@@ -91,14 +93,14 @@ For specific endpoints for OpenID or JWKS, use:
       <p><em>Example:</em> <code>1669014898</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="organization-slug">
     <td><code>organization_slug</code></td>
     <td>
       <p>The organization's slug.</p>
       <p><em>Example:</em> <code>acme-inc</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="pipeline-slug">
     <td><code>pipeline_slug</code></td>
     <td>
       <p>The pipeline's slug.</p>
@@ -112,7 +114,7 @@ For specific endpoints for OpenID or JWKS, use:
       <p><em>Example:</em> <code>1</code></p>
     </td>
   </tr>
-   <tr>
+   <tr id="build-branch">
     <td><code>build_branch</code></td>
     <td>
       <p>The repository branch used in the build.</p>
@@ -161,7 +163,21 @@ For specific endpoints for OpenID or JWKS, use:
 
 ### Optional claims
 
-Generate these additional claims by adding `--claims` to the `buildkite-agent oidc request-token` command.
+You can generate additional optional claims by adding `--claims` to the `buildkite-agent oidc request-token` command. The `--claims` option can also take multiple values.
+
+For example, this command adds the Buildkite organization's UUID value as a claim to the OIDC token:
+
+```sh
+$ buildkite-agent oidc request-token ... --claim "organization_id"
+```
+
+This command adds both the Buildkite organization's UUID and pipeline's UUID values in their own additional claims to the OIDC token:
+
+```sh
+$ buildkite-agent oidc request-token ... --claim "organization_id,pipeline_id"
+```
+
+The following optional claims can be added, whose values are automatically generated by the Buildkite Agent, and are based on the pipeline job it is currently building.
 
 <table data-attributes data-attributes-required>
   <thead>

diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md
@@ -11,8 +11,19 @@ curl -H "Authorization: Bearer $TOKEN" \
   -d '{
     "name": "my registry",
     "ecosystem": "ruby",
-    "description": "registry containing ruby gems"
-    }'
+    "description": "registry containing ruby gems",
+    "oidc_policy": [
+      {
+        "iss": "https://agent.buildkite.com",
+        "claims": {
+          "organization_slug": "my-org",
+          "pipeline_slug": {
+            "in": ["my-pipeline", "my-other-pipeline"]
+          }
+        }
+      }
+    ]
+  }'
 ```
 
 ```json
@@ -46,6 +57,7 @@ Optional [request body properties](/docs/api#request-body-properties):
 <table class="responsive-table">
   <tbody>
     <tr><th><code>description</code></th><td>Description of the registry.<br><em>Default value:</em> <code>null</code>.</td></tr>
+    <tr><th><code>oidc_policy</code></th><td>A policy matching a <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-basic-oidc-policy-format">basic</a> or <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-complex-oidc-policy-example">more complex</a> OIDC policy format. Can be either stringified YAML, or a JSON array of policy statements.<br><em>Default value:</em> <code>null</code>.</td></tr>
   </tbody>
 </table>
 
@@ -123,8 +135,19 @@ curl -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "my registry",
-    "description": "registry containing ruby gems"
-    }' 
+    "description": "registry containing ruby gems",
+    "oidc_policy": [
+      {
+        "iss": "https://agent.buildkite.com",
+        "claims": {
+          "organization_slug": "my-org",
+          "pipeline_slug": {
+            "in": ["my-pipeline"]
+          }
+        }
+      }
+    ]
+  }'
 ```
 
 ```json
@@ -150,6 +173,7 @@ Optional [request body properties](/docs/api#request-body-properties):
   <tbody>
     <tr><th><code>name</code></th><td>Name of the registry.<br><em>Example:</em> <code>my registry</code>.</td></tr>
     <tr><th><code>description</code></th><td>Description of the registry.<br><em>Example:</em> <code>registry containing ruby gems</code>.</td></tr>
+    <tr><th><code>oidc_policy</code></th><td>A policy matching a <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-basic-oidc-policy-format">basic</a> or <a href="/docs/packages/security/oidc#define-an-oidc-policy-for-a-registry-complex-oidc-policy-example">more complex</a> OIDC policy format. Can be either stringified YAML, or a JSON array of policy statements. Be aware that if you are modifying an existing OIDC policy, the entire revised OIDC policy needs to be re-posted in this update request.<br><em>Default value:</em> <code>null</code>.</td></tr>
   </tbody>
 </table>
 

diff --git a/pages/packages/permissions.md b/pages/packages/permissions.md
@@ -96,8 +96,4 @@ From this page, you can configure the following permissions for all users across
 
 ## Manage an agent's access to registries
 
-To configure the rules by which a Buildkite Agent can access a registry, you'll need to configure the OpenID Connect (OIDC) policy within the registry to allow the Buildkite Agent to request an OIDC token (using the [`buildkite-agent oidc request-token`](/docs/agent/v3/cli-oidc#request-oidc-token) command).
-
-<!--
-Learn more about this process in [Configure a registry's OIDC policy](/docs/packages/manage-registries#configure-a-registrys-oidc-policy).
--->
+To configure the rules by which a Buildkite Agent can access a registry, you'll need to configure the [OpenID Connect (OIDC) policy](/docs/packages/security/oidc) within the registry to allow the Buildkite Agent to request an OIDC token (using the [`buildkite-agent oidc request-token`](/docs/agent/v3/cli-oidc#request-oidc-token) command).