Published on

Using IAM Identity Center through the Command Line

Authors

IAM Identity Center is the successor product to AWS Single Signon (AWS SSO), which is mostly used in multi-account AWS environments to manage user access and roles across an AWS Organisation.

Identity Center can also be accessed from the AWS CLI, but the relationship between the old and new components is unclear in the documentation, so I've written some instructions below.

Before you start

Make sure you have set up your ~/.aws/config with the profile information to access your root account through AWS SSO e.g.:

[profile root]
sso_start_url=https://my-company-namespace.awsapps.com/start
sso_region=us-east-2 # where your organisation is set up
sso_account_id=123456789012 # root account ID
sso_role_name=AWSAdministratorAccess
region=us-east-2 # default region for operations
output=json

The service namespaces

Identity Center exists in a sort of half-migrated state between the old AWS SSO product and its shared naming with IAM. You will need to use them in concert in order to perform the same tasks you can access in the AWS Console.

One of the confusing concepts is that of an Identity Store. AWS don't seem to document it, but it seems to refer to your identity provider connection to AWS SSO. You can discover its details through aws sso-admin list-instances.

This is confusing through the CLI, so here is a breakdown of the namespaces for you:

  • aws sso - list AWS accounts and login to an AWS profile (configured in ~/.aws/config) through SSO
  • aws sso-admin - manage permission sets and retrieve your Identity Store ID
  • aws identitystore - manage users and groups within an Identity Store

Login to your root account

Use aws sso login --profile root to login to your root account (after you have configured as above).

Export the profile name to your environment to save passing the --profile argument to each command e.g.:

export AWS_PROFILE=root

Retrieve your Identity Store ID

aws sso-admin list-instances will list your identity stores - you should have only one.

You need the IdentityStoreId and InstanceArn property for some of the following commands. An easy way to save that is with an environment variable e.g.:

export IDENTITY_STORE_ID=$(aws sso-admin list-instances --query "Instances[0].IdentityStoreId" --output text)
export INSTANCE_ARN=$(aws sso-admin list-instances --query "Instances[0].InstanceArn" --output text)

List Groups

aws identitystore list-groups --identity-store-id <IdentityStoreId>

Record the GroupId property of the group you'd like to manipulate.

List Users

aws identitystore list-users --identity-store-id <IdentityStoreId>

Record the UserId property of the group you'd like to manipulate.

or to find a particular user:

aws identitystore list-users --identity-store-id <IdentityStoreId> --query "Users[?UserName == 'user@mycompany.com']"

(UserName can be substituted for other properties - see the JMESPath Tutorial for examples)

Find a group

You can also find groups by a unique attribute with the get-group-id command e.g.

aws identitystore get-group-id --identity-store-id <IdentityStoreId> --alternate-identifier '{"UniqueAttribute":{"AttributePath": "DisplayName","AttributeValue":"My-Group-Name"}}'

The --alternate-identifier parameter has to be a JSON to use it on the command line, and the AttributePath must be one of the group attributes returned in list-groups.

This syntax can be rather clunky, so a simple JMESPath on list-groups can be easier:

aws identitystore list-groups --identity-store-id <IdentityStoreId> --query "Groups[?DisplayName == 'My-Group-Name'].GroupId" --output text

Add a user to a group

aws identitystore create-group-membership --identity-store-id <IdentityStoreId> --group-id <GroupId> --member-id UserId=<UserId>

List permission sets

aws sso-admin list-permission-sets --instance-arn <InstanceArn>

Only the ARNs are list of the permission sets are printed - you'll need to use aws sso-admin describe-permission-set to get details about it.

Discuss on Twitter