From 4a73c870e624577f109e85edfc489d57a36970e5 Mon Sep 17 00:00:00 2001 From: Sathvik Kumar Date: Mon, 27 Apr 2026 17:41:43 +1000 Subject: [PATCH] Document OIDC subject claim drop-when-empty behaviour Clarifies that requested subject keys with no value in the current execution context (e.g. tenant on an untenanted deployment) are omitted entirely from the generated subject - both key and value - not just left with an empty value. Customers configuring AWS IAM trust policies for untenanted projects had to discover this by trial and error. Replaces the single 'default format' line with the default keys plus both the tenanted and untenanted resulting subjects, adds the missing Project Group key part, removes Feed from the Deployments and Runbooks allowed parts (Feed has its own subject config), and adds a tenanted/untenanted example pair to the AWS account doc. --- .../docs/infrastructure/accounts/aws/index.md | 17 +++++++++++--- .../infrastructure/accounts/openid-connect.md | 22 ++++++++++++------- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/src/pages/docs/infrastructure/accounts/aws/index.md b/src/pages/docs/infrastructure/accounts/aws/index.md index e2e9e6a537..36a5d71689 100644 --- a/src/pages/docs/infrastructure/accounts/aws/index.md +++ b/src/pages/docs/infrastructure/accounts/aws/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-08-18 +modDate: 2026-04-27 title: AWS accounts description: Configure your infrastructure so Octopus can deploy infrastructure to AWS and run scripts against the AWS CLI. navOrder: 20 @@ -82,7 +82,7 @@ Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/op By default, the role trust policy does not have any conditions on the subject identifier. To lock the role down to particular usages you need to modify the [trust policy conditions](https://oc.to/aws-iam-policy-conditions) and add a condition for the `sub`. -For example, to lock an identity role to a specific Octopus environment, you can update the conditions: +For example, to lock an identity role to a specific Octopus environment for an untenanted deployment, you can update the conditions: ```json "Condition": { @@ -93,7 +93,18 @@ For example, to lock an identity role to a specific Octopus environment, you can } ``` -`default`, `aws-oidc-testing` and `dev` are the slugs of their respective Octopus resources. +`default`, `aws-oidc-testing`, and `dev` are the slugs of their respective Octopus resources. The `tenant:` segment is omitted because this deployment has no tenant value — when a selected subject key has no value at runtime, both the key and the value are dropped from the subject. + +For a tenanted deployment, the subject also includes the tenant slug: + +```json +"Condition": { + "StringEquals": { + "example.octopus.app:sub": "space:default:project:aws-oidc-testing:tenant:acme:environment:dev", + "example.octopus.app:aud": "example.octopus.app" + } +} +``` AWS policy conditions also support complex matching with wildcards and `StringLike` expressions. diff --git a/src/pages/docs/infrastructure/accounts/openid-connect.md b/src/pages/docs/infrastructure/accounts/openid-connect.md index a5809c4dd1..ad0d56a094 100644 --- a/src/pages/docs/infrastructure/accounts/openid-connect.md +++ b/src/pages/docs/infrastructure/accounts/openid-connect.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-09-22 -modDate: 2025-03-28 +modDate: 2026-04-27 title: OpenID Connect description: How to customize the Subject Claim for OpenID Connect authentication navOrder: 70 @@ -41,11 +41,13 @@ The subject can be modified for the three different uses within Octopus: ### Subject key parts -- Only the requested keys for a **Subject** claim will be include in the generated **Subject** claim -- Any Octopus resource types included in the **Subject** claim will use the slug value for the Octopus resource. The slug value is generated from the name of the Octopus resource when it was created, it can be edited on the edit page of resource type. +- Only the requested keys for a **Subject** claim will be included in the generated **Subject** claim. +- Any Octopus resource types included in the **Subject** claim will use the slug value for the Octopus resource. The slug value is generated from the name of the Octopus resource when it was created, and it can be edited on the edit page of the resource type. +- If a requested key has no value (for example, **Tenant** on an untenanted deployment, or **Runbook** on a deployment), both the key and the value are dropped from the **Subject** claim. - The **Subject** claim parts will always be in the following order: - **Space** - **Project** + - **Project Group** - **Runbook** - **Tenant** - **Environment** @@ -60,21 +62,25 @@ The **Subject** claim for a deployment or a runbook supports the following parts - **Space** slug - **Project** slug +- **Project Group** slug - **Runbook** slug - **Tenant** slug - **Environment** slug - **Account** slug - **Type** -- **Feed** slug -The default format for a deployment and runbook is `space:[space-slug]:project:[project-slug]:tenant:[tenant-slug]:environment:[environment-slug]`. +The default keys for a deployment and runbook are **Space**, **Project**, **Tenant**, and **Environment**. For a tenanted deployment, this produces `space:[space-slug]:project:[project-slug]:tenant:[tenant-slug]:environment:[environment-slug]`. For an untenanted deployment, the **Tenant** segment is dropped, giving `space:[space-slug]:project:[project-slug]:environment:[environment-slug]`. The value for the type is either `deployment` or `runbook`. When changing the **Subject** claim format for a deployment and runbook, the runbook value will not be included (if specified) when running a deployment. -For example, in the **Default** space, you have a project called **Deploy Web App**, and a runbook called **Restart**. If you set the **Subject** claim format to `space`, `project`, `runbook` and `type`, when running a deployment the **Subject** claim will be `space:default:project:deploy-web-app:type:deployment` and for the run of the runbook the **Subject** claim would be `space:default:project:deploy-web-app:runbook:restart:type:runbook`. -This is using the default generated slug values for the space, project and runbook. +For example, in the **Default** space, you have a project called **Deploy Web App**, and a runbook called **Restart**. If you set the **Subject** claim format to `space`, `project`, `runbook` and `type`, when running a deployment the **Subject** claim will be `space:default:project:deploy-web-app:type:deployment`, and for the run of the runbook the **Subject** claim would be `space:default:project:deploy-web-app:runbook:restart:type:runbook`. +This is using the default generated slug values for the space, project, and runbook. + +:::div{.warning} +Make sure your cloud provider's trust policy matches the **Subject** your deployments actually produce (tenanted or untenanted, deployment or runbook), not just the keys you selected. +::: ## Health Checks {#health-checks} @@ -117,7 +123,7 @@ Each of these claims will be prefixed with `https://octopus.com/claims/` and wil "https://octopus.com/claims/tenant": "tenant-slug", "https://octopus.com/claims/type": "deployment", // or runbook for a runbook run "https://octopus.com/claims/account": "account-slug", - "sub": "space:[space-slug]:project:[project-slug]:environment:[environment-slug]" + "sub": "space:[space-slug]:project:[project-slug]:environment:[environment-slug]" // tenant segment dropped because this example is untenanted } ```