AWS Platform Guide

Set up accounts

In order to fully deploy the platform, it’s recommended to set up the conventional accounts:

• Operations: CI/CD pipelines and centralized monitoring
• Network: centralized DNS and networking
• Sandbox: staging and development workloads
• Production: production workloads
• Identity: permission sets and identity provider
• Backup: backup policies and isolated vaults

It may take some time for all the required accounts to be provisioned. Once all the accounts are fully enrolled, you are ready to create VPC networks.

Configure Single Sign On

1. Configure your SSO identity store using the single sign-on guide.
2. From the Single Sign-On configuration page, customize the start URL for your user portal so that it’s easier to remember (Note, your start URL cannot be modified once it has been customized).
3. Delegate IAM administration from the Management account to the Identity account following the delegated administration guide.
4. Accept the invitation in your email to join AWS SSO.
5. Sign out of the IAM management user and sign into the newly created SSO portal.

You can find detailed instructions for specific identity providers:

• Google Sign In
• Microsoft SSO

Google Sign In

You will need to be an administrator for the Google domain to follow these instructions. This may require setting up a screen sharing session with somebody else who has access.

If you’re using Google as a sign-in provider, you’ll also want to deploy the sso-sync Lambda to automatically provision user accounts in Identity Center. Otherwise, users will need to be manually added in both Google and AWS.

1. Set Google as an external identity provider using the above guide.
2. You should have a Identity account for managing SSO identities. This is created if you’re using the accounts.yaml file from the template.
3. Deploy the sso-sync Lambda to the Identity account using the instructions below.

SSO Sync Lambda

From the Google cloud console, create a new project for the Lambda’s credentials. Give it a name that makes it clear why the project exists, such as “aws-google-sso-sync.”

To be performed by Google Admin:

Follow the Google tutorial to create a service account:

1. In the Google Cloud console, go to IAM & Admin > Service Accounts.
2. Click Create service account.
3. Give your service account a name and description, then click Create and continue.
4. Click Continue.
5. Click Done.

Create credentials for your service account:

1. Click Keys > Add key > Create new key.
2. Select JSON, then click Create.
3. Make a note of the downloaded credentials file.
4. Click Close.
5. Expand Advanced Settings.
6. Save the Client ID under Domain-wide Delegation.

Now enable the Admin SDK:

1. In the Google Cloud console, go to APIs & Services > Enabled APIs & services.
2. Click Enable APIs and Services.
3. Search for Admin SDK API.
4. Click the Enable button.

Now enable domain-wide delegation for your service account:

1. From the Google admin console, go to Security > API Controls > Domain-wide Delegation.
2. Click Add new.
3. Fill in the Client ID for the service account you saved earlier.
4. Under OAuth scopes, specify the following: https://www.googleapis.com/auth/admin.directory.group.readonly https://www.googleapis.com/auth/admin.directory.group.member.readonly https://www.googleapis.com/auth/admin.directory.user.readonly
5. Click Authorize.

To be performed by Infra Dev:

Enable SCIM for your Identity Center directory:

1. Sign into the Identity account from your AWS landing zone.

2. From AWS IAM Identity Center settings, within the Automatic provisioning information box, choose Enable.

3. Save the displayed SCIM endpoint and Access token.

4. Create a new Terraform module in the infrastructure repository under sso-sync/secrets to store the credentials:

   module "secret" {
     source = "github.com/thoughtbot/terraform-aws-secrets//secret?ref=v0.8.0"
   
     description = "Secrets for deploying the AWS/Google SSO Sync Lambda"
     name        = "aws-google-sso-sync"
   
     initial_value = jsonencode({
       GoogleCredentials       = ""
       SCIMEndpointAccessToken = ""
       SCIMEndpointUrl         = ""
     })
   }

5. Apply the Terraform module.

6. From AWS Secrets Manager, find the created secret.

7. Click Retrieve Secret Value and then click Edit.

8. Copy the contents of the JSON credentials file you downloaded into the GoogleCredentials field.

9. Fill in the SCIMEndpointAccessToken and SCIMEndpointUrl values you saved earlier.

10. Click Save.

11. Create a new Terraform module in the infrastructure repository under sso-sync/lambda to deploy the SSOSync Lambda:

    module "lambda" {
      source = "github.com/thoughtbot/terraform-aws-google-sso?ref=v0.1.0"
    
      google_admin_email         = "google-admin@example.com"
      google_credentials         = local.secrets.GoogleCredentials
      google_group_match         = "email:aws-*"
      name                       = "aws-google-sso-sync"
      scim_endpoint_access_token = local.secrets.SCIMEndpointAccessToken
      scim_endpoint_url          = local.secrets.SCIMEndpointUrl
      semantic_version           = "2.0.2"
    }
    
    locals {
      secrets = jsondecode(
        data.aws_secretsmanager_secret_version.sso_sync.secret_string
      )
    }
    
    data "aws_secretsmanager_secret_version" "sso_sync" {
      secret_id = "aws-google-sso-sync"
    }

12. Apply the module.

IAM Identity Center will now automatically synchronize matched groups and users from your Google domain.

Updating the SCIM Token

You will need to regularly update the SCIM token as it expires to continually provision users and groups: Update SCIM tokens

Microsoft SSO

References

• https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/aws-single-sign-on-tutorial
• https://www.youtube.com/watch?v=WSd0POCqklY

Note:

When following the above youtube tutorial and creating a non-gallery SSO app, we encountered an issue that was due to duplicate users in AWS. Therefore, we need to ensure that existing groups don’t have users with the same email in Microsoft. It may be best to use the “AWS IAM Identity Center” application from the Microsoft enterprise app gallery. The following instructions still apply except for the initial bullet point for app creation in Microsoft section

Prerequisites

1. Identify AWS groups with the appropriate target permission sets / account assignments
2. Ensure those same group names exist within Microsoft
   • Owners / members should be set appropriately
3. Create backup IAM admin user with access to identity center in AWS in case changes need to be reverted

In AWS

1. Change IdP to external
2. Download metadata file

In Microsoft

1. Create new enterprise app (non-gallery app)
2. In single sign-on section, select SAML
3. Upload metadata file from AWS
4. Save the SAML config
5. Download federation metadata xml

In AWS

1. Upload metadata file from Microsoft
2. Finish changing identity source
3. Enable automatic provisioning
4. Copy SCIM endpoint / access token for use in Microsoft

In Microsoft

1. In Provisioning section, set mode to automatic
2. Set tenant url to SCIM endpoint, secret token to access token (from the previous AWS provisioning setup screen)
3. Test connection
4. Save provisioning config
5. Make sure to assign groups to enterprise app
6. Then start provisioning