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

適用対象: 外部テナント (詳細)

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

この API リファレンス記事では、フローを実行するために生の HTTP 要求を手動で行うときにのみ必要な詳細について説明します。 ただし、この方法は推奨しません。 そのため、可能なときは、Microsoft が構築し、サポートしている認証 SDK を使用します。 ネイティブ認証 SDK の詳細を確認します。 API エンドポイントの呼び出しが成功すると、ユーザーを識別するための ID トークン と、保護された API を呼び出すための アクセス トークン の両方を受け取ります。 API からの応答はすべて JSON 形式です。

Microsoft Entraのネイティブ認証 API では、次の 2 つの認証フローのサインアップとサインインがサポートされています。

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

  • メールアドレスとパスワードでサインインしたユーザーは、 ユーザー名とパスワードでサインインすることも可能です。

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

前提条件

1. Microsoft Entra外部テナント。 外部テナントをまだ作成していない場合は、ここで作成してください。

2. まだ行っていない場合は、Microsoft Entra管理センターでアプリケーションを登録します。 次のことを確認します。

   • 後で使用するために、 アプリケーション (クライアント) ID と ディレクトリ (テナント) ID を 記録します。
   • アプリケーションに管理者の同意を付与します。
   • パブリック クライアントとネイティブ認証フローを有効にします。

3. まだ行っていない場合は、Microsoft Entra管理センターでユーザー フローを作成します。 ユーザー フローを作成するときは、必要に応じて構成したユーザー属性を書き留めます。これらの属性は、アプリの送信Microsoft Entra想定される属性です。

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

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

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

7. メールアドレスとパスワードでサインインしたユーザーもユーザー名とパスワードでサインインできるようにしたい場合は、「 別名またはユーザー名でサインイン 」記事の手順をご利用ください。

   1. サインインでユーザー名を有効にします。
   2. 管理センターでユーザー名を持つユーザーを作成するか、ユーザー名 を 追加して既存のユーザーを更新します。 または、Microsoft Graph API を使用して、ユーザーの作成と更新を自動的に行うこともできます。

8. 顧客に多要素認証 (MFA) を適用するには、「 アプリに多要素認証 (MFA) を追加して サインイン フローに MFA を追加する」の手順を使用します。 ネイティブ認証では、MFA の 2 番目の要素として電子メール ワンタイム パスコードと SMS がサポートされます。

継続トークン

サインイン、サインアップ、または 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 エンドポイントに送信できます。 アプリが必要なすべての情報を /signup/v1.0/start エンドポイントに送信する場合、アプリは呼び出しを行い、オプションの手順で応答を処理する必要はありません。

手順 21 では、ユーザーは既にサインアップしています。 ただし、アプリがサインアップ後にユーザーを自動的にサインインさせる必要がある場合、アプリは oauth/v2.0/token エンドポイントを呼び出してセキュリティ トークンを要求します。

ステップ 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( 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 エンドポイント経由で送信された場合、アプリは属性を送信せずに継続トークンを取得します。 アプリでは、「セキュリティ トークンの要求」に示すように、継続トークンを使用して セキュリティ トークンを要求できます。 それ以外の場合、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": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "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サインアップし、継続トークンを発行します。 アプリは継続トークンを使用して、 oauth/v2.0/token エンドポイントからセキュリティ トークンを要求できます。

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_grant の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_grant エラーのsuberror プロパティの値を次に示します。

手順 5: サインアップ後に自動的にサインインする

ユーザーがサインアップ後に自動的にサインインする必要がある場合、アプリは oauth/v2.0/token エンドポイントに POST 要求を行い、前の手順で取得した継続トークンを提供してセキュリティ トークンを取得します。 トークン エンドポイントを呼び出す方法について説明します。

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

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 管理センターの Display Name は、API で displayName として参照されます。

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

サインインフローのAPI参照

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

セキュリティ トークンを要求するために、アプリは 3 つのエンドポイント ( oauth/v2.0/initiate、 oauth/v2.0/challenge、 oauth/v2.0/token、必要に応じて oauth/v2.0/introspect) と対話します。

サインイン用の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
&capabilities=registration_required mfa_required

成功応答

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

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_client の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_client エラーの suberror プロパティの値を次 に 示します。

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

フローを続行するために、アプリは前の手順で取得した継続トークンを使用してMicrosoft Entraを要求し、ユーザーが MFA チャレンジを認証または完了するためにサポートされているチャレンジの種類のいずれかを選択します。 アプリが /oauth2/v2.0/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" 
} 

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
} 

リダイレクト応答

次のシナリオでは、Web ベースの認証フローへのフォールバックが必要になる場合があります。

• クライアント アプリは、Microsoft Entraが必要とする認証方法や機能をサポートしていません。
• ユーザーは強力な認証方法として SMS を使用しようとしますが、不正な保護によって要求が高リスクと見なされた場合 (パスワード認証を使用したメールでのみ) 要求がブロックされます。

これらのシナリオでは、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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

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

アプリは、 oauth2/v2.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_grant の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_grant エラーのsuberror プロパティの値を次に示します。

リダイレクト応答

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

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

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 

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

ユーザーが登録した強力な認証方法を取得する

oauth2/v2.0/introspect エンドポイントを使用して、登録されている強力な認証方法のユーザーの一覧を要求します。

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

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

成功応答

例:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6   
        }
    ]
}

MFA メソッド オブジェクトには、次のプロパティがあります。

リダイレクト応答

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

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

{     
   "challenge_type": "redirect" 
} 

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

クライアント アプリがユーザーに登録されている強力な認証方法の一覧を正常に取得すると、ユーザーは MFA チャレンジを完了するために使用する方法を選択します。 その後、フローは次のように進みます。

1. クライアント アプリは /oauth2/v2.0/challenge を呼び出し、 /oauth2/v2.0/introspect から取得した継続トークンと、選択した MFA メソッドの id を含めます。

   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
   &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
   &continuation_token=uY29tL2F1dGhlbnRpY... 
   

2. Microsoft Entra、電子メールなどのチャレンジ コードをユーザーのチャレンジ チャネルに送信し、継続トークンと MFA チャレンジの詳細を使用してクライアント アプリに応答します。

   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
   } 
   

3. アプリは、 /oauth2/v2.0/token エンドポイントに POST 要求を行い、継続トークン、正しい許可の種類、対応する許可の種類の値を含め、セキュリティ トークンを取得できるようになりました。 セキュリティ トークンの要求で想定される応答を参照してください。

   POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded    
   client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
   &continuation_token=uY29tL2F1dGhlbnRpY...   
   &grant_type=mfa_oob  
   &oob={otp_code}
   &scope=openid offline_access
   

強力な認証方法の API リファレンスを登録する

ネイティブ認証では、強力な認証方法の登録がサポートされます。 アプリが /oauth2/v2.0/token エンドポイントを呼び出し、MFA が必要であるが、ユーザーに厳密なメソッドが登録されていない場合、応答 (registeration_required) は、トークンを発行する前にユーザーに登録するようアプリに指示します。

クライアント アプリは、強力な認証方法を登録するフローを完了した後、 /oauth2/v2.0/token エンドポイントを呼び出してセキュリティ トークンを要求します。

強力な認証方法の登録エンドポイント

強力な認証方法登録 API を使用するために、アプリは次の表に示すエンドポイントを使用します。

手順 1: 強力な認証方法の一覧を取得する

登録フローは、ユーザーが登録を許可されている強力な認証方法の一覧をアプリが要求したときに開始されます。

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

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  

成功応答

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

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}

強力な認証方法オブジェクトには、次のプロパティがあります。

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

手順 2: 強力な認証方法を選択する

この手順では、ユーザーが登録する強力な認証方法を送信します。 Microsoft Entra、電子メールワンタイム パスコードなどのチャレンジをユーザーに送信します。

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

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com 

成功応答

成功した応答の例を次に示します。

例 1:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
} 

例 2:

サインアップ フローが強力な認証方法の登録フローの前にあり、 /register/v1.0/challenge エンドポイントに送信された電子メールがサインアップ フローで検証されたものと一致する場合、ネイティブ認証 API はチャレンジをユーザーに送信せずにメソッドを登録します。 この場合、応答は次のスニペットのようになります。

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

エラー応答

ここでのエラーは、 /register/v1.0/introspect エンドポイントを呼び出すときに発生する可能性があるエラーと似ています。 ただし、電話番号を登録するときに、電話番号が高リスクと見なされる場合は、要求がブロックされる可能性があります。

要求がブロックされた場合に発生する可能性のあるエラーを次に示します。

エラー パラメーターの値が access_denied の場合、Microsoft Entraは応答にサブエラー プロパティを含めます。 invalid_grant エラーのサブエラー プロパティの値を次に示します。

手順 3: チャレンジを送信する

この手順では、 /register/v1.0/continue エンドポイントを呼び出して、強力な認証方法の登録を完了します。

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

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?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

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

エラー応答

例:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_grant の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_grant エラーのsuberror プロパティの値を次に示します。

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

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

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

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

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

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

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

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

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

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

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

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

パスワード リセット フローは、アプリがエンドポイントに /resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_client の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_client エラーの suberror プロパティの値を次 に 示します。

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

フローを続行するために、アプリは前の手順で取得した継続トークンを使用してMicrosoft Entraを要求し、ユーザーが認証に使用するためにサポートされているチャレンジの種類のいずれかを選択します。 アプリが /resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

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

その後、アプリは /resetpassword/v1.0/continue エンドポイントに POST 要求を行います。 要求には、前のステップで選択したユーザーの資格情報と、/resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_grant の場合、Microsoft Entraは応答に suberror プロパティを含めます。 invalid_grant エラーのsuberror プロパティの値を次に示します。

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

アプリはユーザーから新しいパスワードを収集し、 エンドポイントによって発行された/resetpassword/v1.0/continueを使用して、/resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

エラー パラメーターの値が invalid_grant の場合、Microsoft Entraは応答に suberror プロパティを含めます。 suberror プロパティで使用できる値を次に示します。

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

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

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

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

発生する可能性があるエラー ( error プロパティの値) を次に示します。

パスワードのリセット後に自動的にサインインする

パスワードのリセットが成功した後にユーザーがサインインする必要がある場合。 アプリは、 /oauth2/v2.0/token エンドポイントを呼び出す必要があります。 トークン エンドポイントを呼び出す方法について説明します。

関連コンテンツ

• カスタム クレーム プロバイダーを構成します。