Using Federated Identities with AWS CodeCommit

Thanks to Raja Mani, AWS Solutions Architect, for this great blog that describes how federated users can access AWS CodeCommit.
—

You can access repositories in AWS CodeCommit using the identities used in your business. This is useful because you can reuse your existing organizational identities and authentication methods. In this blog post, we’ll focus on authenticating with Active Directory Federation Services (AD FS), but the concepts apply to other federated identity providers as well, such as Okta.

AWS Federation helps to manage access to your AWS resources centrally. With federation, you can single sign-on to your AWS accounts using your corporate directory credentials. This authenticates through AWS Identity and Access Management (IAM) policies once a user assumes an IAM role. AWS offers multiple options for federating your identities. You can learn more about them here.

If you are federating with AWS for the first time, refer the following for more information and implementation guidance:

• Identity Providers and Federation
• AWS Federated Authentication with Active Directory Federation Services

There are two solutions available when using federated identities with AWS CodeCommit: AWS Single Sign-On and AWS Process Credential Provider.

Using CodeCommit with AWS Single Sign-On

Your first option is to use AWS Single Sign-On (AWS SSO). You can access AWS CodeCommit repositories by using temporary credentials obtained from the AWS SSO user portal. You might want to use AWS SSO if you have multiple AWS accounts and business applications and you want to manage them centrally. This solution is documented in the blog post “AWS Single Sign-On Now Enables Command Line Interface Access for AWS Account Using Corporate Credentials”.

The AWS SSO Service connects to an on-premises Microsoft Active Directory via AD Connector/AD trust. In the AWS SSO Console, you can obtain temporary credentials for the AWS Command Line Interface (AWS CLI). It is easy to manage federation for multiple AWS accounts centrally using AWS SSO. However, as of this writing, AWS SSO supports Microsoft Active Directory only. If you are using a different identity provider, use the second solution.

The high-level architecture for this solution looks like this:

1. The user signs in to the AWS SSO Console and chooses the account they want to use for CodeCommit access. Then, they select the particular permission set for that account that has access to the CodeCommit Repository.
2. The user then clicks the “Command line or programmatic access” link corresponding to the permission set to get the AWS Credentials.
3. The user configures the AWS CLI to use the credentials obtained in the previous step.
4. The user configures the Git command line tool to use the AWS CLI via the AWS CLI Credential Helper. For more information, see this page.

After completing all the above steps, the user can run commands from the Git client.

Using CodeCommit with AWS Process Credential Provider

Your second option is to use the AWS Process Credential Provider utility. You might want to use this solution if you do not currently use AWS SSO to centrally manage access to AWS accounts. The following diagram shows a high-level architectural view of what happens when the AWS Process Credential Provider utility is invoked from the AWS CLI.

1. The AWS Process Credential Provider utility is invoked by AWS CLI. It calls the Active Directory Federation Services portal sign-in page and provides the Active Directory authentication credentials. If you are using a different federated access solution, it works in a similar manner.
2. AD FS authenticates the user against Active Directory.
3. AD FS builds the Security Assertion Markup Language (SAML) response and sends it back to the AWS Process Credential Provider utility.
4. The AWS Process Credential Provider utility connects to AWS Simple Token Service (STS) using STS AssumeRoleWithSAML.
5. STS sends temporary credentials to the AWS Process Credential Provider utility.
6. The user is authenticated and can successfully connect to the AWS CodeCommit repository from their local Git client, command line, or terminal.

I am going to demonstrate this solution by cloning an AWS CodeCommit repository called ExampleCorpRepository from the US East (Virginia) Region (us-east-1) region by authenticating against AD FS. I used an Amazon EC2 instance to demonstrate this solution, but the same steps can be used in other environments, such as your business intranet.

Prerequisites

• Setup AWS Federated authentication with your identity provider. You can use the blog post mentioned at the beginning of this blog post for reference.
• Install Git on your local computer, including a Git command line from here: https://git-scm.com/downloads
• Install the AWS Process Credential Provider utility “awsprocesscreds” on your local computer according to the installation instructions on this page: https://github.com/awslabs/awsprocesscreds
• Install a Git CodeCommit helper utility called “git-remote-codecommit” on your local computer from this page: https://github.com/awslabs/git-remote-codecommit
• Enable the ADFS Sign-on page (You can get it from your ADFS Admin) in your corporate network. Make sure it has the loginToRp parameter set with the correct value. Your ADFS admin can provide that value too.
• Create an AWS IAM role that grants access to AWS CodeCommit repositories in the US East (N. Virginia) region. Make sure to record the Amazon Resource Name (ARN) for the role that grants users who assume the role access to AWS CodeCommit repositories. Refer this page for more info about CodeCommit.
• Create an AD FS user and password.
• Create an AWS CodeCommit repository in the US East (Virginia) region named ExampleCorpRepository.

Step 1: Create an AWS Command Line Interface (CLI) Profile
This step configures the AWS CLI to use the AWS Process Credential Provider utility you installed as part of the prerequisites. It will authenticate against ADFS using the user name and password you provide. If the authentication is successful, it will obtain temporary AccessKeyId and SecretAccessKey tokens from AWS STS and pass them to the AWS CLI.

1. Open the .aws/config file in a plain-text editor. Create a new profile entry named adfs in the config file and set it up to use the AWS Process Credential Provider utility. For example, I created the following entry in the config file (in my environment, the config file is found in the /home/ec2-user/.aws directory).

[profile adfs]
	 region=us-east-1
credential_process=awsprocesscreds-saml -e 'https://ec2-xx-xx-xxx-xx.compute-1.amazonaws.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices' -u 'username@domain' -p adfs -a arn:aws:iam::xxxxxxxxxxxx:role/ADFS-Production

It takes 4 parameters: the URL of your ADFS Sign-on page (-e flag), the user name of your AD_FS user (-u flag), the name of your SAML provider (-p flag) and the ARN of the role in AWS IAM your user will assume for access to AWS CodeCommit (-a flag).

• The first parameter is AD_FS Sign-on page and it is also known as IdP-initiated login page. For AD_FS, the Sign-on page takes the form of https://<fqdn>/adfs/ls/IdpInitiatedSignOn.aspx with query string value of loginToRp=urn:amazon:webservices.
• The second parameter is AD_FS user name which will be your corporate user id / user id you created specifically for CodeCommit access in the prerequisite steps. In a real-world example, this is something your users would obtain from your AD FS administrator.
• The third parameter is the name of your federated access identity. Currently the only supported providers are AD_FS and Okta.
• The fourth parameter is the AWS IAM role ARN that the AD_FS user will assume in order to be granted access to the AWS CodeCommit repository. This is the role you created in the prerequisites. Refer to https://github.com/awslabs/awsprocesscreds for more information.

The AWS Process Credential Provider utility will prompt you for the password for the configured AD_FS user the first time you invoke an AWS CLI command at the command line or terminal. If authentication is successful, it caches the security tokens for further AWS CLI usage until the cache expires. By default, tokens are valid for an hour. If you want to change the default, you can change it as per the instructions in this blog post (Refer to the section “Adjusting Session Duration”).

2. Save your config file changes and open a new command line or terminal session.

Step 2: Clone the AWS CodeCommit Repository to your Local Computer

This step uses git-remote-codecommit, the Git CodeCommit helper utility you installed in the prerequisities section. It simplifies the way you push and pull changes to repositories from your local Git client to AWS CodeCommit. You can run the following command to clone your repository. In my case, I have a repository called ExampleCorpRepository. I cloned it to my local computer, creating a local repo, by using the following command:

git clone codecommit://adfs@ExampleCorpRepository

The above command takes one parameter in the form of codecommit://<AWS CLI Profile Name>@<AWS CodeCommit Repository Name>. The AWS CLI profile name is the one you created in Step 1 (in the example, it is named adfs). The repository name is the actual name of the AWS CodeCommit repository you want to clone. Git will remember the repository information. You won’t need to pass the parameter again when you run additional Git commands, such as git commit or git push. It will only prompt you for a password if the session is expired.

Conclusion

We hope this has illustrated how you can use CodeCommit with federated users. Happy coding!