ネイティブ認証 API のリファレンス

適用対象: 従業員テナント 外部テナント (詳細情報)

Microsoft Entra のネイティブ認証を使用すると、ブラウザーに認証を委任せずに、クライアント アプリケーションでアプリのユーザー インターフェイスをホストできるため、ネイティブに統合された認証エクスペリエンスが実現します。 開発者は、サインイン インターフェイスの外観を完全に制御できます。

この API リファレンス記事では、フローを実行するために生の HTTP 要求を手動で行うときにのみ必要な詳細について説明します。 ただし、この方法は推奨しません。 そのため、可能なときは、Microsoft が構築し、サポートしている認証 SDK を使ってください。 SDK の使用方法の詳細については、「チュートリアル: ネイティブ認証用に Android モバイル アプリを準備する」および 「チュートリアル: ネイティブ認証用に iOS モバイル アプリを準備する」を参照してください。

API エンドポイントの呼び出しが成功すると、ユーザーを識別するための ID トークンと、保護された API を呼び出すためのアクセス トークンの両方を受け取ります。 API からの応答はすべて JSON 形式です。

Microsoft Entra のネイティブ認証 API では、次の 2 つの認証方法でのサインアップとサインインをサポートしています。

• メールとパスワード。メールとパスワードによるサインアップとサインイン、およびセルフサービス パスワード リセット (SSPR) をサポートします。

• メールのワンタイム パスコード。メールのワンタイム パスコードを使用したサインアップとサインインをサポートします。

前提条件

1. 顧客テナント向け Microsoft Entra 外部 ID。 お持ちでない場合は、無料試用版にサインアップしてください。

2. まだ登録していない場合は、Microsoft Entra 管理センターでアプリケーションを登録します。 委任されたアクセス許可を付与し、パブリック クライアントとネイティブの認証フローを有効にしてください。

3. まだ作成していない場合は、Microsoft Entra 管理センターでユーザー フローを作成します。 ユーザー フローを作成するときに、必須として構成したユーザー属性を記録しておきます。アプリでは、これらの属性を Microsoft Entra に送信する必要があります。 [ID プロバイダー] で、[ワンタイム パスコードの電子メール送信] オプションを選択します。

4. アプリの登録をユーザー フローに関連付けます。

5. サインイン フローで、サインイン API のテストに使用する顧客ユーザーを登録します。 または、サインアップ フローを実行した後に、このテスト ユーザーを取得できます。

6. SSPR フローの場合は、顧客テナント内の顧客ユーザーに対してセルフサービス パスワード リセットを有効にします。 SSPR は、メールとパスワードの認証方法を使用する顧客ユーザーが利用できます。

継続トークン

フロー、サインイン、サインアップ、SSPR のいずれかでエンドポイントを呼び出すたびに、エンドポイントからの応答には "継続トークン" が含まれます。 継続トークンは、同じフロー内の異なるエンドポイントへの呼び出し間で状態を維持するために Microsoft Entra ID が使用する一意の識別子です。 このトークンは、同じフロー内の後続の要求に含める必要があります。

各継続トークンは特定の期間有効であり、同じフロー内の後続の要求にのみ使用できます。

サインアップ API リファレンス

いずれかの認証方法でユーザーのサインアップ フローを完了するために、アプリでは、/signup/v1.0/start、/signup/v1.0/challenge、/signup/v1.0/continue、/token の 4 つのエンドポイントと対話します。

サインアップ API エンドポイント

サインアップ チャレンジ型

この API を使用すると、Microsoft Entra の呼び出しを行うときに、クライアント アプリでサポートされている認証方法を公開できます。 これを行うために、アプリではアプリの要求に challenge_type パラメーターを使用します。 このパラメーターには、さまざまな認証方法を表す定義済みの値が保持されます。

チャレンジ型の詳細については、「ネイティブ認証のチャレンジ型」を参照してください。 この記事では、認証方法に必要なチャレンジ型の値について説明します。

サインアップ フロー プロトコルの詳細

シーケンス図は、サインアップ プロセスのフローを示しています。

この図は、アプリがユーザーのユーザー名 (メール)、パスワード (メールとパスワードの認証方法の場合)、属性を異なるタイミングで (場合によっては別の画面で) 収集することを示しています。 ただし、同じ画面でユーザー名 (メール)、パスワード、必要なすべての属性値、および省略可能な属性値を収集するようにアプリを設計し、/signup/v1.0/start エンドポイントを介してそれらのすべてを送信できます。 この場合、アプリでは、呼び出しを行って、オプションのステップの応答を処理する必要はありません。

ステップ 1: サインアップ フローの開始を要求する

サインアップ フローは、アプリケーションが /signup/v1.0/start エンドポイントに POST 要求を行ってサインアップ フローを開始することで始まります。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します):

例 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com 

例 2 (要求にユーザー属性とパスワードを含める):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com 

成功応答

アップロードの成功の例を次に示します:

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

{
    "continuation_token": "AQABAAEAAA…",
} 

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_grant エラーの suberror パラメーターに指定できる値を次に示します:

エラー パラメーターの値が invalid_client の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_client エラーのsuberror パラメーターに指定できる値を次に示します:

ステップ 2: 認証方法を選びます

アプリでは、ユーザーが認証に使用する、サポートされているチャレンジ型のいずれかを選択するよう Microsoft Entra に要求します。 これを行うために、アプリで /signup/v1.0/challenge エンドポイントを呼び出します。 アプリでは、/signup/v1.0/start エンドポイントから取得した継続トークンを要求に含める必要があります。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します)。

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

成功応答

Microsoft Entra は、ユーザーのメール アドレスにワンタイム パスコードを送信してから、チャレンジ型の値 oob と、ワンタイム パスコードに関する追加情報を使って応答します:

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

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
} 

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{
   "challenge_type": "redirect"
}

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

手順 3: ワンタイム パスコードを送信する

アプリは、ユーザーのメール アドレスに送信されたワンタイム パスコードを送信します。 ワンタイム パスコードを送信しているので、oob パラメータが必要であり、grant_type パラメータの値は oob である必要があります。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

アプリによるワンタイム パスコードの送信が成功した後のサインアップ フローは、次の表に示すようにシナリオによって異なります。

回答

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

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_grant エラーの suberror パラメーターに指定できる値を次に示します:

ユーザーからパスワード資格情報を収集するには、アプリが /signup/v1.0/challenge エンドポイントを呼び出して、ユーザーが指定する必要がある資格情報を決定する必要があります。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

成功応答

パスワードが Microsoft Entra 管理センターでユーザー用に構成された認証方法である場合、継続トークンを含む成功応答がアプリに返されます。

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
    "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

ステップ 4: サインアップするトークンを認証して取得する

アプリは、前のステップで Microsoft Entra が要求したユーザーの資格情報 (この場合はパスワード) を送信する必要があります。 /signup/v1.0/start エンドポイント経由でパスワード資格情報を送信しなかった場合、アプリはパスワード資格情報を送信する必要があります。 アプリは、 /signup/v1.0/continue エンドポイントにパスワードの送信を要求します。 パスワードを送信するため、password パラメーターが必要であり、grant_type パラメーターには値 password が必要です。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}

成功応答

要求が成功したが、Microsoft Entra 管理センターで属性が構成されていない場合、またはすべての必須属性が /signup/v1.0/start エンドポイント経由で送信された場合、アプリは属性を送信せずに継続トークンを取得します。 アプリでは、継続トークンを使用して、ステップ 5 に示すようにセキュリティ トークンを要求できます。 それ以外の場合、Microsoft Entra の応答は、アプリが必要な属性を送信する必要があることを示します。 これらの属性は、組み込みまたはカスタムで、テナント管理者によって Microsoft Entra 管理センターで構成されました。

必要なユーザー属性

この応答は、name、*age、phone 属性の値を送信するようにアプリに要求します。

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

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6",
    "suberror": "password_too_weak"
}

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 suberror パラメーターの使用可能な値を次に示します:

ユーザー属性の送信

フローを続行するには、アプリで /signup/v1.0/continue エンドポイントを呼び出して、必要なユーザー属性を送信する必要があります。 属性を送信するため、attributes パラメーターが必要であり、grant_type パラメーターには attributes と等しい値が必要です。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

成功応答

要求が成功した場合、Microsoft Entra は継続トークンを発行します。このトークンは、アプリがセキュリティ トークンの要求に使用できます。

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

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6" 
}

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_grant エラーの suberror パラメーターに指定できる値を次に示します:

ステップ 5: セキュリティ トークンの要求

アプリは /token エンドポイントに POST 要求を行い、前のステップで取得した継続トークンを提供してセキュリティ トークンを取得します。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token 

成功応答

アップロードの成功の例を次に示します:

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

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エンドポイントへのユーザー属性の送信

Microsoft Entra 管理センターでは、必須または省略可能としてユーザー属性を構成できます。 この構成により、エンドポイントを呼び出したときの Microsoft Entra の応答方法が決まります。 サインアップ フローが完了するために、省略可能な属性は必要ありません。 したがって、すべての属性が省略可能な場合は、ユーザー名が検証される前にそれらを送信する必要があります。 そうしないと、省略可能な属性なしでサインアップが完了します。

次の表は、Microsoft Entra エンドポイントにユーザー属性を送信できるタイミングをまとめたものです。

ユーザー属性値の形式

Microsoft Entra 管理センターでユーザー フロー設定を構成して、ユーザーから収集する情報を指定します。 「サインアップ時にカスタム ユーザー属性」に関する記事を使用して、ビルトインとカスタム属性の両方の値を収集する方法を確認してください。

構成する属性のユーザーによる入力の種類も指定することができます。 次の表は、サポートされているユーザー入力の種類と、UI コントロールによって収集された値を Microsoft Entra に送信する方法をまとめたものです。

属性の値を送信する方法を示す要求の例を次に示します:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

ユーザー属性の入力型の詳細については、「カスタム ユーザー属性の入力の種類」の記事を参照してください。

ユーザー属性の参照方法

サインアップ ユーザー フローを作成する場合は、サインアップ時にユーザーから収集するユーザー属性を構成します。 Microsoft Entra 管理センターのユーザー属性の名前は、ネイティブ認証 API で参照する方法とは異なります。

たとえば、Microsoft Entra 管理センターの表示名は、API の displayName として参照されます。

ネイティブ認証 API で組み込みユーザー属性とカスタム ユーザー属性の両方を参照する方法については、ユーザー プロファイル属性に関する記事を参照してください。

サインイン API リファレンス

ユーザーは、サインアップで使用する認証方法を使ってサインインする必要があります。 たとえば、メールとパスワードの認証方法を使用してサインアップするユーザーは、メールとパスワードでサインインする必要があります。

セキュリティ トークンを要求するために、アプリは 3 つのエンドポイント /initiate、/challenge、/token と対話します。

サインイン API エンドポイント

サインイン チャレンジ型

この API を使用すると、Microsoft Entra の呼び出しを行うときに、アプリでサポートされている認証方法をアドバタイズできます。 これを行うために、アプリはその要求に challenge_type パラメーターを使用します。 このパラメーターには、さまざまな認証方法を表す定義済みの値が保持されます。

特定の認証方法において、サインアップ フロー中にアプリから Microsoft Entra に送信されるチャレンジ型の値は、そのアプリのサインイン時と同じです。 たとえば、メールとパスワードの認証方法では、サインアップとサインインの両方のフローで oob、password、redirect というチャレンジ型の値を使用します。

チャレンジ型の詳細については、「ネイティブ認証のチャレンジ型」の記事を参照してください。

サインイン フロー プロトコルの詳細

シーケンス図は、サインイン プロセスのフローを示しています。

次のセクションでは、シーケンス図のフローを 3 つの基本的なステップにまとめます。

ステップ 1: サインイン フローの開始を要求する

認証フローは、アプリケーションが/initiate エンドポイントに POST 要求を行ってサインイン フローを開始することで始まります。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com 

成功応答

アップロードの成功の例を次に示します:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_client の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_client エラーのsuberror パラメーターに指定できる値を次に示します:

ステップ 2: 認証方法を選びます

フローを続行するために、アプリでは前のステップで取得した継続トークンを使用して、ユーザーが認証に使用する、サポートされているチャレンジ型のいずれかを選択するよう Microsoft Entra に要求します。 アプリが /challenge エンドポイントに POST 要求を行います。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY... 

成功応答

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

ステップ 3: セキュリティ トークンの要求

アプリは /token エンドポイントに POST 要求を行い、前のステップで選択したユーザーの資格情報 (この場合はパスワード) を提供してセキュリティ トークンを取得します。

要求の例を次に示します (読みやすくするために複数行で要求の例を示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 

成功応答

アップロードの成功の例を次に示します:

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

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}

エラー応答

例:

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

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_grant エラーの suberror パラメーターに指定できる値を次に示します:

セルフサービス パスワード リセット (SSPR)

アプリで認証方法としてメールとパスワードを使用する場合は、セルフサービス パスワード リセット (SSPR) API を使用して、顧客ユーザーが自分のパスワードをリセットできるようにします。 この API は、パスワードを忘れた場合やパスワードを変更するシナリオに使用します。

セルフサービス パスワード リセット API エンドポイント

この API を使用するために、アプリは次の表に示すエンドポイントと対話します:

セルフサービス パスワード リセット チャレンジ型

この API を使用すると、Microsoft Entra の呼び出しを行うときに、アプリでサポートされている認証方法をアドバタイズできます。 これを行うために、アプリはその要求に challenge_type パラメーターを使用します。 このパラメーターには、さまざまな認証方法を表す定義済みの値が保持されます。

SSPR フローの場合、チャレンジ型の値は oob および redirect です。

チャレンジ型の詳細については、「ネイティブ認証のチャレンジ型」を参照してください。

セルフサービス パスワード リセット フロー プロトコルの詳細

シーケンス図は、パスワード リセット プロセスのフローを示しています。

この図は、アプリがユーザーのユーザー名 (メール) とパスワードを異なるタイミングで (場合によっては別の画面で) 収集することを示しています。 ただし、同じ画面でユーザー名 (メール) と新しいパスワードを収集するようにアプリを設計できます。 この場合、アプリはパスワードを保持し、必要に応じて /submit エンドポイントを介して送信します。

ステップ 1: セルフサービス パスワード リセット フローの開始を要求する

パスワード リセット フローは、アプリがエンドポイントに /start POST 要求を行ってセルフサービス パスワード リセット フローを開始することから始まります。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com 

成功応答

例:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_client の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_client エラーのsuberror パラメーターに指定できる値を次に示します:

ステップ 2: 認証方法を選びます

フローを続行するために、アプリは前のステップで取得した継続トークンを使用して、ユーザーが認証するためにサポートされているチャレンジ型のいずれかを選択するよう Microsoft Entra に要求します。 アプリが /challenge エンドポイントに POST 要求を行います。 この要求が成功した場合、Microsoft Entra はユーザーのアカウントのメール アドレスにワンタイム パスコードを送信します。 現時点では、メール OTP のみがサポートされています。

次に例を示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 

成功応答

例:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
} 

アプリが Microsoft Entra で必要な認証方法をサポートできない場合は、Web ベースの認証フローへのフォールバックが必要です。 このシナリオでは、Microsoft Entra は redirect チャレンジ型を応答で返してアプリに通知します:

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

{     
   "challenge_type": "redirect" 
} 

この応答は成功と見なされますが、アプリは Web ベースの認証フローに切り替える必要があります。 この場合は、Microsoft が構築し、サポートされている認証ライブラリを使用することをおすすめします。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

手順 3: ワンタイム パスコードを送信する

その後、アプリは /continue エンドポイントに POST 要求を行います。 要求には、前のステップで選択したユーザーの資格情報と、/challenge エンドポイントから発行された継続トークンをアプリに含める必要があります。

要求の例を次に示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

成功応答

例:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 invalid_grant エラーの suberror パラメーターに指定できる値を次に示します:

ステップ 4: 新しいパスワードを送信する

アプリはユーザーから新しいパスワードを収集し、/continue エンドポイントによって発行された継続トークンを使用して、/submit エンドポイントに POST 要求を行ってパスワードを送信します。

次に例を示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}

成功応答

例:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

エラー パラメーターの値が invalid_grant の場合、Microsoft Entra はその応答に suberror パラメーターを含めます。 suberror パラメーターの使用可能な値を次に示します:

ステップ 5: パスワード リセットの状態をポーリングする

最後に、ユーザーの構成を新しいパスワードで更新すると多少の遅延が発生するため、アプリは /poll_completion エンドポイントを使用して Microsoft Entra をポーリングしてパスワード リセットの状態を確認できます。 ポーリング要求の間にアプリが待機する必要がある最小時間 (秒単位) は、poll_interval パラメーターの /submit エンドポイントから返されます。

次に例を示します (読みやすくするために、要求の例を複数行で示します):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0... 

成功応答

例:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Microsoft Entra から返される可能性のある状態 (status パラメーターの可能な値) を次に示します:

エラー応答

例:

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

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
} 

発生する可能性があるエラー (可能性のある error パラメーターの値) を次に示します:

次のステップ

• ネイティブ認証メール OTP API リファレンス。