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

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

Azure Functionsの認証イベントトリガーは、認証イベントの受信 Http 要求に対するすべてのバックエンド処理 (トークン/json スキーマ検証など) を処理します。また、厳密に型指定されたバージョン管理されたオブジェクトモデルを開発者が操作できるようにします。つまり、開発者は要求と応答の json ペイロードに関する事前知識を持っている必要はありません。

このプロジェクトフレームワークには、次の機能が用意されています。

API 呼び出しをセキュリティで保護するためのトークン検証
オブジェクトモデル、型指定、IDE IntelliSense
API 要求スキーマと応答スキーマの受信と送信の検証
バージョン管理
定型コードは必要ありません。

作業の開始

npm パッケージのインストール

npm install @azure/functions-authentication-events

前提条件

Azure 関数ツール
Azure Function Core Tools
Visual Studio Code を使用する場合は、次の拡張機能を使用します。
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

クライアントを認証する

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

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

トークンを処理するには、3 つの方法があります。動作は、次に示すようにアプリケーション設定を使用するか、ローカル環境の local.settings.json ファイルを使用してカスタマイズできます。

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 サービスでホストされていないローカル環境または環境では、トリガーでトークンの検証を実行できます。次のアプリケーション設定を設定します。

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"
  }
}

トークンの検証なし

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

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

クイックスタート

Visual Studio Code
- Visual Studio Code を開始します
- コマンドパレットを使用してターミナルコマンド func init . --worker-runtime node を実行する
- コマンドパレットを使用してターミナルコマンド func new を実行する
- プロジェクトの作成プロンプトに従う
- コマンドパレットを使用してターミナルコマンド npm install @azure/functions-authentication-events を実行する
- コマンドパレットを使用してターミナルコマンド npm install を実行する
- コマンドパレットを使用してターミナルコマンド npm run-script build を実行する
テスト用のトークン検証の開発目的のターン:
AuthenticationEvents__BypassTokenValidation アプリケーションキーを local.settings.json ファイルの "Values" セクションに追加し、その値を true に設定します。ローカル環境に local.settings.json ファイルがない場合は、関数アプリのルートに作成します。

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

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

主要な概念

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

ドキュメント

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

例

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

前の手順で作成したプロジェクトを開きます。 (クイックスタート)
アプリケーションを実行します。 func host start
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/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}

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

{
    "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 アプリケーションを作成して発行します。 </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 宛てに質問またはコメントをお送りください。

次の方法で共有

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

作業の開始

npm パッケージのインストール

前提条件

クライアントを認証する

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

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

トークンの検証なし

クイックスタート

主要な概念

ドキュメント

例

トラブルシューティング

次の手順

公開

共同作成

その他のリソース

次の方法で共有

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

作業の開始

npm パッケージのインストール

前提条件

クライアントを認証する

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

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

トークンの検証なし

クイックスタート

主要な概念

ドキュメント

例

トラブルシューティング

次の手順

公開

共同作成

その他のリソース

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