AWS OIDC account (#2136)

Co-authored-by: Steve Fenton <99181436+steve-fenton-octopus@users.noreply.github.com>

dictionary-octopus.txt

@@ -52,6 +52,7 @@ HSTS
 HTTPAPI
 hyperthread
 hyperthreading
+IMDS
 inetmgr
 inetsrv
 internalcustomer

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.

src/pages/docs/infrastructure/accounts/azure/index.md

@@ -48,27 +48,23 @@ 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 
 
 To manually create a Federated Credential follow the [Add a federated credential](https://oc.to/create-azure-credentials) section in the Azure AD documentation, or create it with a [script](#create-federated-credential-via-script).
 
 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.
 

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.
 

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`** <br/> The Access Key for the AWS account|
 | **`SecretKey`** <br/> The Secret Key for the AWS account|
 
+**OpenId Connect account**
+
+| Name and description |
+| -------------------- |
+| **`RoleArn`** <br/> The Role Arn that identifies the AWS role|
+| **`SessionDuration`** <br/> The session duration for the AWS role|
+| **`OpenIdConnect.Jwt`** <br/> 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_SESSION> `
+    --role-arn $OctopusParameters["aws account.RoleArn"]
+    --web-identity-token $OctopusParameters["aws account.OpenIdConnect.Jwt"]
 ```
 
 :::div{.hint}

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',