.NET 用Azure Functionsクライアントライブラリの認証イベントトリガー

[アーティクル]
04/18/2023

Azure Functionsの認証イベントトリガーを使用すると、Azure Active Directory (Azure AD) 認証イベントを処理するカスタム拡張機能を実装できます。認証イベントトリガーは、Azure AD 認証イベントの受信 HTTP 要求に対するすべてのバックエンド処理を処理し、開発者に次の機能を提供します。

API 呼び出しをセキュリティで保護するためのトークン検証
オブジェクトモデル、型指定、IDE IntelliSense
API 要求スキーマと応答スキーマの受信と送信の検証

作業の開始

パッケージをインストールする

NuGet でAzure Functionsの認証イベントトリガーをインストールします。

dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --prerelease

前提条件

Azure サブスクリプション:Azure Functionsを含む Azure サービスを使用するには、サブスクリプションが必要です。既存の Azure アカウントをお持ちでない場合は、無料試用版にサインアップするか、アカウントの作成時に Visual Studio サブスクリプション特典を使用できます。

クライアントを認証する

Azure AD 認証イベントサービスは、カスタム拡張機能を呼び出すときに、を含むヘッダーをAuthorizationBearer {token}送信します。このトークンは、次のサービス間認証を表します。

"リソース" は、 対象ユーザーとも呼ばれ、API を表すために登録するアプリケーションです。これは、トークン内の aud 要求によって表されます。
"クライアント" は、Azure AD 認証イベントサービスを表す Microsoft アプリケーションです。値は appId です 99045fe1-7639-4a75-9d4a-577b6ca3810f。これは、次の方法で表されます。
- azpアプリケーション accessTokenAcceptedVersion プロパティがに設定されている場合のトークン内の2要求。
- appidリソースアプリケーションのプロパティがまたは nullに1設定されている場合のトークン内のaccessTokenAcceptedVersion要求。

関数アプリへの HTTP 要求を認証し、トークンを検証するには、3 つの方法があります。

Azure Functions Azure AD 認証統合を使用してトークンを検証する

運用環境で関数を実行する場合は、Azure Functions Azure AD 認証統合を使用して受信トークンを検証することを強くお勧めします。次の関数アプリケーション設定を設定します。

関数アプリの [認証] タブに移動します
[ID プロバイダーの追加] をクリックします
ID プロバイダーとして [Microsoft] を選択します
[既存のアプリ登録の詳細を指定する] を選択します
Azure AD で Application ID API を表すアプリのを入力します

発行者と許可対象ユーザーは、アプリケーションのプロパティに依存 accessTokenAcceptedVersion します (アプリケーションの "マニフェスト" にあります)。

プロパティが accessTokenAcceptedVersion : 6 に 2設定されている場合は、appId') を設定します Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (。

プロパティが accessTokenAcceptedVersion または nullに1設定されている場合:6。カスタムドメイン名を使用している場合は、identifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' を設定Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asします。

既定では、認証イベントトリガーは Azure Function 認証統合が構成されていることを検証し、トークン内のクライアントが (トークンのまたは appid 要求を介してazp) に99045fe1-7639-4a75-9d4a-577b6ca3810f設定されていることをチェックします。

Postman の使用など、Azure AD 認証イベントサービスではない他のクライアントに対して API をテストする場合は、 オプション のアプリケーション設定を構成できます。

AuthenticationEvents__CustomCallerAppId - 目的のクライアントの guid。指定されていない場合は、 99045fe1-7639-4a75-9d4a-577b6ca3810f と見なされます。

トリガーでトークンを検証する

Azure Function サービスでホストされていないローカル環境または環境では、トリガーでトークンの検証を実行できます。 local.settings.json ファイルで次のアプリケーション設定を設定します。

AuthenticationEvents__TenantId - テナント ID
AuthenticationEvents__AudienceAppId - オプション 1 の "許可対象ユーザー" と同じ値。
AuthenticationEvents__CustomCallerAppId (省略可能) - 目的のクライアントの guid。指定されていない場合は、 99045fe1-7639-4a75-9d4a-577b6ca3810f と見なされます。

local.settings.json ファイルの例:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

トークンの検証なし

ローカル開発中にトークンを認証 しない 場合は、 local.settings.json ファイルで次のアプリケーション設定を設定します。

AuthenticationEvents__BypassTokenValidation - のtrue値を指定すると、トークンの検証に対してトリガーがチェックされなくなります。

クイックスタート

Visual Studio 2019
- Visual Studio を起動する
- [新しいプロジェクトの作成] を選択します
- テンプレート検索領域で[AzureAuthEventsTrigger]\(AzureAuthEventsTrigger\) を選択します
- プロジェクトにわかりやすいプロジェクト名、場所、ソリューション、ソリューション名を指定します。
Visual Studio Code
- Visual Studio Code を開始します
- コマンドパレットを使用して、"Azure Authentication Events Trigger Project の作成" コマンドを実行します
- プロジェクトの作成プロンプトに従います
注意: 初回実行時には、必要なパッケージのダウンロードにしばらく時間がかかる場合があります。
テスト用のトークン検証の開発目的のターン:
AuthenticationEvents__BypassTokenValidation アプリケーションキーを local.settings.json ファイルの "Values" セクションに追加し、その値を true に設定します。ローカル環境に local.settings.json ファイルがない場合は、関数アプリのルートに作成します。

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

プロジェクトが読み込まれたら、サンプルコードを実行すると、Azure Functions 開発者のアプリケーションによってエンドポイントが読み込まれることがわかります。

主要な概念

.NET SDK

Azure .NET SDK の主な概念については、こちらを参照してください。

Azure AD カスタム拡張機能

カスタム拡張機能を使用すると、Azure AD イベントの処理、外部システムとの統合、アプリケーション認証エクスペリエンスでの動作のカスタマイズを行うことができます。たとえば、カスタムクレームプロバイダーは、Azure AD ディレクトリの一部として格納できない外部システムからの情報を使用してアプリケーショントークンを強化またはカスタマイズできるカスタム拡張機能です。

認証イベントトリガー

認証イベントトリガーを使用すると、Azure AD イベントサービスから認証イベントが送信されたときに関数を実行できます。

認証イベントによって出力バインドがトリガーされる

認証イベントトリガーの出力バインドを使用すると、関数は認証イベントアクションを Azure AD イベントサービスに送信できます。

ドキュメント

関数が発行されたものの 1 つは、ログ記録とメトリックに関する良い読み取りがここにある
API ドキュメントについては、(リンク TBD) を参照してください。
これがプレビューに移行すると、破壊的変更は行われず、プライベートプレビューを指す NuGet ソースを削除するのと同じくらい簡単になります。

例

トークン拡張をテストするには、次の操作を行います。

Visual Studio を起動します。
前の手順で作成したプロジェクトを開きます。 (クイックスタート)
アプリケーションを実行します。 (F5)
Azure Functions 開発者のアプリケーションが開始されたら、アプリケーションの起動時に表示されるリッスン URL をコピーします。
注: すべての認証関数が一覧表示されます。この場合、"OnTokenIssuanceStart" という名前の関数リスナーが 1 つ登録されています
関数エンドポイントは、リッスン URL と関数の組み合わせになります (例: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)&function=OnTokenIssuanceStart"
Postman や Fiddler などを使用して、次のペイロードを投稿します。
Postman を使用する手順が見つかります (リンク TBD)

{
  "type":"microsoft.graph.authenticationEvent.TokenIssuanceStart",
  "source":"/tenants/{tenantId}/applications/{resourceAppId}",
  "data":{
    "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
    "tenantId": "30000000-0000-0000-0000-000000000003",
    "authenticationEventListenerId1": "10000000-0000-0000-0000-000000000001",
    "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002",
    "authenticationContext1":{
      "correlationId": "20000000-0000-0000-0000-000000000002",
      "client": {
        "ip": "127.0.0.1",
        "locale": "en-us",
        "market": "en-au"
      },
      "authenticationProtocol": "OAUTH2.0",
      "clientServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000001",
        "appId": "40000000-0000-0000-0000-000000000002",
        "appDisplayName": "Test client app",
        "displayName": "Test client application"
      },
      "resourceServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000003",
        "appId": "40000000-0000-0000-0000-000000000004",
        "appDisplayName": "Test resource app",
        "displayName": "Test resource application"
      },
      "user": {
        "companyName": "Nick Gomez",
        "country": "USA",
        "createdDateTime": "0001-01-01T00:00:00Z",
        "displayName": "Dummy display name",
        "givenName": "Example",
        "id": "60000000-0000-0000-0000-000000000006",
        "mail": "test@example.com",
        "onPremisesSamAccountName": "testadmin",
        "onPremisesSecurityIdentifier": "DummySID",
        "onPremisesUserPrincipalName": "Dummy Name",
        "preferredDataLocation": "DummyDataLocation",
        "preferredLanguage": "DummyLanguage",
        "surname": "Test",
        "userPrincipalName": "testadmin@example.com",
        "userType": "UserTypeCloudManaged"
      }
    }
  }
}

次の応答が表示されます。

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

トラブルシューティング

Visual Studio Code
- Visual Studio Code で実行している場合は、ローカルの Azure Storage Emulator の行に沿ってエラーが発生します。エミュレーターを手動で起動できます。! (注: Azure Storage エミュレーターは非推奨になり、推奨される置換は Azurite です)
- Mac で Visual Studio Code を使用している場合は、Azurite を使用してください
- 作成された投影を実行しようとしたときに、Windows で次のエラー (バグです) が表示される場合。
- これは、powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine でこのコマンドを実行することで解決できます。詳細については、こちらを参照してください。

次の手順

Azure SDK の詳細については、こちらの Web サイトを参照してください

公開

こちらの手順に従って、Azure アプリケーションを作成して発行します。 https://learn.microsoft.com/azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure
発行済みの投稿エンドポイントを特定するには、作成した azure 関数エンドポイントを組み合わせ、リスナーとリスナーコードにルーティングします。リッスンコードは、azure 関数アプリケーションに移動し、[アプリキー] を選択し、AuthenticationEvents_extensionの値をコピーすることで確認できます。
例: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart"
運用環境にトークン認証用の正しいアプリケーション設定があることを確認します。
もう一度、上記のペイロードを新しいエンドポイントに投稿することで、発行された関数をテストできます。

共同作成

このリポジトリへの投稿の詳細については、投稿ガイドを参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

次の方法で共有

.NET 用Azure Functionsクライアントライブラリの認証イベントトリガー

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

Azure Functions Azure AD 認証統合を使用してトークンを検証する

トリガーでトークンを検証する

トークンの検証なし

クイックスタート

主要な概念

.NET SDK

Azure AD カスタム拡張機能

認証イベントトリガー

認証イベントによって出力バインドがトリガーされる

ドキュメント

例

トラブルシューティング

次の手順

公開

共同作成

フィードバック

フィードバック

その他のリソース

次の方法で共有

.NET 用Azure Functionsクライアント ライブラリの認証イベント トリガー

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

Azure Functions Azure AD 認証統合を使用してトークンを検証する

トリガーでトークンを検証する

トークンの検証なし

クイックスタート

主要な概念

.NET SDK

Azure AD カスタム拡張機能

認証イベント トリガー

認証イベントによって出力バインドがトリガーされる

ドキュメント

例

トラブルシューティング

次の手順

公開

共同作成

フィードバック

フィードバック

その他のリソース

.NET 用Azure Functionsクライアントライブラリの認証イベントトリガー

認証イベントトリガー