Microsoft ID プラットフォームと OAuth 2.0 SAML ベアラー アサーション フローMicrosoft identity platform and OAuth 2.0 SAML bearer assertion flow

OAuth 2.0 SAML ベアラー アサーション フローでは、クライアントが既存の信頼関係を使用する必要があるときに、SAML アサーションを使用して OAuth アクセス トークンを要求することができます。The OAuth 2.0 SAML bearer assertion flow allows you to request an OAuth access token using a SAML assertion when a client needs to use an existing trust relationship. SAML アサーションに適用される署名は、承認されたアプリの認証を提供します。The signature applied to the SAML assertion provides authentication of the authorized app. SAML アサーションは、ID プロバイダーによって発行され、サービス プロバイダーによって使用される XML セキュリティ トークンです。A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider. サービス プロバイダーは、セキュリティ関連の目的でアサーションの対象を識別するために、そのコンテンツに依存します。The service provider relies on its content to identify the assertion’s subject for security-related purposes.

SAML アサーションは、OAuth トークン エンドポイントにポストされます。The SAML assertion is posted to the OAuth token endpoint. エンドポイントはアサーションを処理し、アプリの事前の承認に基づいてアクセス トークンを発行します。The endpoint processes the assertion and issues an access token based on prior approval of the app. クライアントでは、更新トークンを持つ必要も保存する必要もありません。また、トークン エンドポイントに渡す必要があるクライアント シークレットも不要です。The client isn’t required to have or store a refresh token, nor is the client secret required to be passed to the token endpoint.

SAML ベアラー アサーション フローは、ユーザーに資格情報の入力を求めることなく Microsoft Graph API (委任されたアクセス許可のみをサポート) からデータをフェッチする場合に便利です。SAML Bearer Assertion flow is useful when fetching data from Microsoft Graph APIs (which only support delegated permissions) without prompting the user for credentials. このシナリオでは、バックグラウンド プロセスで推奨されるクライアント資格情報の付与は機能しません。In this scenario the client credentials grant, which is preferred for background processes, does not work.

ブラウザーベースの対話型サインインを実行して SAML アサーションを取得してから、OAuth で保護された API (Microsoft Graph など) にアクセスを追加するアプリケーションの場合、API のアクセス トークンを取得する OAuth 要求を行うことができます。For applications that do interactive browser-based sign-in to get a SAML assertion and then want to add access to an OAuth protected API (such as Microsoft Graph), you can make an OAuth request to get an access token for the API. ユーザーを認証するためにブラウザーが Azure AD にリダイレクトされると、ブラウザーは SAML サインインからセッションを取得し、ユーザーは資格情報を入力する必要はありません。When the browser is redirected to Azure AD to authenticate the user, the browser will pick up the session from the SAML sign-in and the user doesn't need to enter their credentials.

OAuth SAML ベアラー アサーション フローは、Azure Active Directory との間で認証連携された Active Directory フェデレーション サービス (ADFS) などの ID プロバイダーを使用して認証されるユーザーに対してのみサポートされます。The OAuth SAML Bearer Assertion flow is only supported for users authenticating with identity providers such as Active Directory Federation Services (ADFS) federated to Azure Active Directory. ADFS から取得した SAML アサーションを OAuth フローで使用して、ユーザーを認証できます。The SAML assertion obtained from ADFS can be used in an OAuth flow to authenticate the user.

OAuth フロー

SAML ベアラー アサーションを使用して Graph を呼び出すCall Graph using SAML bearer assertion

ここで、実際にプログラムで SAML アサーションを取得する方法について説明します。Now let us understand on how we can actually fetch SAML assertion programatically. この方法は、ADFS を使用してテストされます。This approach is tested with ADFS. ただし、これが機能するのは、プログラムで SAML アサーションが返されるのをサポートしている ID プロバイダーを使用した場合になります。However, this works with any identity provider that supports the return of SAML assertion programatically. 基本的なプロセスとしては、SAML アサーションを取得し、アクセス トークンを取得して、Microsoft Graph にアクセスします。The basic process is: get a SAML assertion, get an access token, and access Microsoft Graph.

前提条件Prerequisites

承認サーバー/環境 (Microsoft 365) と ID プロバイダー、または SAML 2.0 ベアラー アサーションの発行者 (ADFS) との間で信頼関係を確立します。Establish a trust relationship between the authorization server/environment (Microsoft 365) and the identity provider, or issuer of the SAML 2.0 bearer assertion (ADFS). シングル サインオン用および ID プロバイダーとして ADFS を構成するには、こちらの記事をご覧ください。To configure ADFS for single sign-on and as an identity provider you may refer to this article.

次の手順に従って、ポータルでアプリケーションを登録します。Register the application in the portal:

  1. ポータルの [アプリの登録] ブレードにサインインします (Graph API には v2.0 エンドポイントを使用しているため、このポータルでアプリケーションを登録する必要があることに注意してください。Sign in to the app registration blade of the portal (Please note that we are using the v2.0 endpoints for Graph API and hence need to register the application in this portal. それ以外の場合は、Azure Active Directory での登録を使用することもできます)。Otherwise we could have used the registrations in Azure active directory).
  2. [新規登録] を選択します。Select New registration.
  3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。When the Register an application page appears, enter your application's registration information:
    1. [名前] - アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します。Name - Enter a meaningful application name that will be displayed to users of the app.
    2. [サポートされているアカウントの種類] - アプリケーションでサポートするアカウントを選択します。Supported account types - Select which accounts you would like your application to support.
    3. [リダイレクト URI (省略可能)] - 構築するアプリの種類として [Web クライアント] または [パブリック クライアント (モバイルとデスクトップ)] を選択してから、アプリケーションのリダイレクト URI (または応答 URL) を入力します。Redirect URI (optional) - Select the type of app you're building, Web, or Public client (mobile & desktop), and then enter the redirect URI (or reply URL) for your application.
    4. 終了したら、 [登録] を選択します。When finished, select Register.
  4. アプリケーション (クライアント) ID をメモします。Make a note of the application (client) ID.
  5. 左側のウィンドウで、 [証明書とシークレット] を選択します。In the left pane, select Certificates & secrets. [クライアント シークレット] セクションで、 [新しいクライアント シークレット] をクリックします。Click New client secret in the Client secrets section. 新しいクライアント シークレットをコピーしてください。このブレードから移動すると取得できなくなります。Copy the new client secret, you won't be able to retrieve when you leave the blade.
  6. 左側のウィンドウで、 [API のアクセス許可][アクセス許可の追加] の順に選択します。In the left pane, select API permissions and then Add a permission. Outlook Graph API を使用する予定のため、 [Microsoft Graph] を選択し、 [委任されたアクセス許可] を選択してから、 [Tasks.read] を選択します。Select Microsoft Graph, then delegated permissions, and then select Tasks.read since we intend to use the Outlook Graph API.

サンプル要求をテストするために必要なツールである Postman をインストールします。Install Postman, a tool required to test the sample requests. 後で、要求をコードに変換できます。Later, you can convert the requests to code.

ADFS から SAML アサーションを取得するGet the SAML assertion from ADFS

SOAP エンベロープを使用して SAML アサーションをフェッチするために、ADFS エンドポイントへの POST 要求を作成します。Create a POST request to the ADFS endpoint using SOAP envelope to fetch the SAML assertion:

SAML アサーションを取得する

ヘッダー値:Header values:

ヘッダー値

ADFS 要求本文:ADFS request body:

ADFS 要求本文

この要求が正常にポストされると、ADFS から SAML アサーションを受け取ります。Once this request is posted successfully, you should receive a SAML assertion from ADFS. SAML:Assertion タグ データのみが必要です。今後の要求で使用するには、base64 エンコードに変換してください。Only the SAML:Assertion tag data is required, convert it to base64 encoding to use in further requests.

SAML アサーションを使用して OAuth2 トークンを取得するGet the OAuth2 token using the SAML assertion

この手順では、ADFS アサーション応答を使用して OAuth2 トークンをフェッチします。In this step, fetch an OAuth2 token using the ADFS assertion response.

  1. 以下に示すように、ヘッダー値を使用して POST 要求を作成します。Create a POST request as shown below with the header values:

    POST 要求

  2. 要求の本文で、client_idclient_secret、および assertion (前の手順で取得した base64 エンコードの SAML アサーション) を置き換えます。In the body of the request, replace client_id, client_secret, and assertion (the base64 encoded SAML assertion obtained the previous step):

    要求本文

  3. 要求が成功すると、Azure Active Directory からアクセス トークンを受け取ります。Upon successful request, you will receive an access token from Azure active directory.

Oauth トークンを使用してデータを取得するGet the data with the Oauth token

アクセス トークンを受け取ったら、Graph API (この例では Outlook タスク) を呼び出します。After receiving the access token, call the Graph APIs (Outlook tasks in this example).

  1. 前の手順でフェッチしたアクセス トークンを使用して GET 要求を作成します。Create a GET request with the access token fetched in the previous step:

    GET 要求

  2. 要求が成功すると、JSON 応答を受け取ります。Upon successful request, you will receive a JSON response.

次のステップNext steps

さまざまな認証フローとアプリケーションのシナリオについて学習します。Learn about the different authentication flows and application scenarios.