ネクストモードの赤井です。
はじめに
こんにちは、ネクストモード株式会社テクニカルサポート担当です。
Oktaには様々なAPIが用意されており、ユーザー属性の取得・更新やOktaグループの操作などが可能です。
今回、新たに利用可能になったGroup Push関連のAPIについてご紹介します。
Group Pushとは
Group Pushは、Oktaでプロビジョニング設定をしている場合に、Oktaグループをサービスプロバイダー(SP)側に反映できる機能です。これにより、SP側のグループ管理をOktaで一元的に行えるというメリットがあります。
なお、Group Pushで使用するOktaグループは、SSO認証時にアサインするOktaグループとは別に管理することが推奨されています。詳細は以下のOktaドキュメントをご参照ください。
Group Push APIの概要
以下の公式ドキュメントに従って、各APIエンドポイントについてrockstarで実行した結果を併せてご紹介します。
List all group push mappings
- メソッド：GET
- APIエンドポイント：/api/v1/apps/{appId}/group-push/mappings
アプリケーションIDを含むAPIエンドポイントを指定すると、そのアプリケーションに紐づくGroup Push情報を取得できます。アプリケーションIDは、Okta管理画面で該当のアプリケーションを開いたときにURLに表示されます。
rockstarで実行した結果は以下のとおりです。
表示される値について簡単に説明すると以下のようになります。
- created：Group Pushを設定した日時
- lastPush：最後にGroup Pushが実行された日時
- lastUpdated：最後にGroup Push設定が更新された日時
- sourceGroupId：OktaグループのID
- targetGroupId：SP側のグループID
targetGroupIdは、OktaがSP側のグループを把握するための内部IDです。管理画面のOktaグループ一覧では表示されませんが、以下のURLを直接指定するとSP側のグループとして表示できます。
https://<subdomain>-admin.okta.com/admin/group/{targetGroupId}
Create a group push mapping
- メソッド：POST
- APIエンドポイント：/api/v1/apps/{appId}/group-push/mappings
アプリケーションIDを含むAPIエンドポイントを指定し、BodyにsourceGroupId、statusそして、targetGroupIdまたはtargetGroupNameを指定することで新しいGroup Push設定を作成できます。
rockstarで実行した結果は以下のとおりです。
画像内のBodyは以下のとおりです。
{ "sourceGroupId": "00guakrnc06fe084L697", "status": "ACTIVE", "targetGroupName": "NewGroup"}
今回はSPとしてGoogle Workspaceを利用して検証しました。興味深いことに、targetGroupNameに指定した名称はSP側のグループに反映されず、代わりにsourceGroupIdで指定したOktaグループの名称が反映されていました。
Retrieve a group push mapping
- メソッド：GET
- APIエンドポイント：/api/v1/apps/{appId}/group-push/mappings/{mappingId}
アプリケーションIDとGroup PushのマッピングIDを含むAPIエンドポイントを指定すると、特定のGroup Push設定の詳細情報を取得できます。このAPIは「List all group push mappings」APIの結果から特定の1件だけを取得するのと同じ機能です。
rockstarで実行した結果は以下のとおりです。
Update a group push mapping
- メソッド：PATCH
- APIエンドポイント：/api/v1/apps/{appId}/group-push/mappings/{mappingId}
アプリケーションIDとGroup PushのマッピングIDを含むAPIエンドポイントを指定し、Bodyにstatusを指定することで、Group Push設定の有効化または無効化ができます。
rockstarで実行した結果は以下のとおりです。
画像内のBodyは以下のとおりです。
{ "status": "INACTIVE"}
Delete a group push mapping
- メソッド：DELETE
- APIエンドポイント：/api/v1/apps/{appId}/group-push/mappings/{mappingId}
アプリケーションIDとGroup PushのマッピングIDを含むAPIエンドポイントを指定することでGroup Push設定を削除できます。QueryパラメーターとしてdeleteTargetGroupにtrueを指定するとSP側のグループも削除されます。falseを指定するか何も指定しない場合は、SP側のグループは削除されません。rockstarでdeleteTargetGroupを指定する場合は /api/v1/apps/{appId}/group-push/mappings/{mappingId}?deleteTargetGroup=true と指定します。
注意点として、このAPIを実行する前に指定するマッピングIDのGroup Push設定が無効(INACTIVE)である必要があります。
rockstarで実行した結果は以下のとおりです。
まとめ
今回はGroup Push関連のAPIについてご紹介しました。Okta管理画面で行える操作がAPIを通じても実行できるようになったことは、特に自動化や大規模な環境での運用において非常に大きなメリットとなります。次回の記事では、Okta Workflowsからこれらの新しいAPIを活用した実践的な例を紹介し、実際の業務環境でどのように活用できるか、想定されるユースケースに沿った具体的な内容をご紹介する予定です。
