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

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

適用対象: 白いチェックマーク記号がある緑の円。従業員テナント灰色の X 記号が付いた白い円。外部テナント (詳細情報)

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

重要

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 ユーザーが認証されなくなります。詳細情報を参照してください。

API コネクタを作成する

ヒント

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

Microsoft Entra 管理センターにユーザー管理者以上でサインインしてください。
[ID]>[External Identities]>[概要] を参照します。
[All API connectors](すべての API コネクタ) を選択し、 [New API connector](新しい API コネクタ) を選択します。
呼び出しの表示名を指定します。たとえば、「承認状態の確認」などです。
API 呼び出しの [エンドポイント URL] を指定します。
[認証の種類] を選択し、API を呼び出すための認証情報を構成します。 API コネクタのセキュリティ保護の方法を参照してください。
[保存] を選択します。

API に送信される要求

API コネクタによってユーザー属性 ("要求") が HTTP POST 要求として具体化され、JSON 本文のキーと値のペアとして送信されます。属性は 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"
}

[ID]>[外部 ID]>[概要]>[カスタムのユーザー属性] のエクスペリエンスで一覧表示されるユーザープロパティとカスタム属性だけが、要求で送信できます。

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

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

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

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

重要

API エンドポイントが呼び出されたときに要求に値がない場合、要求は API に送信されません。 API は、要求に要求が含まれていないケースを明示的に確認して処理するように設計する必要があります。

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

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

Microsoft Entra 管理センターにユーザー管理者以上でサインインしてください。
[ID]>[External Identities]>[概要] を参照します。
[ユーザーフロー] を選択し、API コネクタを追加するユーザーフローを選択します。
[API connectors](API コネクタ) を選択し、ユーザーフローの次の手順で呼び出す API エンドポイントを選択します。
- サインアップ時に 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 を使用してこれを意図的に発行して、ユーザーにブロックページを表示することにより、ユーザーフローの継続を停止することができます。ブロックページには、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 がユーザーに表示されます。これで、ユーザーはフォームを編集して再送信することができます。この種類の応答は、入力の検証に使用できます。

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

応答の例

継続応答の例

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
}

パラメーター	タイプ	必須	説明
version	String	はい	API のバージョン。
action	String	はい	値は `Continue` とする必要があります。
<builtInUserAttribute>	<attribute-type>	いいえ	値は、API コネクタの構成の [Claim to receive](受信する要求) とユーザーフローの [ユーザー属性] として選択した場合にディレクトリに格納できます。 [アプリケーション要求] として選択されている場合、値をトークンで返すことができます。
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	いいえ	`_<extensions-app-id>_` は "省略可能" であり、要求に含める必要はありません。戻り値を使用すると、ユーザーから収集された値を上書きすることができます。

ブロック応答の例

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

パラメーター	タイプ	必須	説明
version	String	はい	API のバージョン。
action	String	はい	値は `ShowBlockPage` とする必要があります
userMessage	String	はい	ユーザーに表示するメッセージ。

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

API からブロック応答が返された後のエンドユーザーエクスペリエンスの画像例。

検証エラー応答の例

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

パラメーター	タイプ	必須	説明
version	String	はい	API のバージョン。
action	String	はい	値は `ValidationError` とする必要があります。
status	Integer/String	はい	ValidationError 応答の値は、`400` または `"400"` である必要があります。
userMessage	String	はい	ユーザーに表示するメッセージ。

注意

HTTP 状態コードは、応答の本文で、"status" 値であることに加え、"400" である必要があります。

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

API から検証エラーが返された後のエンドユーザーエクスペリエンスの画像例。

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

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

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 と暗号スイートの要件に関するページを参照してください。

ログの使用

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

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

次のステップ

カスタム承認ワークフローをセルフサービスサインアップに追加する方法を確認する
クイックスタートのサンプルからご覧ください。

次の方法で共有

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

API コネクタを作成する

API に送信される要求

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

この手順で API に送信される要求の例

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

継続応答

ブロック応答

ユーザーを作成する前

この手順で API に送信される要求の例

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

継続応答

ブロック応答

検証エラー応答

応答の例

継続応答の例

ブロック応答の例

検証エラー応答の例

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

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

ベストプラクティス

ログの使用

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

API コネクタを作成する

API に送信される要求

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

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

この手順で API に送信される要求の例

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

継続応答

ブロック応答

ユーザーを作成する前

この手順で API に送信される要求の例

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

継続応答

ブロック応答

検証エラー応答

応答の例

継続応答の例

ブロック応答の例

検証エラー応答の例

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

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

ベスト プラクティス

ログの使用

次のステップ

フィードバック

その他のリソース

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

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

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

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

ベストプラクティス