トークン発行イベント用にカスタム クレーム プロバイダーを構成する

この記事では、トークン発行開始イベント用にカスタム クレーム プロバイダーを構成する方法について説明します。 既存の Azure 関数 REST API を使用して、カスタム認証拡張機能を登録し、REST API から解析する属性を追加します。 カスタム認証拡張機能をテストするため、サンプルの OpenID Connect アプリケーションを登録してトークンを取得し、クレームを表示します。

前提条件

• Azure Functions を作成できる Azure サブスクリプション。 既存の Azure アカウントをお持ちでない場合は、アカウントを作成するときに、無料試用版にサインアップするか、Visual Studio Subscription のベネフィットを利用できます。
• トークン発行開始イベント用に構成された HTTP トリガー関数を持つ Azure 関数 アプリ。 アプリをお持ちでない場合は、「トークン発行開始イベント HTTP トリガー関数を作成する」の手順に従ってください。
• カスタム認証拡張機能の概要に関する記事で説明されている概念の基本的な理解。
• Microsoft Entra ID テナント。 この攻略ガイドには、顧客または従業員のどちらかのテナントを使用できます。
  • 外部テナントの場合は、サインアップとサインインのユーザー フローを使用します。

手順 1: カスタム認証拡張機能を登録する

ここでは、Microsoft Entra ID が Azure 関数を呼び出すために使用するカスタム認証拡張機能を構成します。 カスタム認証拡張機能には、REST API エンドポイントに関する情報、REST API から解析するクレーム、REST API に対する認証方法が含まれています。 次の手順のようにして、カスタム認証拡張機能を Azure 関数 アプリに登録します。

Note

最大 100 個のカスタム拡張機能ポリシーを使用できます。

Azure Portal

カスタム認証拡張機能を登録する

1. アプリケーション管理者および認証管理者以上の権限で Azure portal にサインインします。
2. [Microsoft Entra ID] を検索して選択し、[エンタープライズ アプリケーション] を選択します。
3. [カスタム認証拡張機能] を選択して、[カスタム拡張機能の作成] を選択します。
4. [基本] でイベントの種類に [TokenIssuanceStart] を選択し、[次へ] を選択します。
5. [エンドポイントの構成] で、次のプロパティを入力します。
   • [名前] - カスタム認証拡張機能の名前。 例: "トークン発行イベント"。
   • [ターゲット URL] - Azure 関数の URL の {Function_Url}。 Azure 関数 アプリの [概要] ページに移動し、作成した関数を選択します。 関数の [概要] ページで、[関数の URL の取得] を選択し、コピー アイコンを使用して URL をコピーします。
   • [説明] - カスタム認証拡張機能の説明。
6. [次へ] を選択します。
7. [API 認証] で [アプリの登録を新規作成する] オプションを選んで、"関数アプリ" を表すアプリ登録を作成します。
8. アプリの名前を指定します (例: Azure Functions 認証イベント API)。
9. [次へ] を選択します。
10. [要求] に、カスタム認証拡張機能で REST API から解析されてトークンにマージされる属性を入力します。 次のクレームを追加します。
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
11. [次へ]、[作成] の順に選択します。これにより、カスタム認証拡張機能とそれに関連付けられているアプリケーションの登録が登録されます。
12. [API 認証] の下の [アプリ ID]に注意してください。これは、Azure 関数 アプリで環境変数を設定するために必要です。

Microsoft Graph

アプリケーションの登録

1. ホーム テナントがカスタム認証拡張機能を管理するテナントであるアカウントを使って、Graph エクスプローラーにサインインします。 このアカウントには、テナントでアプリケーション登録を作成および管理するための特権が必要です。

2. 次の要求を実行します。

   POST https://graph.microsoft.com/v1.0/applications
   Content-type: application/json
   
   {
       "displayName": "authenticationeventsAPI"
   }
   

3. 応答から、新しく作成されたアプリ登録の id と appId の値を記録します。 これらの値は、この記事で {authenticationeventsAPI_ObjectId} と {authenticationeventsAPI_AppId} としてそれぞれ参照されます。

authenticationeventsAPI アプリ登録用のサービス プリンシパルをテナントに作成します。

Graph エクスプローラーで、次の要求を実行します。 {authenticationeventsAPI_AppId} を、前の手順で記録した appId の値に置き換えます。

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
    
{
    "appId": "{authenticationeventsAPI_AppId}"
}

アプリ ID URI、アクセス トークンのバージョン、必要なリソース アクセスを設定する

新しく作成したアプリケーションを更新して、アプリケーション ID URI の値、アクセス トークンのバージョン、必要なリソース アクセスを設定します。

Graph エクスプローラーで、次の要求を実行します。

• identifierUris プロパティにアプリケーション ID URI の値を設定します。 {Function_Url_Hostname} を、前に記録した {Function_Url} のホスト名に置き換えます。
• 前に記録した appId で {authenticationeventsAPI_AppId} 値を設定します。
• 値の例は api://authenticationeventsAPI.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444 です。 この値は、{functionApp_IdentifierUri} の代わりにこの記事の後半で使用するので、メモしておきます。

POST https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
"identifierUris": [
    "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
],    
"api": {
    "requestedAccessTokenVersion": 2,
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
},
"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "type": "Role"
            }
        ]
    }
]
}

カスタム認証拡張機能を登録する

カスタム認証拡張機能を登録するには、それを Azure 関数のアプリ登録および Azure 関数エンドポイント {Function_Url} と関連付けます。

1. Graph エクスプローラーで、次の要求を実行します。 {Function_Url} を Azure 関数アプリのホスト名に置き換えます。 {functionApp_IdentifierUri} は、前のステップで使った identifierUri に置き換えます。

   • CustomAuthenticationExtension.ReadWrite.All の委任されたアクセス許可が必要です。

   POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
       "displayName": "onTokenIssuanceStartCustomExtension",
       "description": "Fetch additional claims from custom user store",
       "endpointConfiguration": {
           "@odata.type": "#microsoft.graph.httpRequestEndpoint",
           "targetUrl": "{Function_Url}"
       },
       "authenticationConfiguration": {
           "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
           "resourceId": "{functionApp_IdentifierUri}"
       },
       "claimsForTokenConfiguration": [
           {
               "claimIdInApiResponse": "DateOfBirth"
           },
           {
               "claimIdInApiResponse": "CustomRoles"
           }
       ]
   }
   

2. 作成されたカスタム クレーム プロバイダー オブジェクトの id の値を記録しておきます。 この値は、このチュートリアルの後半で {customExtensionObjectId} の代わりに使います。

1.2 管理者の同意の付与

カスタム認証拡張機能が作成されたら、API にアクセス許可を付与する必要があります。 カスタム認証拡張機能は、client_credentials を使い、Receive custom authentication extension HTTP requests アクセス許可を使って Azure Function App に対する認証を行います。

1. 新しいカスタム認証拡張機能の概要ページを開きます。 ID プロバイダーを追加するときに必要になるため、[API 認証] の下にあるアプリ ID を書き留めます。

2. [API 認証] の下にある [アクセス許可の付与] を選択します。

3. 新しいウィンドウが開き、サインインすると、カスタム認証拡張機能の HTTP 要求を受信するためのアクセス許可が要求されます。 これで、API に対してカスタム認証拡張機能を認証できるようになります。 [Accept](承認) を選択します。

   

手順 2: エンリッチされたトークンを受信するように OpenID Connect アプリを構成する

トークンを取得してカスタム認証拡張機能をテストするには、https://jwt.ms アプリを使用できます。 これは Microsoft 所有の Web アプリケーションであり、トークンのデコードされた内容を表示します (トークンの内容がお使いのブラウザーの外に出ることはありません)。

2.1 テスト Web アプリケーションを登録する

次の手順のようにして、jwt.ms Web アプリケーションを登録します。

1. Azure portal のホームページで、[Microsoft Entra ID]を選択します。

2. [アプリの登録]>[新しい登録] の順に選びます。

3. アプリケーションの名前を入力します。 例: マイ テスト アプリケーション。

4. [サポートされているアカウントの種類] で、 [この組織のディレクトリ内のアカウントのみ] を選択します。

5. [リダイレクト URI] の [プラットフォームの選択] ドロップダウンで [Web] を選び、[URL] テキスト ボックスに「https://jwt.ms」と入力します。

6. [登録] を選んで、アプリの登録を完了します。

   

7. アプリの登録の概要ページで、[アプリケーション (クライアント) ID] をコピーします。 後の手順では、アプリ ID を {App_to_enrich_ID} として参照します。 Microsoft Graph では、appId プロパティによって参照されます。

   

2.2 暗黙的なフローを有効にする

jwt.ms テスト アプリケーションでは、暗黙的なフローを使います。 "マイ テスト アプリケーション" の登録で暗黙的なフローを有効にします。

1. [管理] で、 [認証] を選択します。
2. [暗黙的な許可およびハイブリッド フロー] で、[ID トークン (暗黙的およびハイブリッド フローに使用)] チェックボックスをオンにします。
3. [保存] を選択します。

2.3 クレーム マッピング ポリシーに対してアプリを有効にする

カスタム認証拡張機能から返された属性から、トークンにマップされるものを選ぶには、クレーム マッピング ポリシーを使います。 トークンを拡張できるようにするには、アプリケーション登録によるマップされたクレームの受け入れを明示的に有効にする必要があります。

1. "マイ テスト アプリケーション" の登録で、[管理] の [マニフェスト] を選びます。
2. マニフェストで acceptMappedClaims 属性を見つけて、値を true に設定します。
3. accessTokenAcceptedVersion を 2 に設定します。
4. [保存] を選択して変更を保存します。

次の JSON スニペットでは、これらのプロパティを構成する方法を示します。

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

警告

マルチテナント アプリでは acceptMappedClaims プロパティを true に設定しないでください。悪意のある者がアプリのクレームマッピング ポリシーを作成することを許可してしまう場合があります。 代わりに、カスタム署名キーを構成します。

従業員テナント

次のステップ「カスタム クレーム プロバイダーをアプリに割り当てる」に進みます。

外部テナント

3.4 アプリをユーザー フローに関連付ける

外部テナントの場合は、アプリをユーザー フローに関連付ける必要があります。 ユーザー フローによって、顧客がアプリケーションにサインインするために使用できる認証方法と、サインアップ中に指定する必要のある情報が定義されます。 ユーザー フローへの "マイ テスト アプリケーション" の追加を続行する前に、「アプリケーションをユーザー フローに追加する」のステップを完了していることを確認してください。

手順 3: カスタム クレーム プロバイダーをアプリに割り当てる

カスタム認証拡張機能から受け取ったクレームでトークンが発行されるようにするには、カスタム クレーム プロバイダーをアプリケーションに割り当てる必要があります。 これはトークンの対象ユーザーに基づいているため、ID トークンで要求を受け取るにはクライアント アプリケーションにプロバイダーを割り当て、アクセス トークンで要求を受け取るにはリソース アプリケーションにプロバイダーを割り当てる必要があります。 カスタム クレーム プロバイダーは、トークン発行開始イベント リスナーで構成されたカスタム認証拡張機能に依存します。 カスタム クレーム プロバイダーからのクレームのすべてまたはサブセットのどちらを、トークンにマップするかを選択できます。

Note

アプリケーションとカスタム拡張機能の間で作成できる一意の割り当ては 250 個のみです。 複数のアプリに同じカスタム拡張機能呼び出しを適用する場合は、 authenticationEventListeners Microsoft Graph API を使用して、複数のアプリケーションのリスナーを作成することをお勧めします。 これは Azure portal ではサポートされていません。

次の手順のようにして、マイ テスト アプリケーション とカスタム認証拡張機能を接続します。

Azure Portal

カスタム認証拡張機能をカスタム クレーム プロバイダー ソースとして割り当てるには、次を行います。

1. Azure portal のホームページで、[Microsoft Entra ID]を選択します。

2. [エンタープライズ アプリケーション] を選択し、その後 [管理] で、[すべてのアプリケーション] を選択します。 一覧から[マイ テスト アプリケーション] を選択します。

3. "マイ テスト アプリケーション" の概要ページで、[管理] に移動し、[シングル サインオン] を選択します。

4. [属性とクレーム] で、[編集] を選びます。

   

5. [詳細設定] メニューを展開します。

6. [カスタム クレーム プロバイダー] の横にある [構成] を選択します。

7. [Custom claims provider] (カスタム クレーム プロバイダー) ドロップダウン ボックスを展開して、前に作成した "トークン発行イベント" を選びます。

8. [保存] を選択します。

次に、カスタム クレーム プロバイダーから属性を割り当てます。これは、クレームとしてトークンに発行されている必要があります。

1. [新しクレームの追加] を選んで、新しいクレームを追加します。 発行するクレームに名前を指定します (例: dateOfBirth)。

2. [ソース] の下にある [属性] を選択し、[ソース属性] ドロップダウン ボックスから [customClaimsProvider.dateOfBirth] を選択します。

   

3. [保存] を選択します。

4. このプロセスを繰り返して、[customClaimsProvider.customRoles]、[customClaimsProvider.apiVersion]、[customClaimsProvider.correlationId] の属性と、それぞれに対応する名前を追加します。 クレームの名前と属性の名前は一致させることをお勧めします。

Microsoft Graph

最初に、トークン発行開始イベントを使って My Test アプリケーション のカスタム認証拡張機能をトリガーするイベント リスナーを作成します。

1. ホーム テナントがカスタム認証拡張機能を管理するテナントであるアカウントを使って、Graph エクスプローラーにサインインします。

2. 次の要求を実行します。 {App_to_enrich_ID} を、前に記録した "マイ テスト アプリケーション" のアプリ ID に置き換えます。 {customExtensionObjectId} を、前に記録したカスタム認証拡張機能の ID に置き換えます。

   • EventListener.ReadWrite.All の委任されたアクセス許可が必要です。

   POST https://graph.microsoft.com/beta/identity/authenticationEventListeners
   Content-type: application/json
   
   {
       "@odata.type": "#microsoft.graph.onTokenIssuanceStartListener",
       "conditions": {
           "applications": {
               "includeAllApplications": false,
               "includeApplications": [
                   {
                       "appId": "{App_to_enrich_ID}"
                   }
               ]
           }
       },
       "priority": 500,
       "handler": {
           "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtensionHandler",
           "customExtension": {
               "id": "{customExtensionObjectId}"
           }
       }
   }
   

次に、カスタム クレーム プロバイダーからアプリケーションに発行できるクレームが記述されているクレーム マッピング ポリシーを作成します。

1. 引き続き Graph エクスプローラーで、次の要求を実行します。 Policy.ReadWrite.ApplicationConfiguration の委任されたアクセス許可が必要です。

   POST https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies
   Content-type: application/json
   
   {
       "definition": [
           "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
       ],
       "displayName": "MyClaimsMappingPolicy",
       "isOrganizationDefault": false
   }
   

2. 応答で生成された ID を記録します。後で {claims_mapping_policy_ID} として参照します。

サービス プリンシパル オブジェクト ID を保存します:

1. Graph エクスプローラーで、次の要求を実行します。 {App_to_enrich_ID} を My Test Application の appId に置き換えます。

   GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')
   

ID の値を記録します。

クレーム マッピング ポリシーを My Test Application のサービス プリンシパルに割り当てます。

1. Graph エクスプローラーで、次の要求を実行します。 Policy.ReadWrite.ApplicationConfiguration と Application.ReadWrite.All の委任されたアクセス許可が必要です。

   POST https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref
   Content-type: application/json
   
   {
       "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
   }
   

手順 4: Azure 関数を保護する

Microsoft Entra カスタム認証拡張機能は、サーバー間フローを使って、HTTP の Authorization ヘッダーで Azure 関数に送信されるアクセス トークンを取得します。 関数を Azure に発行するときは、特に運用環境では、Authorization ヘッダーで送信されるトークンを検証する必要があります。

Azure 関数を保護するには、受信したトークンを Azure Functions 認証イベント API アプリケーション登録で検証するため、次の手順のようにして Azure AD 認証を統合します。 テナントの種類に基づいて、次のいずれかのタブを選択します。

Note

Azure 関数アプリが、カスタム認証拡張機能が登録されているテナントとは異なる Azure テナントでホストされている場合は、[OpenID Connect] タブを選択してください。

4.1 Microsoft Entra ID の ID プロバイダーの使用

ID プロバイダーとして Microsoft Entra を Azure 関数アプリに追加するには、次のステップに従います。

従業員テナント

1. Azure portal で、前に発行した関数アプリを探して選択します。

2. [設定] で [認証] を選択します。

3. [ID プロバイダーの追加] を選びます。

4. ID プロバイダーとして [Microsoft] を選択します。

5. テナントの種類として [従業員] を選択します。

6. [アプリの登録] の下で、[アプリ登録の種類] に [このディレクトリ内の既存のアプリ登録を選択] を選択し、カスタム クレーム プロバイダーの登録時に前に作成した "Azure Functions 認証イベント API" アプリ登録を選択します。

7. 発行者 URL https://login.microsoftonline.com/{tenantId}/v2.0 を入力します。ここで、{tenantId} は従業員テナントのテナント ID です。

8. [Unauthenticated requests] (認証されていない要求) で、ID プロバイダーとして [HTTP 401 認可されていない] を選びます。

9. [トークン ストア] オプションをオフにします。

10. [追加] を選んで、Azure 関数に認証を追加します。

    

外部テナント

1. Azure portal で、前に発行した関数アプリを探して選択します。

2. [設定] で [認証] を選択します。

3. [ID プロバイダーの追加] を選びます。

4. ID プロバイダーとして [Microsoft] を選択します。

5. テナントの種類として [顧客] を選択します。

6. [アプリの登録] の下に、カスタム クレーム プロバイダーの登録時に前に作成した "Azure Functions 認証イベント API" アプリ登録の client_id を入力します。

7. [発行者 URL] に、URL https://{domainName}.ciamlogin.com/{tenant_id}/v2.0 を入力します。ここで

   • {domainName} は、{domainName}.contoso.com の形式の、外部テナントのドメイン名です。
   • {tenantId} は外部テナントのテナント ID です。

8. [Unauthenticated requests] (認証されていない要求) で、ID プロバイダーとして [HTTP 401 認可されていない] を選びます。

9. [トークン ストア] オプションをオフにします。

10. [追加] を選んで、Azure 関数に認証を追加します。

    

4.2 OpenID Connect ID プロバイダーの使用

Microsoft ID プロバイダーを構成した場合は、このステップをスキップします。 そうではなく、カスタム認証拡張機能が登録されているテナントとは異なるテナントで Azure 関数がホストされている場合は、次の手順のようにして関数を保護します。

クライアント シークレットの作成

1. Azure portal のホーム ページから、[Microsoft Entra ID]>[アプリの登録] を選択します。
2. 前に作成した "Azure Functions 認証イベント API" アプリの登録を選択します。
3. [証明書とシークレット]>[Client secrets]\(クライアント シークレット\)>[新しいクライアント シークレット] の順に選択します。
4. シークレットの有効期限を選択するか、カスタムの有効期間を指定し、説明を追加して、[追加] を選択します。
5. クライアント アプリケーションのコードで使用できるように、シークレットの値を記録しておきます。 このページからの移動後は、このシークレットの値は "二度と表示されません"。

OpenID Connect ID プロバイダーを Azure 関数アプリに追加します。

1. 前に発行した関数アプリを探して選択します。

2. [設定] で [認証] を選択します。

3. [ID プロバイダーの追加] を選びます。

4. ID プロバイダーとして [OpenID Connect] を選びます。

5. Contoso Microsoft Entra ID などの名前を指定します。

6. [メタデータ エントリ] で、[ドキュメントの URL] に次の URL を入力します。 {tenantId} を Microsoft Entra テナント ID に置き換えます。

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. [アプリの登録] で、前に作成した "Azure Functions 認証イベント API" アプリ登録のアプリケーション ID (クライアント ID) を入力します。

8. Azure 関数に戻り、[アプリの登録] の下で [クライアント シークレット] を入力します。

9. [トークン ストア] オプションをオフにします。

10. [追加] を選んで、OpenID Connect ID プロバイダーを追加します。

ステップ 5: アプリケーションをテストする

カスタム クレーム プロバイダーをテストするには、次のステップに従います。

従業員テナント

1. 新しいプライベート ブラウザーを開き、次の URL に移動してサインインします。

   https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. {tenantId} は、テナント ID、テナント名、または検証済みドメイン名の 1 つに置き換えます。 たとえば、contoso.onmicrosoft.com のようにします。

3. {App_to_enrich_ID} を、"マイ テスト アプリケーション" クライアント ID に置き換えます。

4. ログインすると、https://jwt.ms でデコードされたトークンが表示されます。 Azure 関数からのクレームがデコードされたトークンで提示されていることを確認します (例: dateOfBirth)。

外部テナント

1. 新しいプライベート ブラウザーを開き、次の URL に移動してサインインします。

   https://{domainName}.ciamlogin.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
   

2. {domainName} を自分のドメイン名 (contoso など) に置き換えます。

3. {tenantId} は、テナント ID、テナント名、または検証済みドメイン名の 1 つに置き換えます。 たとえば、contoso.onmicrosoft.com のようにします。

4. {App_to_enrich_ID} を、"マイ テスト アプリケーション" クライアント ID に置き換えます。

5. 構成したサインイン ユーザー フローを確認し、要求されたアクセス許可を受け入れます。

6. ログインすると、https://jwt.ms でデコードされたトークンが表示されます。 Azure 関数からのクレームがデコードされたトークンで提示されていることを確認します (例: dateOfBirth)。

関連項目

• 外部ストアからのクレームを含むトークンを受信するように SAML アプリを構成する
• カスタム クレーム プロバイダー リファレンス
• カスタム認証拡張機能 API のトラブルシューティング