From 33c583e3f5171cd153ae9df00655f93aae6c1d83 Mon Sep 17 00:00:00 2001 From: Chris Werner <59959532+cilwerner@users.noreply.github.com> Date: Mon, 8 Apr 2024 09:14:13 +0100 Subject: [PATCH 1/2] Adding tokenIssuanceStart to JSON --- ...soft.azure.webjobs.extensions.authenticationevents-readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md b/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md index c14aa0d2c228..dc628a9ed8dd 100644 --- a/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md +++ b/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md @@ -220,7 +220,7 @@ To Test Token Augmentation, please do the following. "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { - "@odata.type": "microsoft.graph.provideClaimsForToken", + "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "DateOfBirth": "01/01/2000", "CustomRoles": [ From 32f92832b3534b8953afe4f8c0a2a3d291ef0c89 Mon Sep 17 00:00:00 2001 From: Chris Werner <59959532+cilwerner@users.noreply.github.com> Date: Wed, 10 Apr 2024 09:22:02 +0100 Subject: [PATCH 2/2] Fixing warnings --- ....extensions.authenticationevents-readme.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md b/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md index dc628a9ed8dd..08018d32f3dd 100644 --- a/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md +++ b/api/overview/azure/preview/microsoft.azure.webjobs.extensions.authenticationevents-readme.md @@ -1,11 +1,13 @@ --- -title: +title: Authentication events trigger for Azure Functions client library for .NET +description: Overview of the authentication events trigger for Azure Functions client library for .NET keywords: Azure, dotnet, SDK, API, Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents, entra ms.date: 03/27/2024 ms.topic: reference ms.devlang: dotnet ms.service: entra --- + # Authentication events trigger for Azure Functions client library for .NET The authentication events trigger for Azure Functions allows you to implement a custom extension to handle Microsoft Entra authentication events. The authentication events trigger handles all the backend processing for incoming HTTP requests for Microsoft Entra authentication events and provides the developer with: @@ -30,7 +32,7 @@ dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --pre ### Authenticate the client -When the Microsoft Entra authentication events service calls your custom extension, it sends an `Authorization` header with a `Bearer {token}`. This token represents a [service to service authentication](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow) in which: +When the Microsoft Entra authentication events service calls your custom extension, it sends an `Authorization` header with a `Bearer {token}`. This token represents a [service to service authentication](/entra/identity-platform/v2-oauth2-client-creds-grant-flow) in which: * The '**resource**', also known as the **audience**, is the application that you register to represent your API. This is represented by the `aud` claim in the token. * The '**client**' is a Microsoft application that represents the Microsoft Entra authentication events service. It has an `appId` value of `99045fe1-7639-4a75-9d4a-577b6ca3810f`. This is represented by: @@ -41,7 +43,7 @@ There are three approaches to authenticating HTTP requests to your function app #### Validate tokens using Azure Functions Microsoft Entra ID authentication integration -When running your function in production, it is **highly recommended** to use the [Azure Functions Microsoft Entra ID authentication integration](https://learn.microsoft.com/azure/app-service/configure-authentication-provider-aad#-option-2-use-an-existing-registration-created-separately) for validating incoming tokens. Set the following function [application settings](https://learn.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings?tabs=portal#settings). +When running your function in production, it is **highly recommended** to use the [Azure Functions Microsoft Entra ID authentication integration](/azure/app-service/configure-authentication-provider-aad#-option-2-use-an-existing-registration-created-separately) for validating incoming tokens. Set the following function [application settings](/azure/azure-functions/functions-how-to-use-azure-function-app-settings?tabs=portal#settings). 1. Go to the "Authentication" tab in your Function App 2. Click on "Add identity provider" @@ -49,7 +51,7 @@ When running your function in production, it is **highly recommended** to use th 4. Select "Provide the details of an existing app registration" 5. Enter the `Application ID` of the app that represents your API in Microsoft Entra ID -The issuer and allowed audience depends on the [`accessTokenAcceptedVersion`](https://learn.microsoft.com/azure/active-directory/develop/access-tokens) property of your application (can be found in the "Manifest" of the application). +The issuer and allowed audience depends on the [`accessTokenAcceptedVersion`](/entra/identity-platform/access-tokens) property of your application (can be found in the "Manifest" of the application). If the `accessTokenAcceptedVersion` property is set to `2`: 6. Set the `Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" @@ -57,7 +59,7 @@ If the `accessTokenAcceptedVersion` property is set to `2`: If the `accessTokenAcceptedVersion` property is set to `1` or `null`: 6. Set the `Issuer URL to "https://sts.windows.net/{tenantId}/" -7. Set an 'Allowed Audience' to the Application ID URI (also known as`identifierUri`). It should be in the format of`api://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}` or `api://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}` if using a [custom domain name](https://learn.microsoft.com/azure/dns/dns-custom-domain#:~:text=Azure%20Function%20App%201%20Navigate%20to%20Function%20App,Custom%20domain%20text%20field%20and%20select%20Validate.%20). +7. Set an 'Allowed Audience' to the Application ID URI (also known as`identifierUri`). It should be in the format of`api://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}` or `api://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}` if using a [custom domain name](/azure/dns/dns-custom-domain#:~:text=Azure%20Function%20App%201%20Navigate%20to%20Function%20App,Custom%20domain%20text%20field%20and%20select%20Validate.%20). By default, the Authentication event trigger will validate that Azure Function authentication integration is configured and it will check that the **client** in the token is set to `99045fe1-7639-4a75-9d4a-577b6ca3810f` (via the `azp` or `appid` claims in the token). @@ -67,7 +69,7 @@ If you want to test your API against some other client that is not Microsoft Ent #### Have the trigger validate the token -In local environments or environments that aren't hosted in the Azure Function service, the trigger can do the token validation. Set the following application settings in the [local.settings.json](https://learn.microsoft.com/azure/azure-functions/functions-develop-local#local-settings-file) file: +In local environments or environments that aren't hosted in the Azure Function service, the trigger can do the token validation. Set the following application settings in the [local.settings.json](/azure/azure-functions/functions-develop-local#local-settings-file) file: * **AuthenticationEvents__TenantId** - your tenant ID * **AuthenticationEvents__AudienceAppId** - the same value as "Allowed audience" in option 1. @@ -90,7 +92,7 @@ An example `local.settings.json` file: #### No token validation -If you would like to _not_ authenticate the token while in local development, set the following application settings in the [local.settings.json](https://learn.microsoft.com/azure/azure-functions/functions-develop-local#local-settings-file) file: +If you would like to _not_ authenticate the token while in local development, set the following application settings in the [local.settings.json](/azure/azure-functions/functions-develop-local#local-settings-file) file: * **AuthenticationEvents__BypassTokenValidation** - value of `true` will make the trigger not check for a validation of the token. @@ -143,7 +145,7 @@ The authentication events trigger output binding allows a function to send authe ## Documentation -* One the function has been published, there's some good reading about logging and metrics that can be found [here](https://learn.microsoft.com/azure/azure-functions/functions-monitor-log-analytics?tabs=csharp) +* One the function has been published, there's some good reading about logging and metrics that can be found [here](/azure/azure-functions/functions-monitor-log-analytics?tabs=csharp) * For API Documentation, please see the (Link TBD) * Once this moves to preview, we except no breaking changes and would be as simple as removing the the NuGet source that points to the private preview. @@ -237,10 +239,10 @@ To Test Token Augmentation, please do the following. ## Troubleshooting * Visual Studio Code - * If running in Visual Studio Code, you get an error along the lines of the local Azure Storage Emulator is unavailable, you can start the emulator manually.! (Note: Azure Storage emulator is now deprecated and the suggested replacement is [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite?tabs=visual-studio)) - * If using Visual Studio Code on Mac please use [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite?tabs=visual-studio) + * If running in Visual Studio Code, you get an error along the lines of the local Azure Storage Emulator is unavailable, you can start the emulator manually.! (Note: Azure Storage emulator is now deprecated and the suggested replacement is [Azurite](/azure/storage/common/storage-use-azurite?tabs=visual-studio)) + * If using Visual Studio Code on Mac please use [Azurite](/azure/storage/common/storage-use-azurite?tabs=visual-studio) * If you see the following error on Windows (it's a bug) when trying to run the created projected. - * This can be resolved by executing this command in powershell `Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine` more info on this can be found [here](https://github.com/Azure/azure-functions-core-tools/issues/1821) and [here](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7) + * This can be resolved by executing this command in powershell `Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine` more info on this can be found [here](https://github.com/Azure/azure-functions-core-tools/issues/1821) and [here](/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7) ## Next steps @@ -248,7 +250,7 @@ For more information on Azure SDK, please refer to [this website](https://azure. ## Publish -* Follow the instruction here to create and publish your Azure Application. +* Follow the instruction here to [create and publish your Azure Application](/azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure). * To determine your published posting endpoint, combine the azure function endpoint you created, route to the listener and listener code, the listen code can be found by navigating to your azure function application, selecting "App Keys" and copying the value of AuthenticationEvents_extension. * For example: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart" * Make sure your production environment has the correct application settings for token authentication.