More than 1 year has passed since last update.

Azure AD(Microsoft Entra ID) の新しいインバウンドプロビジョニング API のリリース

Last updated at 2023-07-22Posted at 2023-07-22

Azure AD(Microsoft Entra ID) API 駆動型インバウンドプロビジョニング

個人的に ID エンジニアなら大切だとわかるけど、ID エンジニア以外にいまいちピンと来てもらえない ID 系話題 No1 はプロビジョニングです。

4/1 や 10/1 の度にやってくる大量の人事発令にげんなりし、前後の土日に死んだ表情で休日出勤をする、という経験は ID エンジニアなら皆あるはず。

当然、Azure AD(改め Microsoft Entra ID) でもプロビジョニングは ID 基盤を下支えする重要なタスクではあるのですが、もうちょっと機能が増強されて欲しいな、と思っている領域でもあります。

特に、前述の 4/1 や 10/1 に受ける事になる Inbound プロビジョニングはオンプレミス AD や Workday などの限られた製品からの処理であればいいのですが、そうではない場合、Graph API による個別開発などを頑張る必要がありました。

今月、この Inbound プロビジョニングを強化する機能がリリースされたため、ご紹介したいと思います。

機能概要

この機能は Graph API として Inbound プロビジョニングを受け付けるように実装されています。その際に様々なデータソースに対応できるように、SCIM のスキーマでプロビジョニングの要求を受け付けられるようになっています。
　受け付けた要求に対して、属性の変換処理を Azure AD 側でやる事もできますし、エージェントを利用する事で、Azure AD のエンドポイントで受けたユーザープロビジョニング要求をオンプレミス AD に反映させる事も可能です(その場合は、Azure AD には AAD Connect か Cloud Sync で同期する事になります)

これにより、特に独自の人事データベースや複数の ID 製品を併用しているお客様で Azure AD への Inboud プロビジョニングの自由度が上がる事が期待されます.

なお、現時点の実装としては、SCIM の CRUD に対応しているわけではなく、あくまで Bulk Operation としての受け付けになっていますのでその点は注意が必要です。

それでは構築手順を紹介していきます。

構築手順

0.参考ドキュメント

API 駆動型インバウンドプロビジョニングアプリの構成
 インバウンドプロビジョニング API へのアクセスを付与する
 cURL を使用した API 駆動インバウンドプロビジョニングのクイックスタート
 Perform bulkUpload(Graph API リファレンス)

1. API 駆動型プロビジョニングアプリの作成

まずは、Azure AD 側でプロビジョニングの処理(要求を受けて Azure AD にユーザー改廃を行うアプリケーションを作成します。公式ドキュメントなんかでは、API 駆動型プロビジョニングアプリと呼ばれているようです。

Microsoft Entra Portal にアクセスします。
[Azure Active Directory] -> [アプリケーション] -> [エンタープライズアプリケーション] を参照します。[新しいアプリケーション] をクリックして、新しいプロビジョニングアプリケーションを作成します。
検索フィールドに「API-driven」と入力し、セットアップするアプリケーションを選択します。今回はオンプレミス AD を考慮せず、Azure AD へのプロビジョニングを行います.
[名前] フィールドで、任意の名前を変更し、[作成] をクリックします。アプリケーションは複数作成する事が可能です.例えば、取り込み時のソースに合わせて変換規則を変える場合などです。その場合は取り込元などがわかりやすい名前にしておくと良いでしょう.
アプリケーションの作成が正常に完了したら、[Privisoning] に移動し、[Get started] をクリックします。

[プロビジョニングモード] を [手動] から [自動] に切り替えます。
保存が完了すると、さらに 2 つの拡張パネル ([マッピング] 用と [設定] 用) が表示されます。次の手順に進む前に、有効な通知メールアドレスを指定し、構成をもう一度保存する必要があります。※通知メールアドレスは必須の模様
マッピングでは SCIM のスキーマから Azure AD へのプロパティ取り込みとして基本のセットが設定されています.この規則は ID データソースに合わせてカスタマイズする事も可能です.
マッピングの完了後、プロビジョニングアプリケーションの [プロビジョニング] ->[概要] ページを開きます。

1.以下の Provisoning API Endpoint を控えておきます.

2. API 実行用アプリケーションを登録してアクセスを付与する

続いて、前の手順で作成した API 駆動型プロビジョニングアプリに対して API を実行用のアプリケーションを作成し、API 実行許可を与えます。

グローバル管理者またはアプリケーション管理者のログイン資格情報を使用して、Microsoft Entra ポータル (https://entra.microsoft.com) にログインします。
[Azure Active Directory] ->[アプリケーション] ->[アプリの登録] に移動します。
オプション [新規登録] をクリックします。アプリ名を指定し、既定のオプションを選択して、[登録] をクリックします。
[概要] から [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値をコピーし、後で API クライアントで使用できるように保存します。
アプリのコンテキストメニューで、[Certificates & secretes] を選択します。
新しいクライアントシークレットを作成します。シークレットと有効期限の説明を入力します。
生成されたクライアントシークレットの値をコピーし、後で API クライアントで使用するために保存します。
[API Permissions] から、オプション [権限の追加] を選択します。
[API 権限の要求] で、[Microsoft Graph] を選択します。
[アプリケーションのアクセス許可] を選択します。
[AuditLog.Read.All] と [SynchronizationData-User.Upload] を検索して選択します。
次の画面で [管理者の同意の付与] をクリックして、権限の割り当てを完了します。確認ダイアログで [はい] をクリックします。アプリには次の権限セットがあるはずです。

3. Provisoning を試す

3-1 トークンの取得

アクセストークンを取得します。色々な取得方法がありますが、PowerShell のスクリプトのサンプルを置いておきます。
※極力簡単にトークンを取得する事を目的としてるため、Windwos 10 の標準コマンドレットでの取得を行っています。実環境で継続的に運用するのであれば、MSAL モジュールなどを利用して、証明書を使ったトークンを利用する事などを検討した方が良いでしょう。

Get-Token.ps1

# param

$appID = <Your Client ID>
$sec = <Your Secrets>
$tenantID = <Your TenantID>
[System.Uri]$tokenurl = "https://login.microsoftonline.com/$tenantID/oauth2/v2.0/token" 

#
# get access token
#

$headers = @{
  "Content-Type" = "application/x-www-form-urlencoded"}

$params = @{
  "client_id"=$appID; 
  "scope"="https://graph.microsoft.com/.default"; 
  "client_secret"=$sec;
  "grant_type"="client_credentials"}


$res = Invoke-RestMethod -Method POST -body $params -Uri  $tokenurl
$res.access_token

結果は以下のように長い文字列のアクセストークンが取得できるのでこの内容を控えておきます。

3-2 プロビジョニングの実行

今回は postman を利用してプロビジョニング API の実行を行います。
Web のリクエストを実行出来れば特になんでも良く、公式のドキュメントでは cURL を利用していますが、本記事では直観的にわかりやすいため、Postman を紹介しています。

Postman を初めて利用する場合は Sign Up を行ってください。
サインインアップとサインインが完了したら上部メニューから Worksapces をクリックして、[Create Workspace] を行います。
デフォルトの内容で問題ないので、[Next] をクリックします。
目的がわかりやすい名前を付けておくと便利です。[Who can access your workspace?] は "Personal" を選択して[Create] をクリックします。
Workspace が開いたら[+]をクリックします。
Postman の [Authorization] 設定を開き、 "Bearer Token" を選びます。
アクセストークンの取得手順で控えておいたトークンを指定します。(有効期限は 1 時間なので注意。改めてこのタイミングで取り直しても良いでしょう)
[Headers] 設定を開き、Content-Type の指定をします。Key : Content-Type / Value : application/scim+json
[Body] 設定を開き、要求の payload を指定します。種類は "row" に指定します。指定後、URL 欄にエンドポイントの API を指定し、メソッドを "POST" にして[Send]をクリックします。けっかとして、"202"　が返ってくると成功です。

サンプルデータはまずは API のリファレンスページから取得すると良いでしょう。

以下の例では以下の 2 ユーザーを作成しています。
bjensen@example.com
Kjensen@example.com

users.json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "id": "2819c223-7f76-453a-919d-413861904646",
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
                  "displayName": "John Smith"
                 }
            }
        }
    },
    {
        "method": "POST",
        "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "id": "2819c223-7f76-453a-919d-413861904646",
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
            "employeeNumber": "701984",
            "costCenter": "4130",
            "organization": "Universal Studios",
            "division": "Theme Park",
            "department": "Tour Operations",
            "manager": {
              "value": "89607",
              "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
              "displayName": "John Smith"
             }
            }
        }
    }
],
    "failOnErrors": null
}

4. 結果の確認

Microsoft Entra Portal にアクセスします。
[Azure Active Directory] -> [アプリケーション] -> [エンタープライズアプリケーション]にアクセスし、作成しておいた、API 駆動型プロビジョニングアプリを開き、[プロビジョニング] を選択します。
プロビジョニングログを開いて、成功していると、作成されたユーザーの情報を確認する事が出来ます。