[アップデート] AWS IAM Identity CenterのAPIがユーザーとグループの作成・更新・削除に対応したのでAWS CLIで試してみた

yhana

2022.09.04

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

AWS IAM Identity Center (旧 AWS Single Sign-on) にユーザーやグループの作成・更新・削除を行う API が追加されたため、AWS CLI で試してみました。

これまでは AWS IAM Identity Center 内の ID ストアを利用している場合はマネジメントコンソールからユーザーの作成等を行う必要がありましたが、今回のアップデートにより AWS CLI や SDK を用いてユーザー管理を自動化できるようになりました。

Announcing new AWS IAM Identity Center (successor to AWS SSO) APIs to manage users and groups at scale

今回のアップデート内容は AWS のブログでも紹介されています。このブログではユーザー管理のためのサンプルスクリプト aws-samples/iam-identitycenter-identitystoreapi-operations が紹介されています。

Scale your workforce access management with AWS IAM Identity Center (previously known as AWS SSO) | AWS Security Blog

API リファレンスのページです。

Welcome to the Identity Store API Reference - Identity Store

AWS CLI のページです。

identitystore — AWS CLI 2.7.29 Command Reference

identitystore — AWS CLI 1.25.67 Command Reference

AWS CLI で試してみた

AWS IAM Identity Center には AWS Single Sign-on だった頃から次の AWS CLI があり、AWS IAM Identity Center に名前変更された後も下位互換性維持のために変更されていません。

（参考）IAM Identity Center とは - AWS IAM Identity Center (successor to AWS Single Sign-On)

今回のアップデートは AWS IAM Identity Center　内の ID ストアを管理するidentitystoreコマンドに関するものであり、新しくユーザーやグループの追加・更新・削除ができるようになりました。identitystoreコマンド自体はこれまでもありましたが、アップデート以前はユーザーやグループの作成・更新・削除はできませんでした。

本ブログでは、ID ストアとして Identity Center ディレクトリを利用する環境で、グループとユーザーを作成した後に更新し、最後に削除する流れで試してみます。

AWS CLI のバージョンは 2.7.29 を使用します。

$ aws --version
aws-cli/2.7.29 Python/3.9.11 Linux/4.14.287-215.504.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off

2022 年 9 月 3 日時点では、AWS CloudShell で利用する場合は AWS CLI のバージョンアップが必要になります。アップデートは次の方法でできます。

$ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
$ unzip awscliv2.zip
$ sudo ./aws/install --update
You can now run: /usr/local/bin/aws --version
$ aws --version
aws-cli/2.7.29 Python/3.9.11 Linux/4.14.287-215.504.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off

まずはidentitystoreで利用できるコマンドを確認してみます。以前は、describe-group,describe-user,list-groups,list-users,helpの5つだけでしたが、増えています。

$ aws identitystore ?

usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help

aws: error: argument operation: Invalid choice, valid choices are:

create-group                             | create-group-membership
create-user                              | delete-group
delete-group-membership                  | delete-user
describe-group                           | describe-group-membership
describe-user                            | get-group-id
get-group-membership-id                  | get-user-id
is-member-in-groups                      | list-group-memberships
list-group-memberships-for-member        | list-groups
list-users                               | update-group
update-user                              | help

グループとユーザーの作成と関連付け

始めに、下記のコマンドでグループを作成してみます。

aws identitystore create-group \
  --identity-store-id d-123456a7890 \
  --display-name test-group

グループ作成と参照の実行結果です。

$ aws identitystore create-group --identity-store-id d-123456a7890 --display-name test-group
{
    "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
    "IdentityStoreId": "d-123456a7890"
}

$ aws identitystore describe-group --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be
{
    "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
    "DisplayName": "test-group",
    "IdentityStoreId": "d-123456a7890"
}

次に、下記のコマンドでユーザーを作成します。ユーザーの属性情報として表示名、名、姓、E メールアドレスを指定しています。名、姓はname (structure)で指定し、E メールアドレスはemails (list)で指定します。

aws identitystore create-user \
  --identity-store-id d-123456a7890 \
  --user-name test-user1 \
  --display-name 'Test User1' \
  --name '{"FamilyName":"User1","GivenName":"Test"}' \
  --emails '[{"Value":"test-user1@example.com","Type":"Work","Primary":true}]'

ユーザー作成と参照の実行結果です。

$ aws identitystore create-user --identity-store-id d-123456a7890 --user-name test-user1 --display-name 'Test User1' --name '{"FamilyName":"User1","GivenName":"Test"}' --emails '[{"Value": "test-user1@example.com","Type": "Work","Primary": true }]'
{
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "IdentityStoreId": "d-123456a7890"
}

$ aws identitystore describe-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd
{
    "UserName": "test-user1",
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "Name": {
        "FamilyName": "User1",
        "GivenName": "Test"
    },
    "DisplayName": "Test User1",
    "Emails": [
        {
            "Value": "test-user1@example.com",
            "Type": "Work",
            "Primary": true
        }
    ],
    "IdentityStoreId": "d-123456a7890"
}

ユーザーを参照するdescribe-userではユーザー ID を指定する必要があります。ユーザー ID はget-user-idコマンドによりユーザー名から取得することもできます。

$ aws identitystore get-user-id --identity-store-id d-123456a7890 --alternate-identifier '{"UniqueAttribute":{"AttributePath":"userName","AttributeValue":"test-user1"}}'
{
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "IdentityStoreId": "d-123456a7890"
}

alternate-identifierオプションでUserName属性のパスであるuserNameを指定しています。

{
	"UniqueAttribute": {
		"AttributePath": "userName",
		"AttributeValue": "test-user1"
	}
}

パス情報は次のページに情報があります。他に一覧が掲載されているページがあるかもしれませんが、見つけられませんでした。

属性マッピング - AWS IAM Identity Center (successor to AWS Single Sign-On)

試しに AttributePath としてdisplayNameを指定してget-user-idコマンドを実行したところ、ユニークな属性ではないということでエラーとなりました。

$ aws identitystore get-user-id --identity-store-id d-123456a7890 --alternate-identifier '{"UniqueAttribute":{"AttributePath":"displayName","AttributeValue":"Test User1"}}'

An error occurred (ValidationException) when calling the GetUserId operation: The attribute displayName is not a unique attribute

作成したユーザーをマネジメントコンソールで確認した画面です。E メール検証が必要となりますが、今回はテスト用のドメインなのでこのままにしておきます。

次に、グループとユーザーの関連付けを行います。

下記の構成でグループとユーザーの関連付けを行いたいため、test-user2 を追加で作成します。

test-group
- test-user1
- test-user2

$ aws identitystore create-user --identity-store-id d-123456a7890 --user-name test-user2 --display-name 'Test User2' --name '{"FamilyName":"User2","GivenName":"Test"}' --emails '[{"Value": "test-user2@example.com","Type":"Work","Primary":true}]'
{
    "UserId": "77c46ae8-60c1-708c-fce4-e1f7ee21d4df",
    "IdentityStoreId": "d-123456a7890"
}

create-group-membershipコマンドで関連付けを行います。

$ aws identitystore create-group-membership --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be --member-id '{"UserId":"37a43ab8-70a1-7089-7c5c-453169bc8ccd"}'
{
    "MembershipId": "27345a28-e0c1-7054-1221-b78d4427ea59",
    "IdentityStoreId": "d-123456a7890"
}

$ aws identitystore create-group-membership --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be --member-id '{"UserId":"77c46ae8-60c1-708c-fce4-e1f7ee21d4df"}'
{
    "MembershipId": "27e4da38-2001-7077-ad46-26c2be671291",
    "IdentityStoreId": "d-123456a7890"
}

member-idオプションの値は次の形式で指定しています。

{
  "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd"
}

list-group-membershipsコマンドを用いることでグループ ID を指定して所属しているユーザーを確認できます。

$ aws identitystore list-group-memberships --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be
{
    "GroupMemberships": [
        {
            "IdentityStoreId": "d-123456a7890",
            "MembershipId": "27345a28-e0c1-7054-1221-b78d4427ea59",
            "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
            "MemberId": {
                "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd"
            }
        },
        {
            "IdentityStoreId": "d-123456a7890",
            "MembershipId": "27e4da38-2001-7077-ad46-26c2be671291",
            "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
            "MemberId": {
                "UserId": "77c46ae8-60c1-708c-fce4-e1f7ee21d4df"
            }
        }
    ]
}

describe-group-membershipコマンドでは、メンバーシップ ID を指定してグループとユーザーの関連付け情報を確認できます。

$ aws identitystore describe-group-membership --identity-store-id d-123456a7890 --membership-id 27345a28-e0c1-7054-1221-b78d4427ea59
{
    "IdentityStoreId": "d-123456a7890",
    "MembershipId": "27345a28-e0c1-7054-1221-b78d4427ea59",
    "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
    "MemberId": {
        "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd"
    }
}

マネジメントコンソールで確認したところ、ユーザーとグループの関連付けを確認できました。

グループとユーザーの関連付けを確認するコマンドは、上記で試したlist-group-membershipsコマンド以外にもあります。

list-group-memberships-for-memberはユーザー ID を指定してユーザーが所属しているグループを調べるコマンドです。

$ aws identitystore list-group-memberships-for-member --identity-store-id d-123456a7890 --member-id '{"UserId":"37a43ab8-70a1-7089-7c5c-453169bc8ccd"}'
{
    "GroupMemberships": [
        {
            "IdentityStoreId": "d-123456a7890",
            "MembershipId": "27345a28-e0c1-7054-1221-b78d4427ea59",
            "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
            "MemberId": {
                "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd"
            }
        }
    ]
}

is-member-in-groupsは指定した複数のグループに対して指定したユーザーが存在するかどうかを返答するコマンドです。次の例ではtest-groupにtest-user1が含まれるためMembershipExistsがtrueで返されています。

$ aws identitystore is-member-in-groups --identity-store-id d-123456a7890 --member-id '{"UserId":"37a43ab8-70a1-7089-7c5c-453169bc8ccd"}' --group-ids 37d4ba58-6051-7062-5dfc-bd96792cf7be
{
    "Results": [
        {
            "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
            "MemberId": {
                "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd"
            },
            "MembershipExists": true
        }
    ]
}

グループとユーザーを作成した後は、従来通りsso-adminコマンドを用いてアクセス許可セットの作成やアクセス許可セットとグループの関連付け設定を行う流れとなります。

sso-admin — AWS CLI 2.7.29 Command Reference

今回は、アクセス許可セットの作成や関連付けは行わずに作成したグループとユーザーの更新と削除を行いたいと思います。

グループとユーザーの更新

グループの設定変更を試します。

update-groupコマンドでtest-groupの表示名をtest-group-changedに変更します。

$ aws identitystore update-group --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be --operations '[{"AttributePath":"displayName","AttributeValue":"test-group-changed"}]'

operationsオプションで指定している内容は次の通りです。

[
  {
    "AttributePath": "displayName",
    "AttributeValue": "test-group-changed"
  }
]

変更されていることを確認できました。

$ aws identitystore describe-group --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be
{
    "GroupId": "37d4ba58-6051-7062-5dfc-bd96792cf7be",
    "DisplayName": "test-group-changed",
    "IdentityStoreId": "d-123456a7890"
}

次に、update-userコマンドでユーザーtest-user1の表示名をTest User1 Changedに変更してみます。

$ aws identitystore update-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd --operations '[{"AttributePath":"displayName","AttributeValue":"Test User1 Changed"}]'

operationsオプションで指定している内容です。

[
  {
    "AttributePath": "displayName",
    "AttributeValue": "Test User1 Changed"
  }
]

変更されていることを確認できました。

$ aws identitystore describe-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd
{
    "UserName": "test-user1",
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "Name": {
        "FamilyName": "User1",
        "GivenName": "Test"
    },
    "DisplayName": "Test User1 Changed",
    "Emails": [
        {
            "Value": "test-user1@example.com",
            "Type": "Work",
            "Primary": true
        }
    ],
    "IdentityStoreId": "d-123456a7890"
}

ユーザーに対して次の2つの属性（タイムゾーンとロケール）の追加を試してみます。

[
  {
    "AttributePath": "timezone",
    "AttributeValue": "Asia/Tokyo"
  },
  {
    "AttributePath": "locale",
    "AttributeValue": "Japan"
  }
]

属性を追加します。

$ aws identitystore update-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd --operations '[{"AttributePath":"timezone","AttributeValue":"Asia/Tokyo"},{"AttributePath":"locale","AttributeValue":"Japan"}]'

LocaleとTimezoneの属性追加を確認できました。

$ aws identitystore describe-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd
{
    "UserName": "test-user1",
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "Name": {
        "FamilyName": "User1",
        "GivenName": "Test"
    },
    "DisplayName": "Test User1 Changed",
    "Emails": [
        {
            "Value": "test-user1@example.com",
            "Type": "Work",
            "Primary": true
        }
    ],
    "Locale": "Japan",
    "Timezone": "Asia/Tokyo",
    "IdentityStoreId": "d-123456a7890"
}

ロケール属性の削除も試してみます。削除は AttributeValue を指定しないことで実現できそうです。

[
  {
    "AttributePath": "locale"
  }
]

属性削除を実行します。

$ aws identitystore update-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd --operations '[{"AttributePath": "locale"}]'

Locale属性の削除を確認できました。

$ aws identitystore describe-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd
{
    "UserName": "test-user1",
    "UserId": "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "Name": {
        "FamilyName": "User1",
        "GivenName": "Test"
    },
    "DisplayName": "Test User1 Changed",
    "Emails": [
        {
            "Value": "test-user1@example.com",
            "Type": "Work",
            "Primary": true
        }
    ],
    "Timezone": "Asia/Tokyo",
    "IdentityStoreId": "d-123456a7890"
}

グループとユーザーの削除

最後にこれまで作成したグループとユーザーの削除を試してみます。

まず、delete-group-membershipコマンドでメンバーシップを削除します。

$ aws identitystore list-group-memberships --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be --query 'GroupMemberships[].MembershipId'
[
    "27345a28-e0c1-7054-1221-b78d4427ea59",
    "27e4da38-2001-7077-ad46-26c2be671291"
]

$ aws identitystore delete-group-membership --identity-store-id d-123456a7890 --membership-id 27345a28-e0c1-7054-1221-b78d4427ea59
$ aws identitystore delete-group-membership --identity-store-id d-123456a7890 --membership-id 27e4da38-2001-7077-ad46-26c2be671291

$ aws identitystore list-group-memberships --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be
{
    "GroupMemberships": []
}

次に、delete-userコマンドでユーザーを削除します。

$ aws identitystore list-users --identity-store-id d-123456a7890 --query 'Users[].UserId'
[
    "37a43ab8-70a1-7089-7c5c-453169bc8ccd",
    "77c46ae8-60c1-708c-fce4-e1f7ee21d4df"
]

$ aws identitystore delete-user --identity-store-id d-123456a7890 --user-id 37a43ab8-70a1-7089-7c5c-453169bc8ccd
$ aws identitystore delete-user --identity-store-id d-123456a7890 --user-id 77c46ae8-60c1-708c-fce4-e1f7ee21d4df

$ aws identitystore list-users --identity-store-id d-123456a7890
{
    "Users": []
}

最後に、delete-groupコマンドでグループを削除します。

$ $ aws identitystore list-groups --identity-store-id d-123456a7890 --query 'Groups[].GroupId'
[
    "37d4ba58-6051-7062-5dfc-bd96792cf7be"
]

$ aws identitystore delete-group --identity-store-id d-123456a7890 --group-id 37d4ba58-6051-7062-5dfc-bd96792cf7be

$ aws identitystore list-groups --identity-store-id d-123456a7890
{
    "Groups": []
}

以上で、作成したグループとユーザーの削除は完了です。

さいごに

これまで、AWS IAM Identity Center におけるユーザーの作成等はマネジメントコンソールで行う必要がありましたが、API のアップデートにより AWS CLI や SDK を用いてユーザーとグループの作成・更新・削除ができるようになりました。ユーザー管理の自動化に繋がるうれしいアップデートでした。

グループとユーザーの情報を参照するコマンドも増えているので、外部　ID プロバイダーと連携した環境でもできることが増えています。

最後に余談ですが、AWS IAM Identity Center に名称変更した際に用語も変わっています。ユーザーのことは「ワークフォースユーザー」または「ユーザー」との用語定義なので、このブログでは「ユーザー」と呼ぶことにしました。

（参考）IAM Identity Center とは - AWS IAM Identity Center (successor to AWS Single Sign-On)