セルフサービスサインアップフローにカスタム承認を追加する - Microsoft Entra External ID

[アーティクル]
02/05/2024

API コネクタを使用すると、独自のカスタム承認ワークフローをセルフサービスサインアップと統合できます。これにより、テナントに作成されるゲストユーザーアカウントを管理できます。

この記事では、承認システムと統合する方法の例を示します。この例では、セルフサービスサインアップユーザーフローがサインアッププロセス中にユーザーデータを収集し、データを承認システムに渡します。承認システムでは、次のことが可能です。

ユーザーを自動的に承認し、Microsoft Entra ID にユーザーアカウントの作成を許可します。
手動レビューをトリガーします。要求が承認された場合、承認システムは Microsoft Graph を使用してユーザーアカウントをプロビジョニングします。承認システムは、アカウントが作成されたことをユーザーに通知することもできます。

重要

2021 年 7 月 12 日以降、Microsoft Entra B2B のお客様が、カスタムまたは基幹業務アプリケーションのセルフサービスサインアップで使用するために新しい Google の統合をセットアップした場合、認証がシステム Web ビューに移動されるまで、Google ID を使用した認証が機能しなくなります。詳細情報を参照してください。
2021 年の 9 月 30 日より、Google は埋め込みの Web ビューのサインインサポートを廃止します。アプリで埋め込み Web ビューを使用してユーザーを認証していて、Google フェデレーションを Azure AD B2C、Microsoft Entra B2B (外部ユーザーの招待用)、またはセルフサービスサインアップで使用している場合、Google Gmail ユーザーが認証されなくなります。詳細情報を参照してください。

承認システム用のアプリケーションを登録する

ヒント

この記事の手順は、開始するポータルに応じて若干異なる場合があります。

承認システムをアプリケーションとして Microsoft Entra テナントに登録することで、承認システムを Microsoft Entra ID で認証し、承認システムがユーザーを作成するアクセス許可を持つようにすることができます。詳しくは、Microsoft Graph 用の認証および承認の基本に関する記事をご覧ください。

Microsoft Entra 管理センターにユーザー管理者以上でサインインしてください。
[ID]>[アプリケーション]>[アプリの登録] の順に移動して、[新規登録] を選択します。
アプリケーションの名前を入力します (Sign-up Approvals など)。
[登録] を選択します。他のすべてのフィールドは既定値のままにすることができます。

[登録] ボタンが強調表示されているスクリーンショット。

左のメニューの [管理] で、 [API のアクセス許可] を選択してから、 [アクセス許可の追加] を選択します。
[API アクセス許可の要求] ページで、 [Microsoft Graph] を選択し、 [アプリケーションのアクセス許可] を選択します。
[アクセス許可の選択] で、 [ユーザー] を展開して、 [User.ReadWrite.All] チェックボックスをオンにします。このアクセス許可は、承認システムが承認時にユーザーを作成することを許可します。 [アクセス許可の追加] を選択します。

API のアクセス許可のスクリーンショット。

[API のアクセス許可] ページで、 [(テナント名) に管理者の同意を与えます] を選択し、 [はい] を選択します。
左のメニューの [管理] で [証明書とシークレット] を選択してから、[新しいクライアントシークレット] を選択します。
シークレットの [説明] を入力し (たとえば、Approvals client secret (承認クライアントシークレット) )、クライアントシークレットが期限切れになるまでの期間を選択します。その後、 [追加] を選択します。
クライアントシークレットの値をコピーします。クライアントシークレットの値を表示できるのは、作成直後のみです。シークレットを作成したら、ページを離れる前に必ず保存してください。

クライアントシークレットのコピーのスクリーンショット。

クライアント ID としてのアプリケーション ID と、Microsoft Entra ID で認証するために生成した クライアントシークレットを使用するように承認システムを構成します。

API コネクタを作成する

次に、セルフサービスサインアップユーザーフロー用の API コネクタを作成します。承認システム API には、次に示す例のように、2 つのコネクタとそれに対応するエンドポイントが必要です。これらの API コネクタは次の処理を実行します。

承認状態の確認 - ユーザーが既存の承認要求を持っているか、既に拒否されているかどうかを確認するために、ユーザーが ID プロバイダーでサインインした直後に承認システムに呼び出しを送信します。承認システムが自動承認の決定のみを行う場合、この API コネクタは必要ないことがあります。 "承認状態の確認" API コネクタの例。

承認状態の確認 API コネクタ構成のスクリーンショット。

[要求の承認] - ユーザーが [属性のコレクション] ページに入力した後、ユーザーアカウントが作成される前に、承認を要求するために承認システムに呼び出しを送信します。承認要求は、自動的に許可したり手動で確認したりすることができます。 "要求の承認" API コネクタの例。

承認の要求 API コネクタ構成のスクリーンショット。

これらのコネクタを作成するには、「API コネクタを作成する」の手順に従います。

ユーザーフローで API コネクタを有効にする

ここで、次の手順を使用して、セルフサービスサインアップユーザーフローに API コネクタを追加します。

Microsoft Entra 管理センターにユーザー管理者以上でサインインしてください。
[ID]>[External identities]>[ユーザーフロー] の順に移動して、API コネクタを有効にするユーザーフローを選択します。
[API connectors](API コネクタ) を選択し、ユーザーフローの次の手順で呼び出す API エンドポイントを選択します。
- サインアップ中の ID プロバイダーとのフェデレーションの後: 承認状態 API コネクタ ( [承認状態の確認] など) を選択します。
- ユーザーを作成する前:承認要求 API コネクタを選択します。たとえば、 [要求の承認] を選択します。

ユーザーフロー内の API コネクタのスクリーンショット。

[保存] を選択します。

承認システムでは、呼び出し時にその応答を使用して、サインアップフローを制御できます。

"承認状態の確認" API コネクタの要求と応答

API によって "承認状態の確認" API コネクタから受信した要求の例:

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ //Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

API に送信される正確な要求は、ID プロバイダーによって提供される情報によって異なります。 "email" は常に送信されます。

"承認状態の確認" の継続応答

承認状態の確認 API エンドポイントは、次の場合に継続応答を返す必要があります。

ユーザーが以前承認を要求していない。

継続応答の例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

"承認状態の確認" のブロック応答

承認状態の確認 API エンドポイントは、次の場合にブロック応答を返す必要があります。

ユーザー承認が保留されている。
ユーザーが拒否され、再度承認を要求することができない。

ブロック応答の例は次のとおりです。

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

"要求の承認" API コネクタの要求と応答

API によって受信された "要求の承認" API コネクタからの HTTP 要求の例:

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

API に送信される正確な要求は、ユーザーから収集される情報または ID プロバイダーによって提供される情報によって異なります。

"要求の承認" の継続応答

要求の承認 API エンドポイントは、次の場合に継続応答を返す必要があります。

ユーザーを自動的に承認できる。

継続応答の例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

重要

継続応答を受信すると、Microsoft Entra ID によってユーザーアカウントが作成され、そのユーザーがアプリケーションに送られます。

"要求の承認" のブロック応答

要求の承認 API エンドポイントは、次の場合にブロック応答を返す必要があります。

ユーザー承認要求が作成されて現在保留になっている。
ユーザー承認要求が自動的に拒否された。

ブロック応答の例は次のとおりです。

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

応答内の userMessage がユーザーに表示されます。次に例を示します。

保留中の承認ページの例

手動承認後のユーザーアカウントの作成

カスタム承認システムは、手動承認を取得した後、Microsoft Graph を使用してユーザーアカウントを作成します。承認システムがユーザーアカウントをプロビジョニングする方法は、ユーザーによって使用された ID プロバイダーによって異なります。

Google または Facebook のフェデレーションユーザーおよび電子メールワンタイムパスコードの場合

重要

この方法を使用するには、承認システムは、identities、identities[0]、および identities[0].issuer が存在し、identities[0].issuer が 'facebook'、'google'、または 'mail' に一致することを明示的に確認する必要があります。

ユーザーが Google アカウント、Facebook アカウント、または電子メールワンタイムパスコードを使用してサインインした場合は、ユーザー作成 API を使用できます。

承認システムはユーザーフローから HTTP 要求を受信します。

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

承認システムは、Microsoft Graph を使用してユーザーアカウントを作成します。

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}

パラメーター	必須	説明
userPrincipalName	はい	API に送信された `email` 要求を取得し、`@` 文字を `_` に置き換え、これを `#EXT@<tenant-name>.onmicrosoft.com` の先頭に追加することによって生成できます。
accountEnabled	はい	`true` に設定する必要があります。
mail	はい	API に送信される `email` 要求と同じです。
userType	はい	`Guest`である必要があります。このユーザーをゲストユーザーとして指定します。
ID	はい	フェデレーション ID 情報。
<otherBuiltInAttribute>	いいえ	`displayName`、`city` などの他の組み込み属性。パラメーター名は、API コネクタによって送信されるパラメーターと同じです。
<extension_{extensions-app-id}_CustomAttribute>	いいえ	ユーザーに関するカスタム属性。パラメーター名は、API コネクタによって送信されるパラメーターと同じです。

フェデレーション Microsoft Entra ユーザーまたは Microsoft アカウントユーザーの場合

ユーザーがフェデレーション Microsoft Entra アカウントまたは Microsoft アカウントを使用してサインインする場合は、招待 API を使用してユーザーを作成し、必要に応じてユーザー更新 API を使用してユーザーに追加の属性を割り当てる必要があります。

承認システムはユーザーフローから HTTP 要求を受信します。

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

承認システムは、API コネクタによって提供される email を使用して招待を作成します。

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

応答の例:

HTTP/1.1 201 OK
Content-type: application/json

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}

承認システムは、招待されたユーザーの ID を使用して、収集されたユーザー属性でユーザーのアカウントを更新します (省略可能)。

PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

承認システム用のアプリケーションを登録する

API コネクタを作成する

ユーザーフローで API コネクタを有効にする

"承認状態の確認" API コネクタの要求と応答

"承認状態の確認" の継続応答

"承認状態の確認" のブロック応答

"要求の承認" API コネクタの要求と応答

"要求の承認" の継続応答

"要求の承認" のブロック応答

手動承認後のユーザーアカウントの作成

Google または Facebook のフェデレーションユーザーおよび電子メールワンタイムパスコードの場合

フェデレーション Microsoft Entra ユーザーまたは Microsoft アカウントユーザーの場合

次のステップ

その他のリソース

カスタム承認ワークフローをセルフサービス サインアップに追加する

承認システム用のアプリケーションを登録する

API コネクタを作成する

ユーザー フローで API コネクタを有効にする

API 応答を使用してサインアップ フローを制御する

"承認状態の確認" API コネクタの要求と応答

"承認状態の確認" の継続応答

"承認状態の確認" のブロック応答

"要求の承認" API コネクタの要求と応答

"要求の承認" の継続応答

"要求の承認" のブロック応答

手動承認後のユーザー アカウントの作成

Google または Facebook のフェデレーション ユーザーおよび電子メール ワンタイム パスコードの場合

フェデレーション Microsoft Entra ユーザーまたは Microsoft アカウント ユーザーの場合

次のステップ

その他のリソース

カスタム承認ワークフローをセルフサービスサインアップに追加する

ユーザーフローで API コネクタを有効にする

API 応答を使用してサインアップフローを制御する

手動承認後のユーザーアカウントの作成

Google または Facebook のフェデレーションユーザーおよび電子メールワンタイムパスコードの場合

フェデレーション Microsoft Entra ユーザーまたは Microsoft アカウントユーザーの場合