diff --git a/src/pages/docs/infrastructure/accounts/aws/index.md b/src/pages/docs/infrastructure/accounts/aws/index.md index c79c68f0de..3ac063cc55 100644 --- a/src/pages/docs/infrastructure/accounts/aws/index.md +++ b/src/pages/docs/infrastructure/accounts/aws/index.md @@ -33,18 +33,47 @@ See the [AWS documentation](https://oc.to/aws-access-keys) for instructions to c Support for OpenID Connect authentication to AWS requires Octopus Server version 2024.1 ::: +To use OpenID Connect authentication you have to follow the [required minimum configuration](/docs/infrastructure/accounts/openid-connect#configuration). + See the [AWS documentation](https://oc.to/aws-oidc) for instructions to configure an OpenID Connect identity provider. +:::div{.info}**If using the AWS CLI or API to configure the identity provider.** + +See the [AWS Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html) for instructions on how to obtain the thumbprint of your Octopus Server. +::: + When setting up the identity provider you need to use the host domain name of your server as the **Audience** value, as configured under **Configuration->Nodes->Server Uri**. -To use OpenID Connect authentication you have to follow the [required minimum configuration](/docs/infrastructure/accounts/openid-connect#configuration). +#### Configuring AWS OIDC Account 1. Navigate to **Infrastructure ➜ Accounts**, click the **ADD ACCOUNT** and select **AWS Account**. -1. Add a memorable name for the account. -1. Provide a description for the account. -1. Set the Role ARN to the ARN from the identity provider associated role. -1. Set the Session Duration to the Maximum session duration from the role, in seconds. -1. Click the **SAVE AND TEST** to save the account and verify the credentials are valid. +2. Add a memorable name for the account. +3. Provide a description for the account. +4. Set the **Role ARN** to the ARN from the identity provider associated role. +5. Set the **Session Duration** to the Maximum session duration from the role, in seconds. +6. Click **SAVE** to save the account. +7. Before you can test the account you need to add a condition to the identity provider in AWS under **IAM ➜ Roles ➜ {Your AWS Role} ➜ Trust Relationship** : +```JSON +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::{aws-account}:oidc-provider/{your-identity-provider}" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "example.octopus.app:sub": "space:[space-slug]:account:[slug-of-account-created-above]", + "example.octopus.app:aud": "example.octopus.app" + } + } + } + ] +} +``` +8. Go back to the AWS account in Octopus and click **SAVE AND TEST** to verify the credentials are valid. Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/openid-connect#subject-keys) on how to customize the **Subject** value. @@ -56,12 +85,26 @@ For example, to lock an identity role to a specific Octopus environment, you can "Condition": { "StringEquals": { "example.octopus.app:sub": "space:default:project:aws-oidc-testing:environment:dev", - "example.octopus.app::aud": "example.octopus.app:" + "example.octopus.app:aud": "example.octopus.app:" } } ``` -`default`, `aws-oidc-testing` and `dev` are the slugs of their respective resources. AWS policy conditions also support complex matching with wildcards and `StringLike` expressions. +`default`, `aws-oidc-testing` and `dev` are the slugs of their respective Octopus resources. + +AWS policy conditions also support complex matching with wildcards and `StringLike` expressions. + +For example, to lock an identity role to any Octopus environment, you can update the conditions: + +```JSON +"Condition": { + "StringLike": { + "example.octopus.app:sub": "space:default:project:aws-oidc-testing:environment:*", + "example.octopus.app:aud": "example.octopus.app:" + } +} +``` +`default` and `aws-oidc-testing` are the slugs of their respective Octopus resources. :::div{.hint} AWS steps can also defer to the IAM role assigned to the instance that hosts the Octopus Server for authentication. In this scenario there is no need to create the AWS account. diff --git a/src/pages/docs/infrastructure/accounts/openid-connect.md b/src/pages/docs/infrastructure/accounts/openid-connect.md index cef80013e4..c05d11185b 100644 --- a/src/pages/docs/infrastructure/accounts/openid-connect.md +++ b/src/pages/docs/infrastructure/accounts/openid-connect.md @@ -41,7 +41,7 @@ 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 resource types include in the **Subject** claim will use the slug value for the resource. The slug value is generated from the name of the resource when it was created, it can be edited on the edit page of resource type. +- 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. - The **Subject** claim parts will always be in the following order - **Space** - **Project**