AWS IAM Identity Center (Formerly Single Sign On)

AWS IAM Identity Center setup

To set up AWS IAM Identity Center as your identity provider for Common Fate you will need to create an IAM role in the management account of your AWS organization that has a trust relationship with the Common Fate deployment.

This role required has a minimal set of IAM permissions which only allow it to read information about your users and groups.

Creating an IAM Role

Follow either the Cloudformation process to deploy this role, or you can use the JSON policy template directly if you would prefer to deploy this role using a custom process.

Cloudformation

Setup the Cloudformation Template

Run the following commands in your terminal to create `granted-identity-sso-role.yml`, a CloudFormation template which will be deployed to your AWS account. We recommend saving this alongside your `deployment.yml` file in source control.

IDP_SYNC_ROLE_ARN=$(gdeploy output IDPSyncExecutionRoleARN)
API_ROLE_ARN=$(gdeploy output RestAPIExecutionRoleARN)

cat << EOF > granted-identity-sso-role.yml
Resources:
  GrantedIdentitySSORole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Statement:
          - Action: sts:AssumeRole
            Effect: Allow
            Principal:
              AWS: "${IDP_SYNC_ROLE_ARN}"
          - Action: sts:AssumeRole
            Effect: Allow
            Principal:
              AWS: "${API_ROLE_ARN}"
        Version: "2012-10-17"
      Description: This role grants read access to AWS SSO to Granted.
      Policies:
        - PolicyName: AccessHandlerSSOPolicy
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: ReadIdentityStore
                Action:
                  - identitystore:DescribeGroup
                  - identitystore:DescribeUser
                  - identitystore:ListGroupMembershipsForMember
                  - identitystore:ListUsers
                  - identitystore:ListGroups
                Effect: Allow
                Resource: "*"
      Tags:
        - Key: "common-fate-abac-role"
          Value: "aws-sso-identity-provider"
Outputs:
  RoleARN:
    Value:
      Fn::GetAtt:
        - GrantedIdentitySSORole
        - Arn
EOF

Deploy the Cloudformation Template

Follow either the Console or CLI deployment steps.

Via the AWS CLI

If you have the AWS CLI installed and can deploy cloudformation you can run the following commands to deploy this stack.

aws cloudformation deploy --template-file granted-identity-sso-role.yml --stack-name Granted-Identity-SSO-Role --capabilities CAPABILITY_IAM

Once the stack is deployed, you can retrieve the role ARN by running the following command.

aws cloudformation describe-stacks --stack-name Granted-Identity-SSO-Role --query "Stacks[0].Outputs[0].OutputValue"

Via the AWS console

Open the AWS Console in your organisation's management account and click **Create stack** then select **with new resources (standard)** from the menu.

Upload the template file

Name the stack 'Granted-Identity-SSO-Role'

Click Next

Click Next

Acknowledge the IAM role creation check box and click Create Stack

Keep the RoleARN output from the stack handy for the next step.

Policy as JSON

Permissions Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "identitystore:DescribeGroup",
        "identitystore:DescribeUser",
        "identitystore:ListGroupMembershipsForMember",
        "identitystore:ListUsers",
        "identitystore:ListGroups"
      ],
      "Resource": "*",
      "Effect": "Allow",
      "Sid": "ReadIdentityStore"
    }
  ]
}

Trust Relationship Policy

For the trust relationship policy, you will need replace {{ IDPSyncExecutionRoleARN }} and {{ RestAPIExecutionRoleARN }} with the values from your deployment. You can use the following gdeploy commands to fetch the values.

gdeploy output IDPSyncExecutionRoleARN
gdeploy output RestAPIExecutionRoleARN

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "{{ IDPSyncExecutionRoleARN }}"
      },
      "Action": "sts:AssumeRole"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "{{ RestAPIExecutionRoleARN }}"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Tags

Ensure that you add the following tag to the role so that the Common Fate lambda can assume it.

• Key: common-fate-abac-role
• Value: aws-sso-identity-provider

Setting up SAML SSO

Create the SAML Application

To get started navigate to the Applications tab of the AWS IAM Identity Center console.

Click Add application, then select the Add custom SAML 2.0 application option. Click Next then Give your application a suitable name.

Configure the SAML Application

In a terminal where your deployment.yml file is, run the following command.

gdeploy identity sso saml-parameters

The output should look like this.

+------------------------+-----------------------------------------------------------------------------------+
|       PARAMETER        |                                       VALUE                                       |
+------------------------+-----------------------------------------------------------------------------------+
| SAML SSO URL (ACS URL) | https://cf-granted-josh-6.auth.ap-southeast-2.amazoncognito.com/saml2/idpresponse |
| Audience URI           | urn:amazon:cognito:sp:ap-southeast-2_bEIsBXsiy                                    |
| Dashboard URL          | https://d20qmwhjbabk4p.cloudfront.net                                             |
+------------------------+-----------------------------------------------------------------------------------+

Scroll down to the Application properties section.

Add the Common Fate Dashboard URL from the command output to the Application start URL field.

Scroll down to the Application metadata section.

Add the Common Fate SAML SSO URL (ACS URL) from the command output to the Application ACS URL field.

Add the Common Fate Audience URI from the command output to the Application SAML audience field.

Click Next

Configure the SAML Attributes

Click the Actions menu then select the Edit attribute mappings option.

On the first entry for "Subject" set the field Maps to this string value or user attribute in IAM Identity Center to ${user:email}

Add a new attribute mapping.

• For User attribute in the application, enter: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• For Maps to this string value or user attribute in IAM Identity Center, enter: ${user:email}
• For Format select basic

Click Save Changes

info

You'll need to assign yourself and other users to the SAML application before you can login.

Use the assign user wizard to assign users or groups to the application.

Setup the SAML SSO provider in your deployment

Now that you have configured the SAML application, you can use gdeploy to set up the SSO provider for your deployment.

gdeploy identity sso enable

Select AWS Single Sign On

Enter the ARN of the IAM role that you deployed earlier.

? The ARN of the AWS IAM Role with permission to administer SSO (identityStoreRoleArn)

Fetch the AWS SSO Instance ID

Via the AWS CLI

If you have the AWS CLI installed and can access the account that your AWS SSO instance is deployed to, run the following command to retrieve details about the instance:

aws sso-admin list-instances

You will see an output similar to the following:

{
    "Instances": [
        {
            "InstanceArn": "arn:aws:sso:::instance/ssoins-1234567890",
            "IdentityStoreId": "d-1234567890"
        }
    ]
}

The IdentityStoreId field in the CLI output should be provided as the identityStoreId parameter when configuring the provider.

Via the AWS console

Open the AWS console in the account that your AWS SSO instance is deployed to. If your company is using AWS Control Tower, this will be the root account in your AWS organisation.

Visit the Settings tab. The information about your SSO instance will be shown here, including the Instance ARN (as the “ARN” field) and the Identity Store ID.

Enter the AWS Identity Store id

? The AWS SSO Identity Store ID (identityStoreId)

Enter the region that your Identity Store is deployed to.

? the region the AWS SSO instance is deployed to (region)

Fetch the SAML Application Metadata

Next you will be prompted for the SAML metadata, select URL

? Would you like to use a metadata URL, an XML string, or load XML from a file?  [Use arrows to move, type to filter]
> URL
  String
  File

In the AWS console, navigate to IAM Identity Center, the Applications.

Select the application you created in the previous step.

From the Actions menu, select Edit configuration

Scroll down to the IAM Identity Center metadata section.

Copy the URL under IAM Identity Center SAML metadata file and enter it in the gdeploy cli when prompted for the URL.

? Metadata URL

Creating Common Fate Administrator Group

Finally you will need to create or use an existing group in AWS IAM Identity Center as an administrator group for Common Fate. Members of this group will have access to the admin dashboard of the application. Enter the ID of the group in AWS IAM Identity Center which represents the administrators of Common Fate.

A group ID looks like this 976708da7d-b2f2e2cf-152c-4301-923f-ed6b3b9564a3 and can be found in the AWS console.

[!] Don't forget to assign your users to the SAML app in aws-sso so that they can login after setup is complete.
[i] When using SSO, administrators for Granted are managed in your identity provider.
        Create a group called 'Granted Administrators' in your identity provider and copy the group's ID.
        Users in this group will be able to manage Access Rules.

? The ID of the Granted Administrators group in your identity provider:

You should see the following prompts which indicate that you have completed setup.

You should follow the instructions to update you Common Fate deployment.

[i] Updating your deployment config
[✔] Successfully completed SSO configuration
[!] Your changes won't be applied until you redeploy. Run 'gdeploy update' to apply the changes to your CloudFormation deployment.

    Users and will be synced every 5 minutes from your identity provider. To finish enabling SSO, follow these steps:
    1) Run 'gdeploy update' to apply the changes to your CloudFormation deployment.
    2) Run 'gdeploy identity sync' to trigger an immediate sync of your user directory.