How to Manage AWS SSO Account Assignments in CloudFormaton

Here's a sample template

https://github.com/hayao-k/aws-sso-cloudformation-sample

Introduction

On 9/10/2020, AWS SSO API (sso-admin) was finally added to AWS Single Sign-On and operations through the AWS CLI/SDK and CloudFormation are now supported.

🚀 AWS Single Sign-On adds account assignment APIs and AWS CloudFormation support to automate multi-account access management

Until now, operations such as permission sets and assigning users/groups to AWS accounts had to be configured manually in the console.
This update paves the way for automating account assignment settings and getting to IaC!

Supported CloudFormation resources

As of September 2020, CloiudFormation will support the following two resources.

• AWS::SSO::PermissionSet
  Specifies the permissions to be set on the AWS SSO instance.

• AWS::SSO::Assignment
  Assign access to your AWS account using the specified permission set.

Points to note

Creating an AWS SSO resource in CloudFormation requires various IDs such as InstanceArn, Identiy-Store-Id, UserId, and GroupId.
These IDs are not display in the AWS SSO console and must be obtained via API.
To use the AWS SSO API (sso-admin), make sure you have AWS CLI version 1.18.136 or 2.0.48 or higher.

Example of a permission set

This is an example of creating a simple set of permissions using AWS management policies.

PermissionSet:
  Type: AWS::SSO::PermissionSet
  Properties:
    InstanceArn: 'arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx'
    Name: 'AdministratorAccess'
    ManagedPolicies:
    - 'arn:aws:iam::aws:policy/AdministratorAccess'

For InstanceArn, specify the ARN of the SSO instance.
This value is obtained from list-instances in sso-admin.

$ aws sso-admin list-instances
{
    "Instances": [
        {
            "InstanceArn": "arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx",
            "IdentityStoreId": "d-xxxxxxxxxx"
        }
    ]
}

Example of Account Assignment

Specify the AWS account, privilege set, and principal as follows.

Assignment: 
  Type: AWS::SSO::Assignment
  Properties: 
    InstanceArn: 'arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx'
    PermissionSetArn: 'arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxxx/ps-xxxxxxxxxxxxxxxx'
    TargetId: '123456789012'
    TargetType: AWS_ACCOUNT
    PrincipalId: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
    PrincipalType: 'GROUP'

You can check the PermissionSetArn with sso-admin's describe-permission-set.

$ aws sso-admin list-permission-sets \
> --instance-arn arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxxx 
{
    "PermissionSets": [
        "arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxxx/ps-xxxxxxxxxxxxxxxx",
        "arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxxx/ps-yyyyyyyyyyyyyyyy",
        "arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxxx/ps-zzzzzzzzzzzzzzzz"
    ]
}

$ aws sso-admin describe-permission-set \
> --instance-arn arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxx \
> --permission-set-arn arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxx/ps-xxxxxxxxxxxxxxx
{
    "PermissionSet": {
        "Name": "AdministratorAccess",
        "PermissionSetArn": "arn:aws:sso:::permissionSet/ssoins-xxxxxxxxxxxxxxx/ps-xxxxxxxxxxxxxxx",
        "CreatedDate": "2020-09-09T19:01:06.758000+09:00",
        "SessionDuration": "PT1H"
    }
}

If you have created a permission set in CloudFormation, use the built-in Fn::GetAtt function.

    PermissionSetArn: !GetAtt LogicalId.PermissionSetArn

Only AWS_ACCOUNT can be specified for TargetType.
Specify the AWS account ID to be assigned for TargetId.

    TargetId: '123456789012'
    TargetType: AWS_ACCOUNT

PrincipalType can be specified as either USER or GROUP.
PrincipalId must be specified as the GUID of the user/group to be assigned.

    PrincipalId: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
    PrincipalType: 'GROUP'

Many operations of the AWS SSO API (sso-admin) rely on user and group identifiers called principals.
Use the AWS SSO Identity Store API (identitystore) to get the GUIDs for a user/group.

Specify the identity store identifier obtained from list-instances in sso-admin for --identity-store-id.
For list-users you can specify a UserName and for list-group you can specify a DisplayName as filter.

$ aws identitystore list-users \
> --identity-store-id d-xxxxxxxxxx \
> --filters AttributePath=UserName,AttributeValue="user@example.com"
{
    "Users": [
        {
            "UserName": "userXX@examle.com",
            "UserId": "f81d4faxge-7dec11d8-a765-3at5-80e4-00a0c91e6bf6"
        }
    ]
}

$ aws identitystore list-groups \
> --identity-store-id d-xxxxxxxxxx \
> --filters AttributePath=DisplayName,AttributeValue="TestGroup"
{
    "Groups": [
        {
            "GroupId": "f81d4faxge-789fcfa5-005c-4379-89ba-10a11e641c17"
            "DisplayName": "TestGroup"
        }
    ]
}

See the GitHub link at the top for the entire template.

Summary

• The AWS SSO API (sso-admin) has been added, enabling partial automation of administrative tasks and IaC
• CloudFormation supports permission set creation and account assignment
• User/Group IDs needed to identify principals must be obtained through the IdentityStore API
  • Full automation seems to be difficult at the moment because of the need to search for IDs when assigning accounts
  • AWS SSO console does not display these IDs and ARNs, which is a bit inconvenient
• That said, it's exciting to be able to manage AWS SSO with APIs!

References

AWS CloudFormation User Guide - SSO resource type reference
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_SSO.html

AWS CLI Command Reference - sso-admin
https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sso-admin/index.html

AWS CLI Command Reference - identitystore
https://awscli.amazonaws.com/v2/documentation/api/latest/reference/identitystore/index.html