Azure Active Directory B2C での OAuth 2.0 承認コードフロー

[アーティクル]
11/06/2023

OAuth 2.0 認証コード付与を利用して、デバイスにインストールされているアプリに、Web API など、保護されているリソースにアクセスする権利を与えることができます。 Azure Active Directory B2C (Azure AD B2C) で導入された OAuth 2.0 を利用することで、サインアップ、サインイン、その他の ID 管理タスクをシングルページ、モバイル、デスクトップのアプリに追加できます。この記事は言語に依存しません。この記事では、オープンソースライブラリを利用しないで、HTTP メッセージを送受信する方法について説明します。可能な場合は、サポートされている Microsoft 認証ライブラリ (MSAL) を使用することをお勧めします。MSAL を使用するサンプルアプリをご覧ください。

OAuth 2.0 承認コードフローは、 OAuth 2.0 仕様のセクション 4.1で規定されています。 Web アプリケーション、シングルページアプリケーション、ネイティブにインストールされるアプリケーションを含め、多くのアプリケーションの種類で認証と承認を行う際にこのフローを利用できます。 OAuth 2.0 承認コードフローを利用して、承認サーバーで保護されているリソースにアクセスするために使用できる、アプリケーション用のアクセストークンと更新トークンを安全に取得できます。クライアントは、更新トークンを使用して、アクセストークンの期限が切れた後 (通常は 1 時間後)、新しいアクセス (および更新) トークンを取得できます。

この記事では、パブリッククライアントの OAuth 2.0 承認コードフローに重点を置いて説明します。パブリッククライアントとは、秘密のパスワードの整合性を守る目的で信頼できないクライアントアプリケーションのことです。これには、シングルページアプリケーション、モバイルアプリ、デスクトップアプリケーションなど、サーバー上で実行されない事実上すべてのアプリが該当します。

注意

Azure AD B2C を利用して Web アプリに ID 管理を追加するには、OAuth 2.0 ではなく、OpenID Connect を使用してください。

Azure AD B2C は、単純な認証と承認以上のことができるように標準の OAuth 2.0 プロトコルを拡張したものです。これには、ユーザーフローが導入されています。ユーザーフローと共に OAuth 2.0 を使用して、サインアップ、サインイン、プロファイル管理などのユーザーエクスペリエンスをアプリケーションに追加できます。 OAuth 2.0 プロトコルを使用する ID プロバイダーとしては、Amazon、Microsoft Entra ID、Facebook、GitHub、Google、LinkedIn などがあります。

この記事の HTTP 要求を試すには:

{tenant}を Azure AD B2C テナントの名前に置き換えます。
90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 を、Azure AD B2C テナントに登録済みのアプリケーションのアプリ ID に置き換えます。
{policy} を、テナント内に作成したポリシーの名前に置き換えます (例: b2c_1_sign_in)。

シングルページアプリに必要なリダイレクト URI セットアップ

シングルページアプリケーションの承認コードフローでは、追加のセットアップが必要です。シングルページアプリケーションの作成手順に従って、CORS に対して有効としてリダイレクト URI を正しくマークします。既存のリダイレクト URI を更新して CORS を有効にするために、[アプリの登録の認証] タブの [Web] セクションにある移行プロンプトをクリックできます。あるいは、[アプリの登録のマニフェストエディター] を開き、replyUrlsWithType セクションでリダイレクト URI の type フィールドを spa に設定します。

spa のリダイレクトの種類は、暗黙的なフローと下位互換性があります。トークンを取得するために暗黙的なフローを現在使用しているアプリは、問題なく spa のリダイレクト URI の種類に移行し、暗黙的なフローを引き続き使用することができます。

1.承認コードを取得する

承認コードフローは、クライアントがユーザーを /authorize エンドポイントにリダイレクトさせることから始まります。これはフローの対話部分であり、ユーザーが操作します。この要求で、クライアントは、scope パラメーターで、ユーザーから取得する必要のあるアクセス許可を指定します。次の例 (読みやすさのために改行を使用) は、承認コードを取得する方法を示しています。 GET HTTP 要求をテストしている場合は、ブラウザーを使用します。

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

パラメーター	必須	説明
{tenant}	必須	Azure AD B2C テナントの名前。
{policy}	必須	実行するユーザーフロー。 Azure AD B2C テナントに作成したユーザーフローの名前を指定します。例: `b2c_1_sign_in`、`b2c_1_sign_up`、または`b2c_1_edit_profile`。
client_id	必須	Azure Portal でアプリに割り当てられたアプリケーション ID。
response_type	必須	応答の種類。承認コードフローでは `code` を指定する必要があります。 ID トークンが応答の種類 (`code+id_token`など) に含まれる場合、そのトークンを受け取ることができます。この場合は、スコープに `openid` を含める必要があります。
redirect_uri	必須	アプリのリダイレクト URI。アプリは、この URI で認証応答を送受信します。ポータルで登録したいずれかのリダイレクト URI と完全に一致させる必要があります (ただし、URL エンコードが必要)。
scope	必須	スコープのスペース区切りリスト。 `openid` スコープは、ユーザーをサインインさせ、ID トークンの形式でユーザーに関するデータを取得するためのアクセス許可を示します。 Web アプリケーションの場合、`offline_access` スコープは任意です。これは、アプリケーションがリソースへの拡張アクセスに "更新トークン" を必要とすることを示しています。クライアント ID は、発行されたトークンが Azure AD B2C 登録済みクライアントによる使用を目的としていることを示しています。 `https://{tenant-name}/{app-id-uri}/{scope}` は、保護されたリソース (Web API など) に対するアクセス許可を示します。詳細については、アクセストークンを要求するを参照してください。
response_mode	推奨	結果として得られた承認コードをアプリに返すときに使用するメソッド。 `query`、`form_post`、または `fragment` を指定できます。
state	推奨	要求に含まれる値。使用したい任意の内容の文字列を指定できます。通常、クロスサイトリクエストフォージェリ攻撃を防ぐために、ランダムに生成された一意の値が使用されます。この状態は、認証要求の前にアプリ内のユーザーの状態に関する情報をエンコードする目的にも使用されます。たとえば、ユーザーが表示していたページや実行されていたユーザーフローがその対象です。
prompt	省略可能	ユーザーとの必要な対話の種類。現在、有効な値は `login` のみです。この場合ユーザーは要求時に、その資格情報を入力する必要があります。シングルサインオンは作用しません。
code_challenge	推奨/必須	PKCE (Proof Key for Code Exchange) を使用して承認コード付与をセキュリティ保護するために使用されます。 `code_challenge_method` が含まれている場合は必須です。 `code_verifier`と`code_challenge` を生成するには、アプリケーションにロジックを追加する必要があります。 `code_challenge`は、の Base64 URL でエンコードされた SHA256 ハッシュです `code_verifier`。 `code_verifier`を後で使用するためにアプリケーションに保存し、承認要求 `code_challenge` と共に送信します。詳細については、「PKCE RFC」を参照してください。これは、すべての種類のアプリケーション (ネイティブアプリ、SPA、Web アプリなどの機密クライアント) で推奨されるようになりました。
`code_challenge_method`	推奨/必須	`code_challenge` パラメーターの `code_verifier` をエンコードするために使用されるメソッド。これは `S256` であるべきですが、何らかの理由によってクライアントで SHA256 がサポートされない場合、仕様では `plain` の使用が許可されています。 `code_challenge_method`を除外したが、`code_challenge`を含める場合、`code_challenge` はプレーンテキストと見なされます。 Microsoft ID プラットフォームは `plain` と `S256` の両方をサポートします。詳細については、「PKCE RFC」を参照してください。これは、承認コードフローを使用するシングルページアプリには必須です。
login_hint	いいえ	サインインページのサインイン名フィールドに事前に入力するために使用できます。詳細については、「サインイン名を事前入力する」を参照してください。
domain_hint	いいえ	サインインに使用する必要があるソーシャル ID プロバイダーに関するヒントを Azure AD B2C に提供します。有効な値が含まれている場合、ユーザーは直接 ID プロバイダーのサインインページに移動します。詳細については、「サインインをソーシャルプロバイダーにリダイレクトする」を参照してください。
カスタムパラメーター	いいえ	カスタムポリシーで使用できるカスタムパラメーター。例: 動的なカスタムページコンテンツ URI、またはキー値要求リゾルバー。

この時点で、ユーザーはユーザーフローのワークフローを完了するよう求められます。ユーザー名とパスワードを入力したり、ソーシャル ID でサインインしたり、ディレクトリにサインアップしたりするなど、いくつかの手順が必要なことがあります。ユーザーアクションは、ユーザーフローがどのように定義されているかによって異なります。

ユーザーがユーザーフローを完了すると、Microsoft Entra ID からユーザーが redirect_uri に使用した値でアプリに応答が返されます。これには、response_mode パラメーターで指定されたメソッドが使用されます。応答は、実行されたユーザーフローとは無関係に、ユーザーアクションの各シナリオでまったく同じになります。

response_mode=query を使用した場合の正常な応答は次のようになります。

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

パラメーター	説明
code	アプリが要求した承認コード。アプリは、承認コードを使用してターゲットリソースのアクセストークンを要求できます。承認コードの有効期間は非常に短時間です。通常、約 10 分で期限が切れます。
state	詳細については前のセクションの表を参照してください。要求に `state` パラメーターが含まれている場合、同じ値が応答にも含まれることになります。アプリは、要求と応答の `state` 値が同一であることを検証する必要があります。

アプリ側でエラーを適切に処理できるように、エラー応答をリダイレクト URI に送信することもできます。

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

パラメーター	説明
error	発生したエラーの種類を分類する際に使用できるエラーコード文字列。この文字列はエラーへの対応に利用することもできます。
error_description	認証エラーの根本的な原因を特定しやすいように記述した具体的なエラーメッセージ。
state	前の表の詳しい説明を参照してください。要求に `state` パラメーターが含まれている場合、同じ値が応答にも含まれることになります。アプリは、要求と応答の `state` 値が同一であることを検証する必要があります。

2.アクセストークンを取得する

承認コードを取得したところで、POST 要求を /token エンドポイントに送信して、トークンの code を目的のリソースに適用できます。 Azure AD B2C では、対応するスコープを要求の中で指定することによって、普通に他の API のアクセストークンを要求できます。

さらに、要求スコープとしてアプリのクライアント ID を使用するという慣例によって、アプリ独自のバックエンド Web API 用アクセストークンを要求することもできます (その場合、そのクライアント ID を "audience" として持つアクセストークンが得られます)。

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

パラメーター	必須	説明
{tenant}	必須	Azure AD B2C テナントの名前。
{policy}	必須	認証コードの取得に使用されたユーザーフロー。この要求に別のユーザーフローを使用することはできません。
client_id	必須	Azure Portal でアプリに割り当てられたアプリケーション ID。
client_secret	はい (Web アプリの場合)	Azure portal で生成されたアプリケーションシークレット。クライアントが安全にクライアントシークレットを格納できる Web アプリのシナリオでは、このフローでクライアントシークレットが使用されます。ネイティブアプリ (パブリッククライアント) のシナリオでは、クライアントシークレットは安全に保存できないため、この呼び出しでは使用されません。クライアントシークレットを使用する場合は、定期的に変更してください。
grant_type	必須	付与の種類。承認コードフローでは、付与の種類には `authorization_code` を指定する必要があります。
scope	推奨	スコープのスペース区切りリスト。 1 つのスコープ値が、要求されている両方のアクセス許可を Microsoft Entra ID に示します。クライアント ID をスコープとして使用することは、同じクライアント ID で表される、独自のサービスまたは Web API に対して使用できるアクセストークンをアプリが必要とすることを示します。 `offline_access` スコープは、アプリがリソースに長時間アクセスするには更新トークンが必要になることを示します。 Azure AD B2C に ID トークンを要求するために、`openid` スコープを使用することもできます。
code	必須	`/authorize` エンドポイントから取得した承認コード。
redirect_uri	必須	承認コードを受け取った、アプリケーションのリダイレクト URI。
code_verifier	推奨	承認コードを取得するために`code_verifier`使用されるものと同じ。承認コード付与要求で PKCE が使用された場合は必須です。詳細については、「PKCE RFC」を参照してください。

この POST HTTP 要求をテストしている場合は、Microsoft PowerShell や Postman などの任意の HTTP クライアントを使用できます。

正常なトークン応答は次のようになります。

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

パラメーター	説明
not_before	トークンが有効と見なされる時間 (エポック時間)。
token_type	トークンタイプ値。 Microsoft Entra ID でサポートされる種類はベアラーのみです。
access_token	要求した署名付き JSON Web トークン (JWT)。
scope	トークンが有効である範囲。スコープは、後で使用できるようトークンをキャッシュするためにも使用できます。
expires_in	トークンが有効な時間の長さ (秒単位)。
refresh_token	OAuth 2.0 更新トークン。現在のトークンの有効期限が切れた後、アプリはこのトークンを使用して、追加のトークンを取得します。更新トークンの有効期間は長期です。リソースへのアクセスを長期間保持するときに利用できます。詳細については、「Azure AD B2C: トークンリファレンス」を参照してください。

エラー応答は次のようになります。

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

パラメーター	説明
error	発生したエラーの種類を分類する際に使用できるエラーコード文字列。この文字列はエラーへの対応に利用することもできます。
error_description	認証エラーの根本的な原因を特定しやすいように記述した具体的なエラーメッセージ。

3.トークンを使用する

これでアクセストークンを正常に取得できたので、そのトークンを Authorization ヘッダー内に含めることによって、それをバックエンド Web API への要求で使用できます。

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4.トークンを更新する

アクセストークンと ID トークンの有効期限は非常に短いです。有効期限が切れた後に、リソースに引き続きアクセスできるようにするには、トークンを更新する必要があります。アクセストークンを更新すると、Azure AD B2C から新しいトークンが返されます。更新されたアクセストークンは、nbf (期間の開始時刻)、iat (発行時刻)、および exp (有効期限) の要求値が更新されます。他のすべての要求値は、最初に発行されたアクセストークンと同じになります。

トークンを更新するには、別の POST 要求を /token エンドポイントに送信します。このとき、code の代わりに refresh_token を指定します。

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

パラメーター	必須	説明
{tenant}	必須	Azure AD B2C テナントの名前。
{policy}	必須	元の更新トークンの取得に使用されたユーザーフロー。この要求に別のユーザーフローを使用することはできません。
client_id	必須	Azure Portal でアプリに割り当てられたアプリケーション ID。
client_secret	はい (Web アプリの場合)	Azure portal で生成されたアプリケーションシークレット。クライアントが安全にクライアントシークレットを格納できる Web アプリのシナリオでは、このフローでクライアントシークレットが使用されます。ネイティブアプリ (パブリッククライアント) のシナリオでは、クライアントシークレットは安全に保存できないため、この呼び出しでは使用されません。クライアントシークレットを使用する場合は、定期的に変更してください。
grant_type	必須	付与の種類。この段階の承認コードフローでは、付与の種類には `refresh_token` を指定する必要があります。
scope	推奨	スコープのスペース区切りリスト。 1 つのスコープ値が、要求されている両方のアクセス許可を Microsoft Entra ID に示します。クライアント ID をスコープとして使用することは、同じクライアント ID で表される、独自のサービスまたは Web API に対して使用できるアクセストークンをアプリが必要とすることを示します。 `offline_access` スコープは、アプリがリソースに長時間アクセスするには更新トークンが必要になることを示します。 Azure AD B2C に ID トークンを要求するために、`openid` スコープを使用することもできます。
redirect_uri	オプション	承認コードを受け取った、アプリケーションのリダイレクト URI。
refresh_token	必須	フローの第 2 段階で取得した元の更新トークン。

正常なトークン応答は次のようになります。

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

パラメーター	説明
not_before	トークンが有効と見なされる時間 (エポック時間)。
token_type	トークンタイプ値。 Microsoft Entra ID でサポートされる種類はベアラーのみです。
access_token	要求した署名付きの JWT。
scope	トークンが有効である範囲。スコープを使用して、後で使用するトークンをキャッシュすることもできます。
expires_in	トークンが有効な時間の長さ (秒単位)。
refresh_token	OAuth 2.0 更新トークン。現在のトークンの有効期限が切れた後、アプリはこのトークンを使用して、追加のトークンを取得します。更新トークンは有効期間が長く、リソースへのアクセスを長時間保持するときに利用できます。詳細については、「Azure AD B2C: トークンリファレンス」を参照してください。

エラー応答は次のようになります。

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

パラメーター	説明
error	発生したエラーの種類を分類する際に使用できるエラーコード文字列。この文字列はエラーへの対応に利用することもできます。
error_description	認証エラーの根本的な原因を特定しやすいように記述した具体的なエラーメッセージ。

独自の Azure AD B2C ディレクトリを使用する

これらの要求を自分で試すには、次の手順を実行します。この記事で使用したサンプルの値を独自の値で置き換えます。

Azure AD B2C ディレクトリを作成します。要求で独自のディレクトリの名前を使用します。
アプリケーションを作成し、アプリケーション ID とリダイレクト URI を取得します。アプリにネイティブクライアントを含めます。
使用するユーザーフローを作成して、そのユーザーフロー名を取得します。

次の方法で共有

Azure Active Directory B2C での OAuth 2.0 承認コードフロー

シングルページアプリに必要なリダイレクト URI セットアップ

1.承認コードを取得する

2.アクセストークンを取得する

3.トークンを使用する

4.トークンを更新する

独自の Azure AD B2C ディレクトリを使用する

フィードバック

その他のリソース

次の方法で共有

Azure Active Directory B2C での OAuth 2.0 承認コード フロー

シングル ページ アプリに必要なリダイレクト URI セットアップ

1.承認コードを取得する

2.アクセス トークンを取得する

3.トークンを使用する

4.トークンを更新する

独自の Azure AD B2C ディレクトリを使用する

フィードバック

その他のリソース

Azure Active Directory B2C での OAuth 2.0 承認コードフロー

シングルページアプリに必要なリダイレクト URI セットアップ

2.アクセストークンを取得する