Microsoft Azure Webjobs Extensions Authentication Events Dotnet

1---
2name: microsoft-azure-webjobs-extensions-authentication-events-dotnet
3description: |
4  Microsoft Entra Authentication Events SDK for .NET. Azure Functions triggers for custom authentication extensions. Use for token enrichment, custom claims, attribute collection, and OTP customization in Entra ID. Triggers: "Authentication Events", "WebJobsAuthenticationEventsTrigger", "OnTokenIssuanceStart", "OnAttributeCollectionStart", "custom claims", "token enrichment", "Entra custom extension", "authentication extension".
5---
6 
7# Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents (.NET)
8 
9Azure Functions extension for handling Microsoft Entra ID custom authentication events.
10 
11## Installation
12 
13```bash
14dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
15```
16 
17**Current Version**: v1.1.0 (stable)
18 
19## Supported Events
20 
21| Event | Purpose |
22|-------|---------|
23| `OnTokenIssuanceStart` | Add custom claims to tokens during issuance |
24| `OnAttributeCollectionStart` | Customize attribute collection UI before display |
25| `OnAttributeCollectionSubmit` | Validate/modify attributes after user submission |
26| `OnOtpSend` | Custom OTP delivery (SMS, email, etc.) |
27 
28## Core Workflows
29 
30### 1. Token Enrichment (Add Custom Claims)
31 
32Add custom claims to access or ID tokens during sign-in.
33 
34```csharp
35using Microsoft.Azure.WebJobs;
36using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
37using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
38using Microsoft.Extensions.Logging;
39 
40public static class TokenEnrichmentFunction
41{
42    [FunctionName("OnTokenIssuanceStart")]
43    public static WebJobsAuthenticationEventResponse Run(
44        [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request,
45        ILogger log)
46    {
47        log.LogInformation("Token issuance event for user: {UserId}", 
48            request.Data?.AuthenticationContext?.User?.Id);
49 
50        // Create response with custom claims
51        var response = new WebJobsTokenIssuanceStartResponse();
52        
53        // Add claims to the token
54        response.Actions.Add(new WebJobsProvideClaimsForToken
55        {
56            Claims = new Dictionary<string, string>
57            {
58                { "customClaim1", "customValue1" },
59                { "department", "Engineering" },
60                { "costCenter", "CC-12345" },
61                { "apiVersion", "v2" }
62            }
63        });
64 
65        return response;
66    }
67}
68```
69 
70### 2. Token Enrichment with External Data
71 
72Fetch claims from external systems (databases, APIs).
73 
74```csharp
75using Microsoft.Azure.WebJobs;
76using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
77using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
78using Microsoft.Extensions.Logging;
79using System.Net.Http;
80using System.Text.Json;
81 
82public static class TokenEnrichmentWithExternalData
83{
84    private static readonly HttpClient _httpClient = new();
85 
86    [FunctionName("OnTokenIssuanceStartExternal")]
87    public static async Task<WebJobsAuthenticationEventResponse> Run(
88        [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request,
89        ILogger log)
90    {
91        string? userId = request.Data?.AuthenticationContext?.User?.Id;
92        
93        if (string.IsNullOrEmpty(userId))
94        {
95            log.LogWarning("No user ID in request");
96            return new WebJobsTokenIssuanceStartResponse();
97        }
98 
99        // Fetch user data from external API
100        var userProfile = await GetUserProfileAsync(userId);
101        
102        var response = new WebJobsTokenIssuanceStartResponse();
103        response.Actions.Add(new WebJobsProvideClaimsForToken
104        {
105            Claims = new Dictionary<string, string>
106            {
107                { "employeeId", userProfile.EmployeeId },
108                { "department", userProfile.Department },
109                { "roles", string.Join(",", userProfile.Roles) }
110            }
111        });
112 
113        return response;
114    }
115 
116    private static async Task<UserProfile> GetUserProfileAsync(string userId)
117    {
118        var response = await _httpClient.GetAsync($"https://api.example.com/users/{userId}");
119        response.EnsureSuccessStatusCode();
120        var json = await response.Content.ReadAsStringAsync();
121        return JsonSerializer.Deserialize<UserProfile>(json)!;
122    }
123}
124 
125public record UserProfile(string EmployeeId, string Department, string[] Roles);
126```
127 
128### 3. Attribute Collection - Customize UI (Start Event)
129 
130Customize the attribute collection page before it's displayed.
131 
132```csharp
133using Microsoft.Azure.WebJobs;
134using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
135using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;
136using Microsoft.Extensions.Logging;
137 
138public static class AttributeCollectionStartFunction
139{
140    [FunctionName("OnAttributeCollectionStart")]
141    public static WebJobsAuthenticationEventResponse Run(
142        [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionStartRequest request,
143        ILogger log)
144    {
145        log.LogInformation("Attribute collection start for correlation: {CorrelationId}",
146            request.Data?.AuthenticationContext?.CorrelationId);
147 
148        var response = new WebJobsAttributeCollectionStartResponse();
149 
150        // Option 1: Continue with default behavior
151        response.Actions.Add(new WebJobsContinueWithDefaultBehavior());
152 
153        // Option 2: Prefill attributes
154        // response.Actions.Add(new WebJobsSetPrefillValues
155        // {
156        //     Attributes = new Dictionary<string, string>
157        //     {
158        //         { "city", "Seattle" },
159        //         { "country", "USA" }
160        //     }
161        // });
162 
163        // Option 3: Show blocking page (prevent sign-up)
164        // response.Actions.Add(new WebJobsShowBlockPage
165        // {
166        //     Message = "Sign-up is currently disabled."
167        // });
168 
169        return response;
170    }
171}
172```
173 
174### 4. Attribute Collection - Validate Submission (Submit Event)
175 
176Validate and modify attributes after user submission.
177 
178```csharp
179using Microsoft.Azure.WebJobs;
180using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
181using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;
182using Microsoft.Extensions.Logging;
183 
184public static class AttributeCollectionSubmitFunction
185{
186    [FunctionName("OnAttributeCollectionSubmit")]
187    public static WebJobsAuthenticationEventResponse Run(
188        [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionSubmitRequest request,
189        ILogger log)
190    {
191        var response = new WebJobsAttributeCollectionSubmitResponse();
192 
193        // Access submitted attributes
194        var attributes = request.Data?.UserSignUpInfo?.Attributes;
195        
196        string? email = attributes?["email"]?.ToString();
197        string? displayName = attributes?["displayName"]?.ToString();
198 
199        // Validation example: block certain email domains
200        if (email?.EndsWith("@blocked.com") == true)
201        {
202            response.Actions.Add(new WebJobsShowBlockPage
203            {
204                Message = "Sign-up from this email domain is not allowed."
205            });
206            return response;
207        }
208 
209        // Validation example: show validation error
210        if (string.IsNullOrEmpty(displayName) || displayName.Length < 3)
211        {
212            response.Actions.Add(new WebJobsShowValidationError
213            {
214                Message = "Display name must be at least 3 characters.",
215                AttributeErrors = new Dictionary<string, string>
216                {
217                    { "displayName", "Name is too short" }
218                }
219            });
220            return response;
221        }
222 
223        // Modify attributes before saving
224        response.Actions.Add(new WebJobsModifyAttributeValues
225        {
226            Attributes = new Dictionary<string, string>
227            {
228                { "displayName", displayName.Trim() },
229                { "city", attributes?["city"]?.ToString()?.ToUpperInvariant() ?? "" }
230            }
231        });
232 
233        return response;
234    }
235}
236```
237 
238### 5. Custom OTP Delivery
239 
240Send one-time passwords via custom channels (SMS, email, push notification).
241 
242```csharp
243using Microsoft.Azure.WebJobs;
244using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;
245using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;
246using Microsoft.Extensions.Logging;
247 
248public static class CustomOtpFunction
249{
250    [FunctionName("OnOtpSend")]
251    public static async Task<WebJobsAuthenticationEventResponse> Run(
252        [WebJobsAuthenticationEventsTrigger] WebJobsOnOtpSendRequest request,
253        ILogger log)
254    {
255        var response = new WebJobsOnOtpSendResponse();
256 
257        string? phoneNumber = request.Data?.OtpContext?.Identifier;
258        string? otp = request.Data?.OtpContext?.OneTimeCode;
259 
260        if (string.IsNullOrEmpty(phoneNumber) || string.IsNullOrEmpty(otp))
261        {
262            log.LogError("Missing phone number or OTP");
263            response.Actions.Add(new WebJobsOnOtpSendFailed
264            {
265                Error = "Missing required data"
266            });
267            return response;
268        }
269 
270        try
271        {
272            // Send OTP via your SMS provider
273            await SendSmsAsync(phoneNumber, $"Your verification code is: {otp}");
274            
275            response.Actions.Add(new WebJobsOnOtpSendSuccess());
276            log.LogInformation("OTP sent successfully to {PhoneNumber}", phoneNumber);
277        }
278        catch (Exception ex)
279        {
280            log.LogError(ex, "Failed to send OTP");
281            response.Actions.Add(new WebJobsOnOtpSendFailed
282            {
283                Error = "Failed to send verification code"
284            });
285        }
286 
287        return response;
288    }
289 
290    private static async Task SendSmsAsync(string phoneNumber, string message)
291    {
292        // Implement your SMS provider integration (Twilio, Azure Communication Services, etc.)
293        await Task.CompletedTask;
294    }
295}
296```
297 
298### 6. Function App Configuration
299 
300Configure the Function App for authentication events.
301 
302```csharp
303// Program.cs (Isolated worker model)
304using Microsoft.Extensions.Hosting;
305 
306var host = new HostBuilder()
307    .ConfigureFunctionsWorkerDefaults()
308    .Build();
309 
310host.Run();
311```
312 
313```json
314// host.json
315{
316  "version": "2.0",
317  "logging": {
318    "applicationInsights": {
319      "samplingSettings": {
320        "isEnabled": true
321      }
322    }
323  },
324  "extensions": {
325    "http": {
326      "routePrefix": ""
327    }
328  }
329}
330```
331 
332```json
333// local.settings.json
334{
335  "IsEncrypted": false,
336  "Values": {
337    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
338    "FUNCTIONS_WORKER_RUNTIME": "dotnet"
339  }
340}
341```
342 
343## Key Types Reference
344 
345| Type | Purpose |
346|------|---------|
347| `WebJobsAuthenticationEventsTriggerAttribute` | Function trigger attribute |
348| `WebJobsTokenIssuanceStartRequest` | Token issuance event request |
349| `WebJobsTokenIssuanceStartResponse` | Token issuance event response |
350| `WebJobsProvideClaimsForToken` | Action to add claims |
351| `WebJobsAttributeCollectionStartRequest` | Attribute collection start request |
352| `WebJobsAttributeCollectionStartResponse` | Attribute collection start response |
353| `WebJobsAttributeCollectionSubmitRequest` | Attribute submission request |
354| `WebJobsAttributeCollectionSubmitResponse` | Attribute submission response |
355| `WebJobsSetPrefillValues` | Prefill form values |
356| `WebJobsShowBlockPage` | Block user with message |
357| `WebJobsShowValidationError` | Show validation errors |
358| `WebJobsModifyAttributeValues` | Modify submitted values |
359| `WebJobsOnOtpSendRequest` | OTP send event request |
360| `WebJobsOnOtpSendResponse` | OTP send event response |
361| `WebJobsOnOtpSendSuccess` | OTP sent successfully |
362| `WebJobsOnOtpSendFailed` | OTP send failed |
363| `WebJobsContinueWithDefaultBehavior` | Continue with default flow |
364 
365## Entra ID Configuration
366 
367After deploying your Function App, configure the custom extension in Entra ID:
368 
3691. **Register the API** in Entra ID → App registrations
3702. **Create Custom Authentication Extension** in Entra ID → External Identities → Custom authentication extensions
3713. **Link to User Flow** in Entra ID → External Identities → User flows
372 
373### Required App Registration Settings
374 
375```
376Expose an API:
377  - Application ID URI: api://<your-function-app-name>.azurewebsites.net
378  - Scope: CustomAuthenticationExtension.Receive.Payload
379 
380API Permissions:
381  - Microsoft Graph: User.Read (delegated)
382```
383 
384## Best Practices
385 
3861. **Validate all inputs** — Never trust request data; validate before processing
3872. **Handle errors gracefully** — Return appropriate error responses
3883. **Log correlation IDs** — Use `CorrelationId` for troubleshooting
3894. **Keep functions fast** — Authentication events have timeout limits
3905. **Use managed identity** — Access Azure resources securely
3916. **Cache external data** — Avoid slow lookups on every request
3927. **Test locally** — Use Azure Functions Core Tools with sample payloads
3938. **Monitor with App Insights** — Track function execution and errors
394 
395## Error Handling
396 
397```csharp
398[FunctionName("OnTokenIssuanceStart")]
399public static WebJobsAuthenticationEventResponse Run(
400    [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request,
401    ILogger log)
402{
403    try
404    {
405        // Your logic here
406        var response = new WebJobsTokenIssuanceStartResponse();
407        response.Actions.Add(new WebJobsProvideClaimsForToken
408        {
409            Claims = new Dictionary<string, string> { { "claim", "value" } }
410        });
411        return response;
412    }
413    catch (Exception ex)
414    {
415        log.LogError(ex, "Error processing token issuance event");
416        
417        // Return empty response - authentication continues without custom claims
418        // Do NOT throw - this would fail the authentication
419        return new WebJobsTokenIssuanceStartResponse();
420    }
421}
422```
423 
424## Related SDKs
425 
426| SDK | Purpose | Install |
427|-----|---------|---------|
428| `Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents` | Auth events (this SDK) | `dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents` |
429| `Microsoft.Identity.Web` | Web app authentication | `dotnet add package Microsoft.Identity.Web` |
430| `Azure.Identity` | Azure authentication | `dotnet add package Azure.Identity` |
431 
432## Reference Links
433 
434| Resource | URL |
435|----------|-----|
436| NuGet Package | https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents |
437| Custom Extensions Overview | https://learn.microsoft.com/entra/identity-platform/custom-extension-overview |
438| Token Issuance Events | https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup |
439| Attribute Collection Events | https://learn.microsoft.com/entra/identity-platform/custom-extension-attribute-collection |
440| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents |
441