diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index 8cbd56726e..18eda36ed6 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -52,6 +52,7 @@ HSTS HTTPAPI hyperthread hyperthreading +IMDS inetmgr inetsrv internalcustomer diff --git a/src/pages/docs/infrastructure/accounts/aws/index.md b/src/pages/docs/infrastructure/accounts/aws/index.md index 08a9893382..c79c68f0de 100644 --- a/src/pages/docs/infrastructure/accounts/aws/index.md +++ b/src/pages/docs/infrastructure/accounts/aws/index.md @@ -15,16 +15,53 @@ The AWS account is either a pair of access and secret keys, or the credentials a ## Create an AWS account -AWS steps can use an Octopus managed AWS account for authentication. +AWS steps can use an Octopus managed AWS account for authentication. There a two different account types you can choose from, Access Keys or OpenID Connect. + +### Access Key account + +See the [AWS documentation](https://oc.to/aws-access-keys) for instructions to create the access and secret keys. 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. Enter the **Access Key** and the secret **Key**. +1. Click the **SAVE AND TEST** to save the account and verify the credentials are valid. + +### OpenID Connect + +:::div{.warning} +Support for OpenID Connect authentication to AWS requires Octopus Server version 2024.1 +::: -See the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) for instructions to create the access and secret keys. +See the [AWS documentation](https://oc.to/aws-oidc) for instructions to configure an OpenID Connect identity provider. -5. Click the **SAVE AND TEST** to save the account and verify the credentials are valid. +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). + +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. + +Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/openid-connect#subject-keys) on how to customize the **Subject** value. + +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: + +```JSON +"Condition": { + "StringEquals": { + "example.octopus.app:sub": "space:default:project:aws-oidc-testing:environment:dev", + "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. :::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. @@ -80,12 +117,21 @@ The **OctopusPrintVariables** has been set to true to print the variables to the When running a step, the available variables will be printed to the log. In this example, the following variables are shown: +**Access Key Account** ``` -[AWS Account] = 'amazonwebservicesaccount-aws-account' -[AWS Account.AccessKey] = 'ABCDEFGHIJKLONOPQRST' +[AWS Account] = 'amazon-web-services-account' +[AWS Account.AccessKey] = 'YOUR_ACCESS_KEY' [AWS Account.SecretKey] = '********' ``` +**OpenID Connect Account** +``` +[AWS Account] = 'amazon-web-services-account' +[AWS Account.RoleArn] = 'arn:aws:iam::123456789012:role/test-role' +[AWS Account.SessionDuration] = '3600' +[AWS Account.OpenIdConnect.Jwt] = '********' +``` + **AWS Account.AccessKey** is the access key associated with the AWS account, and **AWS Account.SecretKey** is the secret key. The secret key is hidden as asterisks in the log because it is a sensitive value, but the complete key is available to your script. You can then use these variables in your scripts or other step types. For example, the following PowerShell script would print the access key to the console. diff --git a/src/pages/docs/infrastructure/accounts/azure/index.md b/src/pages/docs/infrastructure/accounts/azure/index.md index 62d89c4f21..1380f86da1 100644 --- a/src/pages/docs/infrastructure/accounts/azure/index.md +++ b/src/pages/docs/infrastructure/accounts/azure/index.md @@ -48,19 +48,15 @@ Next, you need to configure your [resource permissions](#resource-permissions). ### Create a federated credential for an Azure Service Principal -#### Octopus Server configuration -:::div{.info} -If you are using Octopus Cloud, you will not need to do anything to expose the instance to the public internet, this is already configured for you. +:::div{.warning} +Support for OpenID Connect authentication to Azure requires Octopus Server version 2023.4 ::: -To use federated credentials, your Octopus instance will need to have two anonymous URLs exposed to the public internet. - -- `https://server-host/.well-known/openid-configuration` -- `https://server-host/.well-known/jwks` +To use OpenID Connect to authenticate with Azure, you will need to create a federated credential for the Azure Service Principal -These must be exposed with anonymous access on HTTPS. Without this, the OpenID Connect protocol will not be able to complete the authentication flow. +#### Octopus Server configuration -The hostname of the URL that these two endpoints are available on must either be configured under **Configuration->Nodes->Server Uri** or set as the first ListenPrefix in the server configuration. +To use OpenID Connect authentication you have to follow the [required minimum configuration](/docs/infrastructure/accounts/openid-connect#configuration). #### Azure Service Principal configuration @@ -68,7 +64,7 @@ To manually create a Federated Credential follow the [Add a federated credential The federated credential will need the **Issuer** value set to the publicly accessible Octopus Server URI configured in the previous step, this value must also not have a trailing slash (/), for example `https://samples.octopus.app`. -Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/openid-connect) on how to customize the **Subject** value. +Please read [OpenID Connect Subject Identifier](/docs/infrastructure/accounts/openid-connect#subject-keys) on how to customize the **Subject** value. The **Audience** value can be left at the default, or set to a custom value if needed. diff --git a/src/pages/docs/infrastructure/accounts/openid-connect.md b/src/pages/docs/infrastructure/accounts/openid-connect.md index d67c94e4a3..cef80013e4 100644 --- a/src/pages/docs/infrastructure/accounts/openid-connect.md +++ b/src/pages/docs/infrastructure/accounts/openid-connect.md @@ -26,7 +26,7 @@ The hostname of the URL that these two endpoints are available on must either be If you have a third-party service or tool that supports OpenID Connect, you can add any OIDC account variable into your projects variable set and use the `[account name].OpenIdConnect.Jwt` variable to get access to the request token that can be used for authenticating. The JWT for the account on a step or the target is available in the `Octopus.OpenIdConnect.Jwt` variable. -## Subject Keys +## Subject Keys {#subject-keys} When using OpenID Connect to authenticate to with external services, the Subject claim can have its contents customized. diff --git a/src/pages/docs/projects/variables/aws-account-variables.md b/src/pages/docs/projects/variables/aws-account-variables.md index 30ef7882a5..3cb7c4d5ff 100644 --- a/src/pages/docs/projects/variables/aws-account-variables.md +++ b/src/pages/docs/projects/variables/aws-account-variables.md @@ -26,11 +26,22 @@ Select the AWS account you want to access from the project to assign it to the v The AWS account variable also exposes the following properties that you can reference in a PowerShell script: +**Access Key account** + | Name and description | | -------------------- | | **`AccessKey`**
The Access Key for the AWS account| | **`SecretKey`**
The Secret Key for the AWS account| +**OpenId Connect account** + +| Name and description | +| -------------------- | +| **`RoleArn`**
The Role Arn that identifies the AWS role| +| **`SessionDuration`**
The session duration for the AWS role| +| **`OpenIdConnect.Jwt`**
The JWT identity token for the current task| + + ### Accessing the properties in a script Each of the above properties can be referenced in PowerShell. @@ -42,9 +53,24 @@ Each of the above properties can be referenced in PowerShell. Write-Host 'AwsAccount.Id=' $OctopusParameters["aws account"] Write-Host 'AwsAccount.AccessKey=' $OctopusParameters["aws account.AccessKey"] +# For an OpenId Connect account +Write-Host `AwsAccount.RoleArn=` $OctopusParameters["aws account.RoleArn"] +Write-Host `AwsAccount.SessionDuration=` $OctopusParameters["aws account.SessionDuration"] + # Directly as a variable Write-Host 'AwsAccount.Id=' #{aws account} Write-Host 'AwsAccount.AccessKey=' #{aws account.AccessKey} + +# For an OpenId Connect account +Write-Host `AwsAccount.RoleArn=` #{aws account.RoleArn} +Write-Host `AwsAccount.SessionDuration=` #{aws account.SessionDuration} + +# Manually obtain temporary credentials for the AWS Cli with an OpenId Connect account +aws sts assume-role-with-web-identity ` + --duration-seconds $OctopusParameters["aws account.SessionDuration"] ` + --role-session-name ` + --role-arn $OctopusParameters["aws account.RoleArn"] + --web-identity-token $OctopusParameters["aws account.OpenIdConnect.Jwt"] ``` :::div{.hint} diff --git a/tests/bookmark.spec.ts b/tests/bookmark.spec.ts index 911cf3f9e4..2788548c9a 100644 --- a/tests/bookmark.spec.ts +++ b/tests/bookmark.spec.ts @@ -52,6 +52,7 @@ const bookmarks = [ '/docs/deprecations#reporting-deployments-by-week', '/docs/infrastructure/accounts/azure#azure-service-principal', '/docs/infrastructure/accounts/azure#resource-permissions', + '/docs/infrastructure/accounts/openid-connect#subject-keys', '/docs/infrastructure/deployment-targets#target-roles', '/docs/infrastructure/deployment-targets/kubernetes-target#add-a-kubernetes-target', '/docs/infrastructure/deployment-targets/kubernetes-target#vendor-authentication-plugins',