microsoft-azure-webjobs-extensions-authentication-events-dotnet について
Azure Functions で Microsoft Entra ID のカスタム認証イベントを扱う .NET 開発者向けスキルです。トークンへのクレーム追加に加え、属性収集や OTP イベントの統合手順と、リクエスト検証や SDK 確認の注意点を示します。
主な機能
- 01トークン発行イベントの処理
- 02承認済みクレームのトークン追加
- 03属性収集ワークフローの案内
- 04認証済み OTP 配信の案内
- 05リクエスト検証と失敗処理
活用シーン
- 01承認済みプロフィール情報のサイントークンへの追加
- 02ユーザー送信属性の検証
- 03設定済み OTP プロバイダーの統合
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/microsoft-azure-webjobs-extensions-authentication-events-dotnetを入力して読み込まれたか確認します。
詳細
Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents（.NET）
Microsoft Entra ID のカスタム認証イベントを処理するための Azure Functions 拡張機能です。
インストール
dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
選択した Functions ホストと互換性のある、レビュー済みのパッケージバージョンを固定してください。Microsoft のセットアップガイドでは、この NuGet 統合はプレビューとして説明されています。この例から安定性を推測しないでください。
サポート対象イベント
| イベント | 目的 |
|---|---|
OnTokenIssuanceStart | トークン発行時にカスタムクレームを追加します |
OnAttributeCollectionStart | 表示前に属性収集 UI をカスタマイズします |
OnAttributeCollectionSubmit | ユーザー送信後に属性を検証／変更します |
OnOtpSend | カスタム OTP 配信（SMS、メールなど） |
認証と応答の前提条件
公式のセットアップに従い、実際のテナント／拡張機能から AuthenticationEvents__AudienceAppId、AuthenticationEvents__AuthorityUrl、AuthenticationEvents__AuthorizedPartyAppId を設定してください。データにアクセスしたりクレームを返したりする前に、リクエストの認証／ステータスを検証してください。トリガーが呼び出されたことだけをもって、トークン／スキーマの検証が成功したとみなさないでください。SDK のドキュメントに記載された応答／エラーパターンを使って、無効なリクエストを拒否してください。Graph User.Read は、Entra コールバックの認証の代わりにはなりません。
以下の例はそれぞれ独立した断片であり、パッケージバージョン固有の名前空間、リクエスト型、System／Collections／Tasks のインポート、および必要な SDK アクションコレクションの初期化が必要です。インストール済み SDK でサポートされるイベント名／型を確認してください。ここではビルドの成立は確認されていません。クレームとロールは、認可されたテナントに紐づくソースから取得する必要があります。サンプルの Engineering／roles は合成データであり、ユーザーの権限ではありません。OTP、電話番号、トークン、生の例外ペイロードをログに記録しないでください。テナント／ユーザー／バージョンを考慮したキャッシュと、認証済みの外部呼び出しに対する上限を適用してください。必須クレームが欠落または無効な場合、依存するアプリケーションではフェイルクローズにしてください。アクセスを暗黙に許可してはいけません。
主なワークフロー
1. トークンへの情報追加（カスタムクレームの追加）
サインイン時にアクセス トークンまたは ID トークンへカスタムクレームを追加します。
using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
public static class TokenEnrichmentFunction
{
[FunctionName("OnTokenIssuanceStart")]
public static WebJobsAuthenticationEventResponse Run(
[WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request)
{
try
{
if (request.RequestStatus != WebJobsAuthenticationEventsRequestStatusType.Successful)
return request.Completed(); // SDK preserves validation failure; do not add claims.
request.Response.Actions.Add(new WebJobsProvideClaimsForToken(
new WebJobsAuthenticationEventsTokenClaim("apiVersion", "v2")));
return request.Completed();
}
catch (Exception ex)
{
return request.Failed(ex);
}
}
}
apiVersion の値は、権限を表さない合成データの例です。必須クレームは Entra 拡張機能／アプリケーションでマッピングし、依存するアプリケーションで適用する必要があります。ユーザーや例外をそのままログに記録する必要はありません。
2. 外部データを使ったトークンへの情報追加
外部システム（データベース、API）からクレームを取得します。
ユーザーのコンテキストを読み取る前に、上記の認証済みリクエストのゲートを使用してください。検証済みイベントからテナントとユーザー ID を特定し、コールバックの予算時間内のタイムアウト、応答サイズの上限、スキーマ検証を適用して、認可されたテナントに紐づくプロファイルアダプターに問い合わせます。承認済みの各値を WebJobsAuthenticationEventsTokenClaim と request.Response.Actions で追加し、その後 request.Completed() を返します。必須のプロファイルデータが欠落または無効な場合は request.Failed(exception) を返し、依存するアプリケーションではクレームがない場合に拒否するようにしてください。信頼できない入力からロール文字列を連結したり、新しい空の成功応答を返したりしないでください。プロファイルアダプター、認証、ロールマッピングはアプリケーションのコードであり、ここでは提供されていません。
3. 属性の収集と OTP の配信
これらのイベントは、テナント／製品／バージョンによって異なります。これまでの例では、未検証のリクエスト／アクションコンストラクターと何もしない SMS アダプターを想定していました。これらを、コンパイル可能な SDK 連携の例としてコピーしてはいけません。インストール済みパッケージの公式イベント別サンプルを使用し、属性や OTP コンテキストにアクセスする前に、リクエストの認証／ステータスゲートを確認してください。
- 開始：承認済みの属性のみを事前入力してください。クライアントから提供された ID を信頼したり、事前入力を認可判断に使用したりしてはいけません。
- 送信：イベントのスキーマ全体と許可される属性フィールドを検証し、イベントで文書化されている検証／ブロックアクションを返すとともに、ユーザーが入力を修正できるようにしてください。表示メッセージだけではポリシーを強制できません。
- OTP：認証済みの設定済みプロバイダーを通じてのみ配信し、宛先とチャレンジコンテキストを検証し、試行回数とタイムアウトに上限を設け、プロバイダーが受け付けた後にのみ成功を報告してください。OTP 値をログに記録または永続化したり、Task.CompletedTask から配信済みと偽って報告したりしてはいけません。
- ローカルでは合成フィクスチャを使用してください。AuthenticationEvents__BypassTokenValidation は、デプロイするすべての環境で無効にしてください。ローカルのバイパステストでは、本番環境の認証を検証できません。
主な型のリファレンス
検証済みのトークン発行パターンでは、WebJobsTokenIssuanceStartRequest、WebJobsAuthenticationEventsRequestStatusType、WebJobsProvideClaimsForToken、WebJobsAuthenticationEventsTokenClaim を、request.Response、request.Completed()、request.Failed(exception) を通じて使用します。イベントラベルから推測するのではなく、それ以外のイベント固有の名前はすべてインストール済みパッケージで確認してください。
Entra ID の構成
Function App のデプロイ後、Entra ID でカスタム拡張機能を構成します。
- Entra ID → アプリの登録で API を登録 します
- Entra ID → 外部 ID → カスタム認証拡張機能で カスタム認証拡張機能を作成 します
- Entra ID → 外部 ID → ユーザーフローで ユーザーフローにリンク します
必須のアプリ登録設定
Expose an API:
- Application ID URI: api://<your-function-app-name>.azurewebsites.net
- Scope: CustomAuthenticationExtension.Receive.Payload
API Permissions:
- Microsoft Graph: User.Read (delegated)
ベストプラクティス
- すべての入力を検証する — リクエストデータを決して信頼せず、処理前に検証してください
- エラーを適切に処理する — 適切なエラーレスポンスを返してください
- 相関 ID を記録する — トラブルシューティングには
CorrelationIdを使用してください - 関数を高速に保つ — 認証イベントにはタイムアウト制限があります
- マネージド ID を使用する — Azure リソースに安全にアクセスしてください
- 外部データをキャッシュする — リクエストごとの低速な検索を避けてください
- ローカルでテストする — Azure Functions Core Tools とサンプルペイロードを使用してください
- App Insights で監視する — 関数の実行状況とエラーを追跡してください
エラー処理
上記の、ガード処理を備えたトークン発行関数を使用してください。SDK の検証ステータスを維持し、Successful リクエストに対してのみ request.Response を設定し、処理に失敗した場合は request.Failed(exception) を使用してください。失敗を new WebJobsTokenIssuanceStartResponse() で置き換えたり、コールバックや例外の生のペイロードを記録したりしてはいけません。
関連 SDK
| SDK | 用途 | インストール |
|---|---|---|
Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents | 認証イベント（この SDK） | dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents |
Microsoft.Identity.Web | Web アプリの認証 | dotnet add package Microsoft.Identity.Web |
Azure.Identity | Azure 認証 | dotnet add package Azure.Identity |
参照リンク
使用する場合
このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。
制限事項
- このスキルは、タスクが上記の説明範囲に明確に該当する場合にのみ使用してください。
- 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
- 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、いったん停止して確認を求めてください。
検証済みのトークン発行 API の形式：Microsoft のセットアップガイド。その他のイベントワークフローは、コンパイルされた実装ではなく、手順に基づく統合要件です。