From dabd8b39d940b8d4c4171cacf9e37614f010e989 Mon Sep 17 00:00:00 2001 From: rchildress87 <13559499+rchildress87@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:38:33 -0500 Subject: [PATCH 1/3] Updated service connection instructions in README.md Replaced some inaccurate instructions, replaced all references of service endpoint with service connection, added more verbosity to the service connection parameters section to make it more clear which parameters need to be filled out. --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 8c3ac27e..0ab516f9 100644 --- a/README.md +++ b/README.md @@ -34,11 +34,11 @@ To enable tasks to call AWS services when run as part of your build or release p The AWS tasks support the following mechanisms for obtaining AWS credentials: -One or more service endpoints, of type _AWS_, can be created and populated with either: +One or more service connections, of type _AWS_, can be created and populated with either: - Static credentials in the form of AWS access and secret keys, and optionally data for _Assumed Role_ credentials. - If only the _Assumed Role_ is defined but neither access key ID nor secret key, the role will be assumed regardless. This is useful when using instance profiles, and profile which only allows to assume a role. -- If `Use OIDC` is checked and you have defined an _Assumed Role_ without an access key ID or secret key, an OIDC token will be requested from Azure Devops and used to federate into AWS. +- If `Use OIDC` is checked and you have defined an _Assumed Role_ without an `Access Key ID` or `Secret Access Key`, an OIDC token will be requested from Azure DevOps and used to federate into AWS. - Using OIDC requires the creation of an OIDC Provider. Please refer to the documentation here: [Creating and managing an OIDC provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-console) - This will also require a trust policy on the _Assume Role_ similar to this : @@ -67,32 +67,32 @@ One or more service endpoints, of type _AWS_, can be created and populated with - A sample CloudFormation template [example_cfn.yml](./example_cfn.yaml) is available to assist with the setup and configuration. - Variables defined on the task or build. - - If tasks are not configured with the name of a service endpoint they will attempt to obtain credentials, and optionally region, from variables defined in the build environment. The + - If tasks are not configured with the name of a service connection they will attempt to obtain credentials, and optionally region, from variables defined in the build environment. The variables are named _AWS.AccessKeyID_, _AWS.SecretAccessKey_ and optionally _AWS.SessionToken_. To supply the ID of the region to make the call in, e.g. us-west-2, you can also use the variable _AWS.Region_. Optionally a role to assume can be specified by using the variable _AWS.AssumeRoleArn_. When assuming roles _AWS.RoleSessionName_ (optional) and _AWS.ExternalId_ (optional) can be provided in order to specify an identifier for the assumed role session and an external id to show in customers' accounts when assuming roles. - Environment variables in the build agent's environment. - - If tasks are not configured with the name of a service endpoint, and credentials or region are not available from task variables, the tasks will attempt to obtain credentials, and optionally region, from standard environment variables in the build process environment. These variables are _AWS_ACCESS_KEY_ID_, _AWS_SECRET_ACCESS_KEY_ and optionally _AWS_SESSION_TOKEN_. To supply the ID of the region to make the call in, e.g. us-west-2, you can also use the environment variable _AWS_REGION_. + - If tasks are not configured with the name of a service connection, and credentials or region are not available from task variables, the tasks will attempt to obtain credentials, and optionally region, from standard environment variables in the build process environment. These variables are _AWS_ACCESS_KEY_ID_, _AWS_SECRET_ACCESS_KEY_ and optionally _AWS_SESSION_TOKEN_. To supply the ID of the region to make the call in, e.g. us-west-2, you can also use the environment variable _AWS_REGION_. - EC2 instance metadata, for build hosts running on EC2 instances. - Both credential and region information can be automatically obtained from the instance metadata in this scenario. -### Configuring an AWS Service Endpoint +### Configuring an AWS Service Connection in Azure DevOps -To use _AWS_ service endpoints add the AWS subscription(s) to use by opening the Account Administration screen (gear icon on the top-right of the screen) and then click on the Services Tab. Note that each Azure DevOps project is associated with its own set of credentials. Service endpoints are not shared across projects. You can associate a single service endpoint to be used with all AWS tasks in a build or multiple endpoints if you require. +To use AWS service connections with the AWS Toolkit for Azure DevOps, you must first configure one. From Azure DevOps, open the project for which you would like pipelines to be able to access your AWS account and open `Project Settings` (bottom-left corner of web site). Under the `Pipelines` section, select `Service connections` and then click the `New service connection` button. Note that each Azure DevOps project is associated with its own set of credentials. Service connections are not shared across projects. You can associate a single service connection to be used with all AWS tasks in a build or multiple endpoints if you require. -Select the _AWS_ endpoint type and provide the following parameters based on the type of authentification above. +Select the _AWS_ endpoint type and provide the following parameters based on the type of authentification above: #### OIDC Federation -- A name used to refer to the credentials when configuring the AWS tasks -- The arn of the role to assume -- Check the useOIDC options +- `Service connection name`: A name used to refer to this service connection when later configuring AWS tasks +- `Role to Assume`: The ARN of the IAM role to assume +- `Use OIDC`: Checked #### Static credentials Please refer to [About Access Keys](https://aws.amazon.com/developers/access-keys/): -- A name used to refer to the credentials when configuring the AWS tasks -- AWS Access Key ID -- AWS Secret Access Key +- `Service connection name`: A name used to refer to the credentials when configuring the AWS tasks +- `Access Key ID`: The ID of the access key of the IAM user that will be used by the service connection tasks to authenticate to AWS +- `Secret Access Key`: The secret access key that will also be used with authentication #### Assume Role From b2ae8e6fbd8bc82ad8c7b12caa71430157688ea1 Mon Sep 17 00:00:00 2001 From: rchildress87 <13559499+rchildress87@users.noreply.github.com> Date: Thu, 14 Nov 2024 11:25:29 -0500 Subject: [PATCH 2/3] Added instructions on creating Entra App Registration. Make formatting more consistent in new content. --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 0ab516f9..73fcaf61 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,13 @@ One or more service connections, of type _AWS_, can be created and populated wit ``` - A sample CloudFormation template [example_cfn.yml](./example_cfn.yaml) is available to assist with the setup and configuration. - + - Additionally, a new App Registration will need to be created in the same Microsoft Entra Directory as the subscription where Azure DevOps is enabled. + - Create new App Registration from Microsoft Entra + - Create a new Federated Credential (values based on example trust policy above) + - **Federated credential scenario**: Other issuer + - **Issuer**: `https://vstoken.dev.azure.com/{org-id}` + - **Subject identifier**: `sc://{orgName}/{ProjectName}/{ServiceConnectionName}` + - **Audience**: `api://AzureADTokenExchange` - Variables defined on the task or build. - If tasks are not configured with the name of a service connection they will attempt to obtain credentials, and optionally region, from variables defined in the build environment. The variables are named _AWS.AccessKeyID_, _AWS.SecretAccessKey_ and optionally _AWS.SessionToken_. To supply the ID of the region to make the call in, e.g. us-west-2, you can also use the variable _AWS.Region_. Optionally a role to assume can be specified by using the variable _AWS.AssumeRoleArn_. When assuming roles _AWS.RoleSessionName_ (optional) and _AWS.ExternalId_ (optional) can be provided in order to specify an identifier for the assumed role session and an external id to show in customers' accounts when assuming roles. @@ -82,17 +88,17 @@ Select the _AWS_ endpoint type and provide the following parameters based on the #### OIDC Federation -- `Service connection name`: A name used to refer to this service connection when later configuring AWS tasks -- `Role to Assume`: The ARN of the IAM role to assume -- `Use OIDC`: Checked +- **Service connection name**: A name used to refer to this service connection when later configuring AWS tasks +- **Role to Assume**: The ARN of the IAM role to assume +- **Use OIDC**: Checked #### Static credentials Please refer to [About Access Keys](https://aws.amazon.com/developers/access-keys/): -- `Service connection name`: A name used to refer to the credentials when configuring the AWS tasks -- `Access Key ID`: The ID of the access key of the IAM user that will be used by the service connection tasks to authenticate to AWS -- `Secret Access Key`: The secret access key that will also be used with authentication +- **Service connection name**: A name used to refer to the credentials when configuring the AWS tasks +- **Access Key ID**: The ID of the access key of the IAM user that will be used by the service connection tasks to authenticate to AWS +- **Secret Access Key**: The secret access key that will also be used with authentication #### Assume Role From ef0a3c1345fc8b270dbf0350cdd47a0334446fb3 Mon Sep 17 00:00:00 2001 From: Dick Childress Date: Thu, 14 Nov 2024 12:25:11 -0500 Subject: [PATCH 3/3] Updated changes for next release. --- .../Feature-a3274e41-c614-4426-8856-2d4dc236ebbd.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .changes/next-release/Feature-a3274e41-c614-4426-8856-2d4dc236ebbd.json diff --git a/.changes/next-release/Feature-a3274e41-c614-4426-8856-2d4dc236ebbd.json b/.changes/next-release/Feature-a3274e41-c614-4426-8856-2d4dc236ebbd.json new file mode 100644 index 00000000..0f3cd38a --- /dev/null +++ b/.changes/next-release/Feature-a3274e41-c614-4426-8856-2d4dc236ebbd.json @@ -0,0 +1,4 @@ +{ + "type": "Feature", + "description": "Add additional documentation for OIDC authentication type and Microsoft Entra app registrations." +} \ No newline at end of file