AWS Assume Role

This guide will walk you through the process of authenticating with AWS services using Web Identity Federation. By following these steps, you can obtain temporary security credentials without embedding long-term credentials in your applications.

The temporary security credentials returned by the AWS API consist of an access key ID, a secret access key, and a security token. Applications can use these temporary security credentials to securely access AWS Resources.

Prerequisites

• An active client in usegrant.dev
• An AWS account
• AWS CLI installed on your system

Before proceeding, you must plan your security strategy to ensure that access tokens are only allocated in a predictable way. To control how your cloud provider issues access tokens, you must define at least one condition to your openid connect provider, so that untrusted entities can't request access tokens for your cloud resources.

Step 1: Set Up an OpenID Connect Provider in AWS

1. Log in to the AWS Management Console and navigate to the IAM service.
2. In the navigation pane, select "Identity Providers".
3. Click on "Create Provider".
4. Select "OpenID Connect" as the provider type.
5. Fill in the required details and click "Create Provider".

For the provider URL use the url of your project or the custom domain you set up.

Ensure that the audience matches the one used to create the client in useGrant.dev. For AWS, the audience is typically sts.amazonaws.com.

Refer to the AWS documentation for more details and customization options.

Step 2: Create a Role in AWS

1. Access the AWS Management Console and go to the IAM service.
2. In the navigation pane, click on "Roles".
3. Select "Create Role".
4. Choose "Web Identity" as the trusted entity.
5. Select the provider you set up in the previous step and choose the appropriate audience.

For enhanced security, you can also create a custom trust policy that is more restrictive. For example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456123456:oidc-provider/acme-prod.auth.usegrant.dev"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "acme-prod.auth.usegrant.dev:sub": "Z3bXuT3jaHG-ZF9LYt2hmNGi3iAJlUv9",
          "acme-prod.auth.usegrant.dev:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

Replace acme-prod.auth.usegrant.dev with the url of your project or the custom domain you set up. And also replace the subject with the one from your client.

Step 3: Assume Role with AWS CLI

Run the following command to assume the role:

aws sts assume-role-with-web-identity \
    --role-arn <ROLE_ARN_YOU_CREATED> \
    --role-session-name <YOUR_SESSION_NAME> \
    --web-identity-token <THE_ACCESS_TOKEN_FROM_USEGRANT>

This would return the temporary security credentials with AccessKeyId, SecretAccessKey and SessionToken. You can use these credentials to securely access AWS Resources.

For example,

{
    "SubjectFromWebIdentityToken": "amzn1.account.AF6RHO7KZU5XRVQJGXK6HB56KR2A"
    "Audience": "client.5498841531868486423.1548@apps.example.com",
    "AssumedRoleUser": {
        "Arn": "arn:aws:sts::123456789012:assumed-role/FederatedWebIdentityRole/app1",
        "AssumedRoleId": "AROACLKWSDQRAOEXAMPLE:app1"
    }
    "Credentials": {
        "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY",
        "SessionToken": "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtpZ3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE",
        "Expiration": "2020-05-19T18:06:10+00:00"
    },
    "Provider": "www.amazon.com"
}

By default, the temporary security credentials created by AssumeRoleWithWebIdentity last for one hour. However, you can use the optional DurationSeconds parameter to specify the duration of your session. You can provide a value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.

Learn more about the AssumeRoleWithWebIdentity API from the official AWS documentation.

Using CloudFormation Template

You can also use CloudFormation to create the role and the trust policy instead of manually creating them as shown in the previous steps.

Example CloudFormation template:

AWSTemplateFormatVersion: '2010-09-09'
Description: Configure OIDC Provider and IAM Role for Web Identity Federation
 
Resources:
  OIDCProvider:
    Type: AWS::IAM::OIDCProvider
    Properties:
      Url: https://<PROJECT_URL_ID>.usegrant.dev
      ClientIdList:
        - sts.amazonaws.com
 
  IAMRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: OIDCRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Federated: !Ref OIDCProvider
            Action: sts:AssumeRoleWithWebIdentity
            Condition:
              ForAnyValue:StringEquals:
                <PROJECT_URL_ID>.usegrant.dev:sub: <SUBJECT_FROM_CLIENT>
                <PROJECT_URL_ID>.usegrant.dev:aud: sts.amazonaws.com
      ManagedPolicyArns: # replace with the policy you want to attach to the role
        - arn:aws:iam::aws:policy/AdministratorAccess

Copy the template and replace the placeholders like PROJECT_URL_ID, SUBJECT_FROM_CLIENT with your own values.

• Audience is typically sts.amazonaws.com. But you can also use the audience you used while creating the project in useGrant.dev.
• SUBJECT_FROM_CLIENT is the subject from the client, this will be generated after you create the client.

If you have a custom domain set up, replace the Url with your custom domain.