API コネクタをユーザー フローに追加する

適用対象: ワークフォース テナント 外部テナント (詳細)

API コネクタを使用するには、まず API コネクタを作成してから、ユーザー フローで有効にします。

API コネクタを作成する

1. Microsoft Entra 管理センターに、少なくともユーザー管理者としてサインインします。

2. Entra ID>外部 ID>概要に移動します。

3. [すべての API コネクタ] を選択し、[新しい API コネクタ] を選択します。

   

4. 呼び出しの表示名を指定します。 たとえば、 承認の状態を確認します。

5. API 呼び出しの エンドポイント URL を 指定します。

6. 認証の 種類 を選択し、API を呼び出すための認証情報を構成します。 API コネクタをセキュリティで保護する方法について説明します。

   

7. [保存] を選択します。

API に送信される要求

API コネクタは HTTP POST 要求として具体化され、JSON 本文でキーと値のペアとしてユーザー属性 ('claims') を送信します。 属性は、 Microsoft Graph のユーザー プロパティと同様にシリアル化されます。

要求の例

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"
}

要求で送信できるのは、Entra ID>External Identities>Overview>Custom ユーザー属性インターフェースにリストされているユーザー プロパティとカスタム属性だけです。

カスタム属性は、ディレクトリ内の extension_<extensions-app-id>_AttributeName 形式に存在します。 API では、これと同じシリアル化された形式で要求を受け取ることを想定しています。 カスタム属性の詳細については、 セルフサービス サインアップ フローのカスタム属性の定義に関するページを参照してください。

さらに、通常、要求はすべての要求で送信されます。

• UI ロケール ('ui_locales') - デバイスで構成されているエンドユーザーのロケール。API は、国際化された応答を返すために使用できます。

• 電子メール アドレス ('email') または ID ('id') - これらの要求は、アプリケーションに対して認証されているエンド ユーザーを識別するために API によって使用できます。

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

セルフサービス サインアップ ユーザー フローに API コネクタを追加するには、次の手順を実行します。

1. Microsoft Entra 管理センターに、少なくともユーザー管理者としてサインインします。

2. Entra ID>外部 ID>概要に移動します。

3. [ ユーザー フロー] を選択し、API コネクタを追加するユーザー フローを選択します。

4. API コネクタを選択し、ユーザー フローの次の手順で呼び出す API エンドポイントを選択します。

   • サインアップ中に ID プロバイダーとフェデレーションした後
   • ユーザーを作成する前に

   

5. [保存] を選択します。

サインアップ時に ID プロバイダーとのフェデレーションを行った後

サインアップ プロセスのこの手順での API コネクタは、ID プロバイダー (Google、Facebook、または Microsoft Entra ID など) でユーザーが認証された直後に呼び出されます。 この手順は、 ユーザー属性を収集するためにユーザーに表示されるフォームである属性コレクション ページの前にあります。

この手順で 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" は常に送信されます。

この手順での Web API からの予期される応答の種類

ユーザー フロー中に Web API で Microsoft Entra ID から HTTP 要求を受信すると、これらの応答が返されることがあります。

• 継続応答
• ブロック応答

継続応答

継続応答は、ユーザー フローが次の手順 (属性収集ページ) に進む必要があることを示します。

継続応答では、API は次の要求を返すことができます。

• 属性収集ページの入力フィールドに事前入力する。

継続応答の例を参照してください。

ブロック応答

ブロック応答によって、ユーザー フローは終了します。 API は意図的にブロック応答を発行し、ブロック ページをユーザーに表示することで、ユーザー フローの継続を停止できます。 ブロック ページには、API によって提供された userMessage が表示されます。

ブロック応答の例を参照してください。

ユーザーを作成する前

サインアップ プロセスのこのステップでの API コネクタは、属性コレクション ページが含まれている場合、その後に呼び出されます。 このステップは、Microsoft Entra ID でユーザー アカウントが作成される前に必ず呼び出されます。

この手順で 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",
 "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 プロバイダーによって提供される情報によって異なります。

この手順での Web API からの予期される応答の種類

ユーザー フロー中に Web API で Microsoft Entra ID から HTTP 要求を受信すると、これらの応答が返されることがあります。

• 継続応答
• ブロック応答
• 検証応答

継続応答

継続応答は、ユーザー フローが次の手順 (ディレクトリでのユーザーの作成) に進む必要があることを示します。

継続応答では、API は次の要求を返すことができます。

• 属性コレクション ページから要求に既に割り当てられている値をオーバーライドします。

継続応答の例を参照してください。

ブロック応答

ブロック応答によって、ユーザー フローは終了します。 API は意図的にブロック応答を発行し、ブロック ページをユーザーに表示することで、ユーザー フローの継続を停止できます。 ブロック ページには、API によって提供された userMessage が表示されます。

ブロック応答の例を参照してください。

検証エラー応答

API が検証エラー応答で応答すると、ユーザー フローは属性収集ページにとどまり、userMessage がユーザーに表示されます。 これで、ユーザーはフォームを編集して再送信することができます。 この種類の応答は、入力の検証に使用できます。

検証エラー応答の例を参照してください。

応答の例

継続応答の例

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

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

ブロック応答の例

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

ブロック応答を使用したエンド ユーザー エクスペリエンス

検証エラー応答の例

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

検証エラー応答を使用したエンド ユーザー エクスペリエンス

ベスト プラクティスとトラブルシューティングの方法

サーバーレス クラウド機能の使用

Azure Functions の HTTP トリガーなどのサーバーレス関数は、API コネクタで使用する API エンドポイントを作成する方法を提供します。 たとえば 、サーバーレス クラウド関数を使用して検証ロジックを実行し、サインアップを特定の電子メール ドメインに制限することができます。 複雑なシナリオには、サーバーレス クラウド機能を使用して、他の Web API、データ ストア、および他のクラウド サービスを呼び出して起動することもできます。

ベスト プラクティス

次のことを確認します。

• API は、前に説明したように API 要求と応答のコントラクトに従います。
• API コネクタの エンドポイント URL は、正しい API エンドポイントを指します。
• API によって、それが依存する受信済み要求の null 値が明示的に確認されます。
• API には、セキュリティで 保護された API コネクタに記載されている認証方法が実装されています。
• API が可能な限り迅速に応答することで、スムーズなユーザー エクスペリエンスが保証されます。
  • Microsoft Entra ID 側は、応答を受信するために最大 "20 秒間" 待機します。 何も受信しない場合は、API の呼び出しが "もう一度実行 (再試行)" されます。
  • サーバーレス機能またはスケーラブルな Web サービスを使用している場合は、API を運用環境で "起動状態" または "ウォーム状態" に保つホスティング プランを使用します。 Azure Functions の場合は、少なくとも Premium プランを使用することをお勧めします。
• API の高可用性を保証します。
• ダウンストリームの API、データベース、または API のその他の依存関係のパフォーマンスを監視し、最適化します。
• エンドポイントは、Microsoft Entra TLS と暗号のセキュリティ要件に準拠している必要があります。 詳細については、「 TLS と暗号スイートの要件」を参照してください。

ログの使用

一般に、 Application Insights などの Web API サービスによって有効になっているログ ツールを使用して、API で予期しないエラー コード、例外、パフォーマンス低下を監視すると便利です。

• HTTP 200 または 400 以外の HTTP 状態コードを監視します。
• 401 または 403 HTTP 状態コードは、通常、認証に問題があることを示しています。 API コネクタで API の認証レイヤーとそれに対応する構成を再確認します。
• 開発では、必要に応じて、より積極的なログ レベル ("トレース" や "デバッグ" など) を使用します。
• 長い応答時間について API を監視します。

次のステップ

• セルフサービス サインアップにカスタム承認ワークフローを追加する方法について説明します
• クイック スタート サンプルを開始します。