From 9782bf9d116016bebe5988e563e514e652923727 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Tue, 21 May 2024 14:22:06 -0700 Subject: [PATCH 01/14] Updated readme --- .../README.md | 184 ++---------------- 1 file changed, 14 insertions(+), 170 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 6caf6bbdc057a..7eee19e228c19 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -18,7 +18,7 @@ dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents ### Prerequisites -- **Azure Subscription:** To use Azure services, including Azure Functions, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://account.windowsazure.com/Home/Index). +- **Azure Subscription:** To use Azure services, including Azure Functions, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you create an account. ### Authenticate the client @@ -29,56 +29,7 @@ When the Microsoft Entra authentication events service calls your custom extensi * The `azp` claim in the token if your application `accessTokenAcceptedVersion` property is set to `2`. * The `appid` claim in the token if your resource application's `accessTokenAcceptedVersion` property is set to `1` or `null`. -There are three approaches to authenticating HTTP requests to your function app and validating the token. - -#### 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). - -1. Go to the "Authentication" tab in your Function App -2. Click on "Add identity provider" -3. Select "Microsoft" as the identity provider -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). - -If the `accessTokenAcceptedVersion` property is set to `2`: -6. Set the `Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" -7. Set an 'Allowed Audience' to the Application ID (`appId`) - -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). - -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). - -If you want to test your API against some other client that is not Microsoft Entra authentication events service, like using Postman, you can configure an _optional_ application setting: - -* **AuthenticationEvents__CustomCallerAppId** - the guid of your desired client. If not provided, `99045fe1-7639-4a75-9d4a-577b6ca3810f` is assumed. - -#### 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: - -* **AuthenticationEvents__TenantId** - your tenant ID -* **AuthenticationEvents__AudienceAppId** - the same value as "Allowed audience" in option 1. -* **AuthenticationEvents__CustomCallerAppId** (_optional_) - the guid of your desired client. If not provided, `99045fe1-7639-4a75-9d4a-577b6ca3810f` is assumed. - -An example `local.settings.json` file: - -```json -{ - "IsEncrypted": false, - "Values": { - "AzureWebJobsStorage": "UseDevelopmentStorage=true", - "FUNCTIONS_WORKER_RUNTIME": "dotnet", - "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8", - "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038", - "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038" - } -} -``` +There are different approaches to authenticating HTTP requests to your function app and validating the token which can be found [here](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#configure-authentication-for-your-azure-function). #### No token validation @@ -88,32 +39,7 @@ If you would like to _not_ authenticate the token while in local development, se ### Quickstart -* Visual Studio 2019 - * Start Visual Studio - * Select "Create a new project" - * In the template search area search and select "AzureAuthEventsTrigger" - * Give your project a meaningful Project Name, Location, Solution and Solution Name. - -* Visual Studio Code - * Start Visual Studio Code - * Run the command "Create Azure Authentication Events Trigger Project" via the command palette - * Follow the project creation prompts -* Please note: that on a first time run it might take awhile to download the the required packages. -* For development purpose turn of token validation for testing: -* Add the **AuthenticationEvents__BypassTokenValidation** application key to the "Values" section in the local.settings.json file and set it's value to **true**. If you do not have a local.settings.json file in your local environment, create one in the root of your Function App. - -```json -{ - "IsEncrypted": false, - "Values": { - "AzureWebJobsStorage": "UseDevelopmentStorage=true", - "FUNCTIONS_WORKER_RUNTIME": "dotnet", - "AuthenticationEvents__BypassTokenValidation": true - } -} -``` - -* Once the project is loaded, you can run the sample code and you should see the Azure functions developer's application load your end point. +You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) ## Key concepts @@ -135,116 +61,34 @@ 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) - -* For API Documentation, please see the (Link TBD) +* Once 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) * 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. ## Examples To Test Token Augmentation, please do the following. -* Start Visual Studio. * Open the project that was created in the prior step. (QuickStart) -* Run the Application. (F5) -* Once the Azure functions developer's application has started, copy the listening url that is displayed with the application starts up. -* Note: All Authentication functions are listed, in the case we have one function listener registered called "**OnTokenIssuanceStart**" -* Your function endpoint will then be a combination of the listening url and function, for example: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)&function=OnTokenIssuanceStart" -* Post the following payload using something like Postman or Fiddler. -* Steps for using Postman can be found (Link TBD) - -```json -{ - "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" - } - } - } -} -``` - -* You should see this response: - -```json -{ - "data": { - "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", - "actions": [ - { - "@odata.type": "microsoft.graph.provideClaimsForToken", - "claims": { - "DateOfBirth": "01/01/2000", - "CustomRoles": [ - "Writer", - "Editor" - ] - } - } - ] - } -} -``` +* Follow [these](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) steps to test your app locally. ## 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 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 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) - -## Next steps - -For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Publish -* Follow the instruction here to create and publish your Azure Application. +* Follow the instruction [here](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#deploy-the-function-and-publish-to-azure) to create and publish your Azure Application. * 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" + * 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. -* Once again you can test the published function by posting the above payload to the new endpoint. + +## Next steps + +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) + +[Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration?tabs=azure-portal%2Cworkforce-tenant) ## Contributing From 95641847ba70503225fcd029ee172cf6cf34a830 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Tue, 21 May 2024 15:31:24 -0700 Subject: [PATCH 02/14] Updated changelog.md --- .../CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md index 7946f3003ad07..42a98fd834f71 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md @@ -4,6 +4,7 @@ ### Other Changes - Removed '--prerelease' from README.md +- Updated README.md to reflect the latest changes ## 1.0.0-beta.8 (2024-05-01) From 4baca3e919d29e8f0d24f801715a9ed84f9edf53 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Tue, 21 May 2024 16:24:25 -0700 Subject: [PATCH 03/14] feedback changes and updated links --- .../README.md | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 7eee19e228c19..3bb7711f8cb59 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -22,14 +22,14 @@ dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents ### 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](https://learn.microsoft.com/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: * The `azp` claim in the token if your application `accessTokenAcceptedVersion` property is set to `2`. * The `appid` claim in the token if your resource application's `accessTokenAcceptedVersion` property is set to `1` or `null`. -There are different approaches to authenticating HTTP requests to your function app and validating the token which can be found [here](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#configure-authentication-for-your-azure-function). +There are different approaches to authenticating HTTP requests to your function app and validating the token which can be found [here](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#configure-authentication-for-your-azure-function). #### No token validation @@ -37,9 +37,9 @@ If you would like to _not_ authenticate the token while in local development, se * **AuthenticationEvents__BypassTokenValidation** - value of `true` will make the trigger not check for a validation of the token. -### Quickstart +### How to get started -You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) +You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) ## Key concepts @@ -59,17 +59,12 @@ The authentication events trigger allows a function to be executed when an authe The authentication events trigger output binding allows a function to send authentication event actions to the Microsoft Entra event service. -## Documentation - -* Once 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) -* 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. - ## Examples To Test Token Augmentation, please do the following. -* Open the project that was created in the prior step. (QuickStart) -* Follow [these](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) steps to test your app locally. +* Open the project that was created in the prior step. (How to get started) +* Follow [these](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) steps to test your app locally. ## Troubleshooting @@ -79,7 +74,7 @@ To Test Token Augmentation, please do the following. ## Publish -* Follow the instruction [here](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#deploy-the-function-and-publish-to-azure) to create and publish your Azure Application. +* Follow the instruction [here](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#deploy-the-function-and-publish-to-azure) to create and publish your Azure Application. * 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. @@ -88,7 +83,9 @@ To Test Token Augmentation, please do the following. For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) -[Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration?tabs=azure-portal%2Cworkforce-tenant) +Information about logging and metrics for the deployed function can be found [here](https://learn.microsoft.com/azure/azure-functions/monitor-functions?tabs=portal) + +[Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration?tabs=azure-portal%2Cworkforce-tenant) ## Contributing From 161ce349dec1bb2a22c937996899af72716714e1 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 22 May 2024 14:05:21 -0700 Subject: [PATCH 04/14] Updated links and feedback suggestions --- .../README.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 3bb7711f8cb59..67f93f375518b 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -10,7 +10,7 @@ The authentication events trigger for Azure Functions allows you to implement a ### Install the package -Install the authentication events trigger for Azure Functions with [NuGet](https://www.nuget.org/): +Install the authentication events trigger for Azure Functions with [NuGet](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/): ```dotnetcli dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents @@ -18,7 +18,7 @@ dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents ### Prerequisites -- **Azure Subscription:** To use Azure services, including Azure Functions, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you create an account. +- **Azure Subscription:** To use Azure services, including Azure Functions, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://azure.microsoft.com/account). ### Authenticate the client @@ -31,7 +31,7 @@ When the Microsoft Entra authentication events service calls your custom extensi There are different approaches to authenticating HTTP requests to your function app and validating the token which can be found [here](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#configure-authentication-for-your-azure-function). -#### No token validation +#### Bypass 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: @@ -61,31 +61,30 @@ The authentication events trigger output binding allows a function to send authe ## Examples -To Test Token Augmentation, please do the following. +To test token augmentation, please do the following. -* Open the project that was created in the prior step. (How to get started) -* Follow [these](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) steps to test your app locally. +* Open the project that was created in the prior step. [How to get started](#How-to-get-started) +* Follow [these steps](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) to test your app locally. ## Troubleshooting -* Visual Studio Code +### 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) -## Publish +### Azure function endpoint -* Follow the instruction [here](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#deploy-the-function-and-publish-to-azure) to create and publish your Azure Application. * 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. ## Next steps +Follow [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration?tabs=azure-portal%2Cworkforce-tenant) to create a custom extension that will call your function. + For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) Information about logging and metrics for the deployed function can be found [here](https://learn.microsoft.com/azure/azure-functions/monitor-functions?tabs=portal) -[Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration?tabs=azure-portal%2Cworkforce-tenant) ## Contributing From 01cf6a63372d5d0ef0d02e0ad7134ead59d4a8e9 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 22 May 2024 16:49:25 -0700 Subject: [PATCH 05/14] Updated version and lowercase ref link --- .../CHANGELOG.md | 6 +++++- .../README.md | 2 +- ...oft.Azure.WebJobs.Extensions.AuthenticationEvents.csproj | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md index 42a98fd834f71..0500e08a7b7d3 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md @@ -1,10 +1,14 @@ # Release History +## 1.0.1 (2024-05-22) + +### Other Changes +- Updated README.md to reflect the latest changes + ## 1.0.0 (2024-05-15) ### Other Changes - Removed '--prerelease' from README.md -- Updated README.md to reflect the latest changes ## 1.0.0-beta.8 (2024-05-01) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 67f93f375518b..ca4a6f59a9a28 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -63,7 +63,7 @@ The authentication events trigger output binding allows a function to send authe To test token augmentation, please do the following. -* Open the project that was created in the prior step. [How to get started](#How-to-get-started) +* Open the project that was created in the prior step. [How to get started](#how-to-get-started) * Follow [these steps](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) to test your app locally. ## Troubleshooting diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/src/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.csproj b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/src/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.csproj index e634c3a9d3714..47299e92932aa 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/src/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.csproj +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/src/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.csproj @@ -2,7 +2,7 @@ $(RequiredTargetFrameworks) true - 1.0.0 + 1.0.1 Triggers for Azure AD Authentication event custom extensions. Lets you focus on your business logic. From 08a59df9d53ed76f2f03a76a730e6357aab60ee8 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Thu, 23 May 2024 12:19:34 -0700 Subject: [PATCH 06/14] Feedback changes --- .../README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index ca4a6f59a9a28..7a0d82ad547ab 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -35,7 +35,17 @@ There are different approaches to authenticating HTTP requests to your function 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: -* **AuthenticationEvents__BypassTokenValidation** - value of `true` will make the trigger not check for a validation of the token. +```json +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "", + "AzureWebJobsSecretStorageType": "files", + "FUNCTIONS_WORKER_RUNTIME": "dotnet", + "AuthenticationEvents__BypassTokenValidation" : true + } +} +``` ### How to get started @@ -68,7 +78,7 @@ To test token augmentation, please do the following. ## Troubleshooting -### Visual studio code +### 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) @@ -106,6 +116,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact with any additional questions or comments. +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fentra%2FMicrosoft.Azure.WebJobs.Extensions.AuthenticationEvents%2FREADME.png) + [cg]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/resourcemanager/Azure.ResourceManager/docs/CONTRIBUTING.md [coc]: https://opensource.microsoft.com/codeofconduct/ From e674adfba9dc028346080863804141432061ee10 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 19 Jun 2024 14:52:46 -0700 Subject: [PATCH 07/14] Copied learn documentation to readme --- .../README.md | 297 +++++++++++++++++- 1 file changed, 281 insertions(+), 16 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 7a0d82ad547ab..a1ec8fb8dff4e 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -8,32 +8,146 @@ The authentication events trigger for Azure Functions allows you to implement a ## Getting started -### Install the package +You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) + +### Prerequisites + +- A basic understanding of the concepts covered in [Custom authentication extensions overview](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-overview). +- An Azure subscription with the ability to create Azure Functions. If you don't have an existing Azure account, sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://account.windowsazure.com/Home/Index). +- A Microsoft Entra ID tenant. You can use either a customer or workforce tenant for this how-to guide. +- One of the following IDEs and configurations: + - Visual Studio with [Azure Development workload for Visual Studio](https://learn.microsoft.com/en-us/dotnet/azure/configure-visual-studio) configured. + - Visual Studio Code, with the [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension enabled. + +## Create and build the Azure Function app + +In this step, you create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code. You build the project and run the function to extract the local function URL. + +### Create the application + +To create an Azure Function app, follow these steps: + +### [Visual Studio](#tab/visual-studio) + +1. Open Visual Studio, and select **Create a new project**. +2. Search for and select **Azure Functions**, then select **Next**. +3. Give the project a name, such as *AuthEventsTrigger*. It's a good idea to match the solution name with the project name. +4. Select a location for the project. Select **Next**. +5. Select **.NET 6.0 (Long Term Support)** as the target framework. +6. Select *Http trigger* as the **Function** type, and that **Authorization level** is set to *Function*. Select **Create**. +7. In the **Solution Explorer**, rename the *Function1.cs* file to *AuthEventsTrigger.cs*, and accept the rename change suggestion. + +### [Visual Studio Code](#tab/visual-studio-code) + +1. Open Visual Studio Code. +2. Select the **New Folder** icon in the **Explorer** window, and create a new folder for your project, for example *AuthEventsTrigger*. +3. Select the Azure extension icon on the left-hand side of the screen. Sign in to your Azure account if you haven't already. +4. Under the **Workspace** bar, select the **Azure Functions** icon > **Create New Project**. +5. In the top bar, select the location to create the project. +6. Select **C#** as the language, and **.NET 6.0 LTS** as the .NET runtime. +7. Select **HTTP trigger** as the template. +8. Provide a name for the project, such as *AuthEventsTrigger*. +9. Accept **Company.Function** as the namespace, with **AccessRights** set to *Function*. + +--- + +### Install NuGet packages and build the project + +After creating the project, you'll need to install the required NuGet packages and build the project. + +### [Visual Studio](#tab/visual-studio) -Install the authentication events trigger for Azure Functions with [NuGet](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/): +1. In the top menu of Visual Studio, select **Project**, then **Manage NuGet packages**. +2. Select the **Browse** tab, then search for and select *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* in the right pane. Select **Install**. +3. Apply and accept the changes in the popups that appear. -```dotnetcli +### [Visual Studio Code](#tab/visual-studio-code) + +1. Open the **Terminal** in Visual Studio Code, and navigate to the project folder. +2. Enter the following command into the console to install the *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* NuGet package. + +```console dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents ``` -### Prerequisites +--- + +### Add the sample code + +The function API is the source of extra claims for your token. For the purposes of this article, we're hardcoding the values for the sample app. In production, you can fetch information about the user from external data store. + +In your *AuthEventsTrigger.cs* file, replace the entire contents of the file with the following code: + +```cs +using System; +using Microsoft.Azure.WebJobs; +using Microsoft.Extensions.Logging; +using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart; +using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents; + +namespace AuthEventsTrigger +{ + public static class AuthEventsTrigger + { + [FunctionName("onTokenIssuanceStart")] + public static WebJobsAuthenticationEventResponse Run( + [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) + { + try + { + // Checks if the request is successful and did the token validation pass + if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) + { + // Fetches information about the user from external data store + // Add new claims to the token's response + request.Response.Actions.Add( + new WebJobsProvideClaimsForToken( + new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), + new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), + new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), + new WebJobsAuthenticationEventsTokenClaim( + "correlationId", + request.Data.AuthenticationContext.CorrelationId.ToString()))); + } + else + { + // If the request fails, such as in token validation, output the failed request status, + // such as in token validation or response validation. + log.LogInformation(request.StatusMessage); + } + return request.Completed(); + } + catch (Exception ex) + { + return request.Failed(ex); + } + } + } +} +``` + +### Build and run the project locally -- **Azure Subscription:** To use Azure services, including Azure Functions, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://azure.microsoft.com/account). +The project has been created, and the sample code has been added. Using your IDE, we need to build and run the project locally to extract the local function URL. -### Authenticate the client +### [Visual Studio](#tab/visual-studio) -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/entra/identity-platform/v2-oauth2-client-creds-grant-flow) in which: +1. Navigate to **Build** in the top menu, and select **Build Solution**. +2. Press **F5** or select *AuthEventsTrigger* from the top menu to run the function. +3. Copy the **Function url** from the terminal that popups up when running the function. This can be used when setting up a custom authentication extension. -* 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: - * The `azp` claim in the token if your application `accessTokenAcceptedVersion` property is set to `2`. - * The `appid` claim in the token if your resource application's `accessTokenAcceptedVersion` property is set to `1` or `null`. +### [Visual Studio Code](#tab/visual-studio-code) -There are different approaches to authenticating HTTP requests to your function app and validating the token which can be found [here](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#configure-authentication-for-your-azure-function). +1. In the top menu, select **Run** > **Start Debugging** or press **F5** to run the function. +2. In the terminal, copy the **Function url** that appears. This can be used when setting up a custom authentication extension. -#### Bypass 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: +## Run the function locally (recommended) + +It's a good idea to test the function locally before deploying it to Azure. We can use a dummy JSON body that imitates the request that Microsoft Entra ID sends to your REST API. Use your preferred API testing tool to call the function directly. + +1. In your IDE, open *local.settings.json* and replace the code with the following JSON. We can set `"AuthenticationEvents__BypassTokenValidation"` to `true` for local testing purposes. ```json { @@ -47,9 +161,160 @@ If you would like to _not_ authenticate the token while in local development, se } ``` -### How to get started +2. Using your preferred API testing tool, create a new HTTP request and set the **HTTP method** to `POST`. +3. Use the following JSON body that imitates the request Microsoft Entra ID sends to your REST API. -You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) +```json +{ + "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart", + "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444", + "data": { + "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData", + "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", + "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555", + "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666", + "authenticationContext": { + "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd", + "client": { + "ip": "127.0.0.1", + "locale": "en-us", + "market": "en-us" + }, + "protocol": "OAUTH2.0", + "clientServicePrincipal": { + "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", + "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "appDisplayName": "My Test application", + "displayName": "My Test application" + }, + "resourceServicePrincipal": { + "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", + "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "appDisplayName": "My Test application", + "displayName": "My Test application" + }, + "user": { + "companyName": "Casey Jensen", + "createdDateTime": "2023-08-16T00:00:00Z", + "displayName": "Casey Jensen", + "givenName": "Casey", + "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", + "mail": "casey@contoso.com", + "onPremisesSamAccountName": "Casey Jensen", + "onPremisesSecurityIdentifier": "", + "onPremisesUserPrincipalName": "Casey Jensen", + "preferredLanguage": "en-us", + "surname": "Jensen", + "userPrincipalName": "casey@contoso.com", + "userType": "Member" + } + } + } +} +``` + +4. Select **Send**, and you should receive a JSON response similar to the following: + +```json +{ + "data": { + "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", + "actions": [ + { + "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", + "claims": { + "customClaim1": "customClaimValue1", + "customClaim2": [ + "customClaimString1", + "customClaimString2" + ] + } + } + ] + } +} +``` + +## Deploy the function and publish to Azure + +The function needs to be deployed to Azure using our IDE. Check that you're correctly signed in to your Azure account so the function can be published. + +### [Visual Studio](#tab/visual-studio) + +1. In the Solution Explorer, right-click on the project and select **Publish**. +1. In **Target**, select **Azure**, then select **Next**. +1. Select **Azure Function App (Windows)** for the **Specific Target**, select **Azure Function App (Windows)**, then select **Next**. +1. In the **Function instance**, use the **Subscription name** dropdown to select the subscription under which the new function app will be created in. +1. Select where you want to publish the new function app, and select **Create New**. +1. On the **Function App (Windows)** page, use the function app settings as specified in the following table, then select **Create**. + + | Setting | Suggested value | Description | + | ------------ | ---------------- | ----------- | + | **Name** | Globally unique name | A name that identifies the new function app. Valid characters are `a-z` (case insensitive), `0-9`, and `-`. | + | **Subscription** | Your subscription | The subscription under which the new function app is created. | + | **[Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview)** | *myResourceGroup* | Select an existing resource group, or name the new one in which you'll create your function app. | + | **Plan type** | Consumption (Serverless) | Hosting plan that defines how resources are allocated to your function app. | + | **Location** | Preferred region | Select a [region](https://azure.microsoft.com/regions/) that's near you or near other services that your functions can access. | + | **Azure Storage** | Your storage account | An Azure storage account is required by the Functions runtime. Select New to configure a general-purpose storage account. | + | **Application Insights** | *Default* | A feature of Azure Monitor. This is autoselected, select the one you wish to use or configure a new one. | + + +2. Wait a few moments for your function app to be deployed. Once the window closes, select **Finish**. +3. A new **Publish** pane opens. At the top, select **Publish**. Wait a few minutes for your function app to be deployed and show up in the Azure portal. + +### [Visual Studio Code](#tab/visual-studio-code) + +1. Select the **Azure** extension icon. In **Resources**, select the **+** icon to **Create a resource**. +1. Select **Create Function App in Azure**. Use the following settings for setting up your function app. +1. Give the function app a name, such as *AuthEventsTriggerNuGet*, and press **Enter**. +1. Select the **.NET 6 (LTS) In-Process** runtime stack. +1. Select a location for the function app, such as *East US*. +1. Wait a few minutes for your function app to be deployed and show up in the Azure portal. + +--- + +## Configure authentication for your Azure Function + +There are three ways to set up authentication for your Azure Function: + +- [Set up authentication in the Azure portal using environment variables](#set-up-authentication-in-the-azure-portal-using-environment-variables) (recommended) +- [Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute`](#set-up-authentication-in-your-code-using-webjobsauthenticationeventstriggerattribute) +- [Azure App service authentication and authorization](https://learn.microsoft.com/en-us/azure/app-service/configure-authentication-provider-aad?tabs=workforce-tenant) + +By default, the code has been set up for authentication in the Azure portal using environment variables. Use the tabs below to select your preferred method of implementing environment variables, or alternatively, refer to the built-in [Azure App service authentication and authorization](https://learn.microsoft.com/en-us/azure/app-service/overview-authentication-authorization). For setting up environment variables, use the following values: + + | Name | Value | + | ---- | ----- | + | *AuthenticationEvents__AudienceAppId* | *Custom authentication extension app ID* which is set up in [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration) | + | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | + | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | + +### [Set up authentication in Azure portal](#tab/azure-portal) + +### Set up authentication in the Azure portal using environment variables + +1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). +2. Navigate to the function app you created, and under **Settings**, select **Configuration**. +3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. +4. Select **Save** to save the application settings. + +### [Set up authentication in your code](#tab/nuget-library) + +### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` + +1. Open the *AuthEventsTrigger.cs* file in your IDE. +1. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. + +```cs + [FunctionName("onTokenIssuanceStart")] + public static WebJobsAuthenticationEventResponse Run( + [WebJobsAuthenticationEventsTriggerAttribute( + AudienceAppId = "Enter custom authentication extension app ID here", + AuthorityUrl = "Enter authority URI here", + AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) +``` + +--- ## Key concepts From 31249c3faaaace6efdceacadb7930f094ee26b52 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 19 Jun 2024 15:54:48 -0700 Subject: [PATCH 08/14] Added required titles to readme --- .../README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index a1ec8fb8dff4e..ff14c54a24cb4 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -51,7 +51,7 @@ To create an Azure Function app, follow these steps: --- -### Install NuGet packages and build the project +### Install NuGet packages and build the project (Install the package) After creating the project, you'll need to install the required NuGet packages and build the project. @@ -273,7 +273,7 @@ The function needs to be deployed to Azure using our IDE. Check that you're corr --- -## Configure authentication for your Azure Function +## Configure authentication for your Azure Function (Authenticate the client) There are three ways to set up authentication for your Azure Function: From 104b9ce16d78c7ba302e5d81ea0148d708f6471f Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 19 Jun 2024 16:16:30 -0700 Subject: [PATCH 09/14] Updated structure --- .../README.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index ff14c54a24cb4..77234cd7e6ad2 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -19,7 +19,7 @@ You can follow this article to start creating your function: [Create a REST API - Visual Studio with [Azure Development workload for Visual Studio](https://learn.microsoft.com/en-us/dotnet/azure/configure-visual-studio) configured. - Visual Studio Code, with the [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension enabled. -## Create and build the Azure Function app +### Create and build the Azure Function app In this step, you create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code. You build the project and run the function to extract the local function URL. @@ -27,7 +27,7 @@ In this step, you create an HTTP trigger function API using your IDE, install th To create an Azure Function app, follow these steps: -### [Visual Studio](#tab/visual-studio) +#### [Visual Studio](#tab/visual-studio) 1. Open Visual Studio, and select **Create a new project**. 2. Search for and select **Azure Functions**, then select **Next**. @@ -37,7 +37,7 @@ To create an Azure Function app, follow these steps: 6. Select *Http trigger* as the **Function** type, and that **Authorization level** is set to *Function*. Select **Create**. 7. In the **Solution Explorer**, rename the *Function1.cs* file to *AuthEventsTrigger.cs*, and accept the rename change suggestion. -### [Visual Studio Code](#tab/visual-studio-code) +#### [Visual Studio Code](#tab/visual-studio-code) 1. Open Visual Studio Code. 2. Select the **New Folder** icon in the **Explorer** window, and create a new folder for your project, for example *AuthEventsTrigger*. @@ -51,17 +51,17 @@ To create an Azure Function app, follow these steps: --- -### Install NuGet packages and build the project (Install the package) +### Install the package After creating the project, you'll need to install the required NuGet packages and build the project. -### [Visual Studio](#tab/visual-studio) +#### [Visual Studio](#tab/visual-studio) 1. In the top menu of Visual Studio, select **Project**, then **Manage NuGet packages**. 2. Select the **Browse** tab, then search for and select *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* in the right pane. Select **Install**. 3. Apply and accept the changes in the popups that appear. -### [Visual Studio Code](#tab/visual-studio-code) +#### [Visual Studio Code](#tab/visual-studio-code) 1. Open the **Terminal** in Visual Studio Code, and navigate to the project folder. 2. Enter the following command into the console to install the *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* NuGet package. @@ -130,20 +130,20 @@ namespace AuthEventsTrigger The project has been created, and the sample code has been added. Using your IDE, we need to build and run the project locally to extract the local function URL. -### [Visual Studio](#tab/visual-studio) +#### [Visual Studio](#tab/visual-studio) 1. Navigate to **Build** in the top menu, and select **Build Solution**. 2. Press **F5** or select *AuthEventsTrigger* from the top menu to run the function. 3. Copy the **Function url** from the terminal that popups up when running the function. This can be used when setting up a custom authentication extension. -### [Visual Studio Code](#tab/visual-studio-code) +#### [Visual Studio Code](#tab/visual-studio-code) 1. In the top menu, select **Run** > **Start Debugging** or press **F5** to run the function. 2. In the terminal, copy the **Function url** that appears. This can be used when setting up a custom authentication extension. --- -## Run the function locally (recommended) +### Run the function locally (recommended) It's a good idea to test the function locally before deploying it to Azure. We can use a dummy JSON body that imitates the request that Microsoft Entra ID sends to your REST API. Use your preferred API testing tool to call the function directly. @@ -235,11 +235,11 @@ It's a good idea to test the function locally before deploying it to Azure. We c } ``` -## Deploy the function and publish to Azure +### Deploy the function and publish to Azure The function needs to be deployed to Azure using our IDE. Check that you're correctly signed in to your Azure account so the function can be published. -### [Visual Studio](#tab/visual-studio) +#### [Visual Studio](#tab/visual-studio) 1. In the Solution Explorer, right-click on the project and select **Publish**. 1. In **Target**, select **Azure**, then select **Next**. @@ -262,7 +262,7 @@ The function needs to be deployed to Azure using our IDE. Check that you're corr 2. Wait a few moments for your function app to be deployed. Once the window closes, select **Finish**. 3. A new **Publish** pane opens. At the top, select **Publish**. Wait a few minutes for your function app to be deployed and show up in the Azure portal. -### [Visual Studio Code](#tab/visual-studio-code) +#### [Visual Studio Code](#tab/visual-studio-code) 1. Select the **Azure** extension icon. In **Resources**, select the **+** icon to **Create a resource**. 1. Select **Create Function App in Azure**. Use the following settings for setting up your function app. @@ -273,7 +273,7 @@ The function needs to be deployed to Azure using our IDE. Check that you're corr --- -## Configure authentication for your Azure Function (Authenticate the client) +### Authenticate the client There are three ways to set up authentication for your Azure Function: @@ -289,18 +289,18 @@ By default, the code has been set up for authentication in the Azure portal usin | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | -### [Set up authentication in Azure portal](#tab/azure-portal) +#### [Set up authentication in Azure portal](#tab/azure-portal) -### Set up authentication in the Azure portal using environment variables +#### Set up authentication in the Azure portal using environment variables 1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). 2. Navigate to the function app you created, and under **Settings**, select **Configuration**. 3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. 4. Select **Save** to save the application settings. -### [Set up authentication in your code](#tab/nuget-library) +#### [Set up authentication in your code](#tab/nuget-library) -### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` +#### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` 1. Open the *AuthEventsTrigger.cs* file in your IDE. 1. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. From 72fd333337fec2dd2f52c7f24b24323af386d9cc Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Wed, 19 Jun 2024 16:45:33 -0700 Subject: [PATCH 10/14] removed locale from urls --- .../README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 77234cd7e6ad2..0a86083f7df2d 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -12,11 +12,11 @@ You can follow this article to start creating your function: [Create a REST API ### Prerequisites -- A basic understanding of the concepts covered in [Custom authentication extensions overview](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-overview). +- A basic understanding of the concepts covered in [Custom authentication extensions overview](https://learn.microsoft.com/entra/identity-platform/custom-extension-overview). - An Azure subscription with the ability to create Azure Functions. If you don't have an existing Azure account, sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://account.windowsazure.com/Home/Index). - A Microsoft Entra ID tenant. You can use either a customer or workforce tenant for this how-to guide. - One of the following IDEs and configurations: - - Visual Studio with [Azure Development workload for Visual Studio](https://learn.microsoft.com/en-us/dotnet/azure/configure-visual-studio) configured. + - Visual Studio with [Azure Development workload for Visual Studio](https://learn.microsoft.com/dotnet/azure/configure-visual-studio) configured. - Visual Studio Code, with the [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension enabled. ### Create and build the Azure Function app @@ -252,7 +252,7 @@ The function needs to be deployed to Azure using our IDE. Check that you're corr | ------------ | ---------------- | ----------- | | **Name** | Globally unique name | A name that identifies the new function app. Valid characters are `a-z` (case insensitive), `0-9`, and `-`. | | **Subscription** | Your subscription | The subscription under which the new function app is created. | - | **[Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview)** | *myResourceGroup* | Select an existing resource group, or name the new one in which you'll create your function app. | + | **[Resource Group](https://learn.microsoft.com/azure/azure-resource-manager/management/overview)** | *myResourceGroup* | Select an existing resource group, or name the new one in which you'll create your function app. | | **Plan type** | Consumption (Serverless) | Hosting plan that defines how resources are allocated to your function app. | | **Location** | Preferred region | Select a [region](https://azure.microsoft.com/regions/) that's near you or near other services that your functions can access. | | **Azure Storage** | Your storage account | An Azure storage account is required by the Functions runtime. Select New to configure a general-purpose storage account. | @@ -279,13 +279,13 @@ There are three ways to set up authentication for your Azure Function: - [Set up authentication in the Azure portal using environment variables](#set-up-authentication-in-the-azure-portal-using-environment-variables) (recommended) - [Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute`](#set-up-authentication-in-your-code-using-webjobsauthenticationeventstriggerattribute) -- [Azure App service authentication and authorization](https://learn.microsoft.com/en-us/azure/app-service/configure-authentication-provider-aad?tabs=workforce-tenant) +- [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/configure-authentication-provider-aad?tabs=workforce-tenant) -By default, the code has been set up for authentication in the Azure portal using environment variables. Use the tabs below to select your preferred method of implementing environment variables, or alternatively, refer to the built-in [Azure App service authentication and authorization](https://learn.microsoft.com/en-us/azure/app-service/overview-authentication-authorization). For setting up environment variables, use the following values: +By default, the code has been set up for authentication in the Azure portal using environment variables. Use the tabs below to select your preferred method of implementing environment variables, or alternatively, refer to the built-in [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/overview-authentication-authorization). For setting up environment variables, use the following values: | Name | Value | | ---- | ----- | - | *AuthenticationEvents__AudienceAppId* | *Custom authentication extension app ID* which is set up in [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-tokenissuancestart-configuration) | + | *AuthenticationEvents__AudienceAppId* | *Custom authentication extension app ID* which is set up in [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration) | | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | @@ -293,7 +293,7 @@ By default, the code has been set up for authentication in the Azure portal usin #### Set up authentication in the Azure portal using environment variables -1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). +1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). 2. Navigate to the function app you created, and under **Settings**, select **Configuration**. 3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. 4. Select **Save** to save the application settings. From 53472114343007a1188f7ac3a6d0f9e1931c1c38 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Mon, 24 Jun 2024 16:17:22 -0700 Subject: [PATCH 11/14] Feedback changes --- .../README.md | 190 ++++-------------- 1 file changed, 39 insertions(+), 151 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 0a86083f7df2d..0a2f72e7d44fa 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -21,107 +21,43 @@ You can follow this article to start creating your function: [Create a REST API ### Create and build the Azure Function app -In this step, you create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code. You build the project and run the function to extract the local function URL. - -### Create the application - -To create an Azure Function app, follow these steps: - -#### [Visual Studio](#tab/visual-studio) - -1. Open Visual Studio, and select **Create a new project**. -2. Search for and select **Azure Functions**, then select **Next**. -3. Give the project a name, such as *AuthEventsTrigger*. It's a good idea to match the solution name with the project name. -4. Select a location for the project. Select **Next**. -5. Select **.NET 6.0 (Long Term Support)** as the target framework. -6. Select *Http trigger* as the **Function** type, and that **Authorization level** is set to *Function*. Select **Create**. -7. In the **Solution Explorer**, rename the *Function1.cs* file to *AuthEventsTrigger.cs*, and accept the rename change suggestion. - -#### [Visual Studio Code](#tab/visual-studio-code) - -1. Open Visual Studio Code. -2. Select the **New Folder** icon in the **Explorer** window, and create a new folder for your project, for example *AuthEventsTrigger*. -3. Select the Azure extension icon on the left-hand side of the screen. Sign in to your Azure account if you haven't already. -4. Under the **Workspace** bar, select the **Azure Functions** icon > **Create New Project**. -5. In the top bar, select the location to create the project. -6. Select **C#** as the language, and **.NET 6.0 LTS** as the .NET runtime. -7. Select **HTTP trigger** as the template. -8. Provide a name for the project, such as *AuthEventsTrigger*. -9. Accept **Company.Function** as the namespace, with **AccessRights** set to *Function*. - ---- - -### Install the package - -After creating the project, you'll need to install the required NuGet packages and build the project. - -#### [Visual Studio](#tab/visual-studio) - -1. In the top menu of Visual Studio, select **Project**, then **Manage NuGet packages**. -2. Select the **Browse** tab, then search for and select *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* in the right pane. Select **Install**. -3. Apply and accept the changes in the popups that appear. - -#### [Visual Studio Code](#tab/visual-studio-code) - -1. Open the **Terminal** in Visual Studio Code, and navigate to the project folder. -2. Enter the following command into the console to install the *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* NuGet package. - -```console -dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents -``` +The first step is to create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code (found below). You can build the project and run the function to extract the local function URL. --- -### Add the sample code +### Add the snippet The function API is the source of extra claims for your token. For the purposes of this article, we're hardcoding the values for the sample app. In production, you can fetch information about the user from external data store. -In your *AuthEventsTrigger.cs* file, replace the entire contents of the file with the following code: +In your trigger class, add the contents of the following snippet: ```cs -using System; -using Microsoft.Azure.WebJobs; -using Microsoft.Extensions.Logging; -using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart; -using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents; - -namespace AuthEventsTrigger +[FunctionName("onTokenIssuanceStart")] +public static WebJobsAuthenticationEventResponse Run( + [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) { - public static class AuthEventsTrigger + try { - [FunctionName("onTokenIssuanceStart")] - public static WebJobsAuthenticationEventResponse Run( - [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) + if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) { - try - { - // Checks if the request is successful and did the token validation pass - if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) - { - // Fetches information about the user from external data store - // Add new claims to the token's response - request.Response.Actions.Add( - new WebJobsProvideClaimsForToken( - new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), - new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), - new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), - new WebJobsAuthenticationEventsTokenClaim( - "correlationId", - request.Data.AuthenticationContext.CorrelationId.ToString()))); - } - else - { - // If the request fails, such as in token validation, output the failed request status, - // such as in token validation or response validation. - log.LogInformation(request.StatusMessage); - } - return request.Completed(); - } - catch (Exception ex) - { - return request.Failed(ex); - } + request.Response.Actions.Add( + new WebJobsProvideClaimsForToken( + new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), + new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), + new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), + new WebJobsAuthenticationEventsTokenClaim( + "correlationId", + request.Data.AuthenticationContext.CorrelationId.ToString()))); + } + else + { + log.LogInformation(request.StatusMessage); } + return request.Completed(); + } + catch (Exception ex) + { + return request.Failed(ex); } } ``` @@ -130,17 +66,6 @@ namespace AuthEventsTrigger The project has been created, and the sample code has been added. Using your IDE, we need to build and run the project locally to extract the local function URL. -#### [Visual Studio](#tab/visual-studio) - -1. Navigate to **Build** in the top menu, and select **Build Solution**. -2. Press **F5** or select *AuthEventsTrigger* from the top menu to run the function. -3. Copy the **Function url** from the terminal that popups up when running the function. This can be used when setting up a custom authentication extension. - -#### [Visual Studio Code](#tab/visual-studio-code) - -1. In the top menu, select **Run** > **Start Debugging** or press **F5** to run the function. -2. In the terminal, copy the **Function url** that appears. This can be used when setting up a custom authentication extension. - --- ### Run the function locally (recommended) @@ -167,14 +92,14 @@ It's a good idea to test the function locally before deploying it to Azure. We c ```json { "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart", - "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444", + "source": "/tenants/30000000-0000-0000-0000-000000000003/applications/40000000-0000-0000-0000-000000000002", "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData", - "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", - "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555", - "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666", + "tenantId": "30000000-0000-0000-0000-000000000003", + "authenticationEventListenerId": "10000000-0000-0000-0000-000000000001", + "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002", "authenticationContext": { - "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd", + "correlationId": "20000000-0000-0000-0000-000000000002", "client": { "ip": "127.0.0.1", "locale": "en-us", @@ -182,14 +107,14 @@ It's a good idea to test the function locally before deploying it to Azure. We c }, "protocol": "OAUTH2.0", "clientServicePrincipal": { - "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", - "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "id": "40000000-0000-0000-0000-000000000001", + "appId": "40000000-0000-0000-0000-000000000002", "appDisplayName": "My Test application", "displayName": "My Test application" }, "resourceServicePrincipal": { - "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", - "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", + "id": "40000000-0000-0000-0000-000000000003", + "appId": "40000000-0000-0000-0000-000000000004", "appDisplayName": "My Test application", "displayName": "My Test application" }, @@ -198,7 +123,7 @@ It's a good idea to test the function locally before deploying it to Azure. We c "createdDateTime": "2023-08-16T00:00:00Z", "displayName": "Casey Jensen", "givenName": "Casey", - "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", + "id": "60000000-0000-0000-0000-000000000006", "mail": "casey@contoso.com", "onPremisesSamAccountName": "Casey Jensen", "onPremisesSecurityIdentifier": "", @@ -235,43 +160,9 @@ It's a good idea to test the function locally before deploying it to Azure. We c } ``` -### Deploy the function and publish to Azure - -The function needs to be deployed to Azure using our IDE. Check that you're correctly signed in to your Azure account so the function can be published. - -#### [Visual Studio](#tab/visual-studio) - -1. In the Solution Explorer, right-click on the project and select **Publish**. -1. In **Target**, select **Azure**, then select **Next**. -1. Select **Azure Function App (Windows)** for the **Specific Target**, select **Azure Function App (Windows)**, then select **Next**. -1. In the **Function instance**, use the **Subscription name** dropdown to select the subscription under which the new function app will be created in. -1. Select where you want to publish the new function app, and select **Create New**. -1. On the **Function App (Windows)** page, use the function app settings as specified in the following table, then select **Create**. - - | Setting | Suggested value | Description | - | ------------ | ---------------- | ----------- | - | **Name** | Globally unique name | A name that identifies the new function app. Valid characters are `a-z` (case insensitive), `0-9`, and `-`. | - | **Subscription** | Your subscription | The subscription under which the new function app is created. | - | **[Resource Group](https://learn.microsoft.com/azure/azure-resource-manager/management/overview)** | *myResourceGroup* | Select an existing resource group, or name the new one in which you'll create your function app. | - | **Plan type** | Consumption (Serverless) | Hosting plan that defines how resources are allocated to your function app. | - | **Location** | Preferred region | Select a [region](https://azure.microsoft.com/regions/) that's near you or near other services that your functions can access. | - | **Azure Storage** | Your storage account | An Azure storage account is required by the Functions runtime. Select New to configure a general-purpose storage account. | - | **Application Insights** | *Default* | A feature of Azure Monitor. This is autoselected, select the one you wish to use or configure a new one. | - - -2. Wait a few moments for your function app to be deployed. Once the window closes, select **Finish**. -3. A new **Publish** pane opens. At the top, select **Publish**. Wait a few minutes for your function app to be deployed and show up in the Azure portal. - -#### [Visual Studio Code](#tab/visual-studio-code) - -1. Select the **Azure** extension icon. In **Resources**, select the **+** icon to **Create a resource**. -1. Select **Create Function App in Azure**. Use the following settings for setting up your function app. -1. Give the function app a name, such as *AuthEventsTriggerNuGet*, and press **Enter**. -1. Select the **.NET 6 (LTS) In-Process** runtime stack. -1. Select a location for the function app, such as *East US*. -1. Wait a few minutes for your function app to be deployed and show up in the Azure portal. +### Deploy the function and publish to Azure ---- +Once it has been tested and working, deploy the function to Azure. ### Authenticate the client @@ -289,7 +180,6 @@ By default, the code has been set up for authentication in the Azure portal usin | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | -#### [Set up authentication in Azure portal](#tab/azure-portal) #### Set up authentication in the Azure portal using environment variables @@ -298,12 +188,10 @@ By default, the code has been set up for authentication in the Azure portal usin 3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. 4. Select **Save** to save the application settings. -#### [Set up authentication in your code](#tab/nuget-library) - #### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` -1. Open the *AuthEventsTrigger.cs* file in your IDE. -1. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. +1. Open your trigger class in your IDE. +2. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. ```cs [FunctionName("onTokenIssuanceStart")] From ff7ed6f5a6aa48cca93859bef546cc737d87baed Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Mon, 24 Jun 2024 16:56:15 -0700 Subject: [PATCH 12/14] Added required section --- .../README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index 0a2f72e7d44fa..db68700ca7c63 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -25,6 +25,12 @@ The first step is to create an HTTP trigger function API using your IDE, install --- +### Install the package + +After creating the project, you'll need to install the required NuGet packages and build the project *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* + +--- + ### Add the snippet The function API is the source of extra claims for your token. For the purposes of this article, we're hardcoding the values for the sample app. In production, you can fetch information about the user from external data store. From ee60b50154b7407dd42e345b8db7c620db6f7c23 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Tue, 25 Jun 2024 14:58:40 -0700 Subject: [PATCH 13/14] Feedback updates --- .../CHANGELOG.md | 2 +- .../README.md | 68 ++++++++++--------- .../tests/Samples/AuthEventsTrigger.cs | 52 ++++++++++++++ 3 files changed, 89 insertions(+), 33 deletions(-) create mode 100644 sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md index 0500e08a7b7d3..936833eda6c30 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/CHANGELOG.md @@ -1,6 +1,6 @@ # Release History -## 1.0.1 (2024-05-22) +## 1.0.1 (2024-06-25) ### Other Changes - Updated README.md to reflect the latest changes diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index db68700ca7c63..b5d05858ee1e9 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -27,7 +27,11 @@ The first step is to create an HTTP trigger function API using your IDE, install ### Install the package -After creating the project, you'll need to install the required NuGet packages and build the project *Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents* +After creating the project, you'll need to install the required [NuGet package](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents) + +```dotnetcli +dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents +``` --- @@ -37,34 +41,34 @@ The function API is the source of extra claims for your token. For the purposes In your trigger class, add the contents of the following snippet: -```cs -[FunctionName("onTokenIssuanceStart")] -public static WebJobsAuthenticationEventResponse Run( - [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) +```C# Snippet:AuthEventsTriggerExample +try { - try + // Checks if the request is successful and did the token validation pass + if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) { - if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) - { - request.Response.Actions.Add( - new WebJobsProvideClaimsForToken( - new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), - new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), - new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), - new WebJobsAuthenticationEventsTokenClaim( - "correlationId", - request.Data.AuthenticationContext.CorrelationId.ToString()))); - } - else - { - log.LogInformation(request.StatusMessage); - } - return request.Completed(); + // Fetches information about the user from external data store + // Add new claims to the token's response + request.Response.Actions.Add( + new WebJobsProvideClaimsForToken( + new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), + new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), + new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), + new WebJobsAuthenticationEventsTokenClaim( + "correlationId", + request.Data.AuthenticationContext.CorrelationId.ToString()))); } - catch (Exception ex) - { - return request.Failed(ex); + else + { + // If the request fails, such as in token validation, output the failed request status, + // such as in token validation or response validation. + log.LogInformation(request.StatusMessage); } + return request.Completed(); +} +catch (Exception ex) +{ + return request.Failed(ex); } ``` @@ -199,13 +203,13 @@ By default, the code has been set up for authentication in the Azure portal usin 1. Open your trigger class in your IDE. 2. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. -```cs - [FunctionName("onTokenIssuanceStart")] - public static WebJobsAuthenticationEventResponse Run( - [WebJobsAuthenticationEventsTriggerAttribute( - AudienceAppId = "Enter custom authentication extension app ID here", - AuthorityUrl = "Enter authority URI here", - AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) +```C# Snippet:AuthEventsTriggerParameters +[FunctionName("onTokenIssuanceStart")] +public static WebJobsAuthenticationEventResponse Run( +[WebJobsAuthenticationEventsTriggerAttribute( + AudienceAppId = "Enter custom authentication extension app ID here", + AuthorityUrl = "Enter authority URI here", + AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) ``` --- diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs new file mode 100644 index 0000000000000..0ae4982975be9 --- /dev/null +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs @@ -0,0 +1,52 @@ +using System; +using Microsoft.Azure.WebJobs; +using Microsoft.Extensions.Logging; +using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart; +using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents; + +namespace AuthEventsTrigger +{ + public static class AuthEventsTrigger + { + #region Snippet:AuthEventsTriggerParameters + [FunctionName("onTokenIssuanceStart")] + public static WebJobsAuthenticationEventResponse Run( + [WebJobsAuthenticationEventsTriggerAttribute( + AudienceAppId = "Enter custom authentication extension app ID here", + AuthorityUrl = "Enter authority URI here", + AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) + #endregion + { + #region Snippet:AuthEventsTriggerExample + try + { + // Checks if the request is successful and did the token validation pass + if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) + { + // Fetches information about the user from external data store + // Add new claims to the token's response + request.Response.Actions.Add( + new WebJobsProvideClaimsForToken( + new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), + new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), + new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), + new WebJobsAuthenticationEventsTokenClaim( + "correlationId", + request.Data.AuthenticationContext.CorrelationId.ToString()))); + } + else + { + // If the request fails, such as in token validation, output the failed request status, + // such as in token validation or response validation. + log.LogInformation(request.StatusMessage); + } + return request.Completed(); + } + catch (Exception ex) + { + return request.Failed(ex); + } + #endregion + } + } +} \ No newline at end of file From 02b7be6c1ec502afd7bf43723c6ad559564edfb3 Mon Sep 17 00:00:00 2001 From: Abdul Hakim Date: Thu, 27 Jun 2024 14:54:57 -0700 Subject: [PATCH 14/14] Updated layout to match other readme files --- .../README.md | 202 +++++++++--------- .../tests/Samples/AuthEventsTrigger.cs | 10 +- 2 files changed, 102 insertions(+), 110 deletions(-) diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md index b5d05858ee1e9..66bc7de817245 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/README.md @@ -10,6 +10,16 @@ The authentication events trigger for Azure Functions allows you to implement a You can follow this article to start creating your function: [Create a REST API for a token issuance start event in Azure Functions](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library) +### Install the package + +Install the Authentication Event extension with [NuGet](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents): + +```dotnetcli +dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents +``` + +--- + ### Prerequisites - A basic understanding of the concepts covered in [Custom authentication extensions overview](https://learn.microsoft.com/entra/identity-platform/custom-extension-overview). @@ -19,67 +29,114 @@ You can follow this article to start creating your function: [Create a REST API - Visual Studio with [Azure Development workload for Visual Studio](https://learn.microsoft.com/dotnet/azure/configure-visual-studio) configured. - Visual Studio Code, with the [Azure Functions](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) extension enabled. -### Create and build the Azure Function app +### Authenticate the client -The first step is to create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code (found below). You can build the project and run the function to extract the local function URL. +There are three ways to set up authentication for your Azure Function: ---- +- [Set up authentication in the Azure portal using environment variables](#set-up-authentication-in-the-azure-portal-using-environment-variables) (recommended) +- [Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute`](#set-up-authentication-in-your-code-using-webjobsauthenticationeventstriggerattribute) +- [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/configure-authentication-provider-aad?tabs=workforce-tenant) -### Install the package +By default, the code has been set up for authentication in the Azure portal using environment variables. Use the tabs below to select your preferred method of implementing environment variables, or alternatively, refer to the built-in [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/overview-authentication-authorization). For setting up environment variables, use the following values: -After creating the project, you'll need to install the required [NuGet package](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents) + | Name | Value | + | ---- | ----- | + | *AuthenticationEvents__AudienceAppId* | *Custom authentication extension app ID* which is set up in [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration) | + | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | + | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | -```dotnetcli -dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents + +#### Set up authentication in the Azure portal using environment variables + +1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). +2. Navigate to the function app you created, and under **Settings**, select **Configuration**. +3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. +4. Select **Save** to save the application settings. + +#### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` + +1. Open your trigger class in your IDE. +2. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. + +```C# Snippet:AuthEventsTriggerParameters +[FunctionName("onTokenIssuanceStart")] +public static WebJobsAuthenticationEventResponse Run( +[WebJobsAuthenticationEventsTriggerAttribute( + AudienceAppId = "", + AuthorityUrl = "", + AuthorizedPartyAppId = "")] WebJobsTokenIssuanceStartRequest request, ILogger log) ``` ---- +## Key concepts + +### .NET SDK + +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html). + +### Microsoft Entra custom extensions + +Custom extensions allow you to handle Microsoft Entra authentication events, integrate with external systems, and customize what happens in your application authentication experience. For example, a custom claims provider is a custom extension that allows you to enrich or customize application tokens with information from external systems that can't be stored as part of the Microsoft Entra directory. + +### Authentication events trigger + +The authentication events trigger allows a function to be executed when an authentication event is sent from the Microsoft Entra event service. + +### Authentication events trigger output binding + +The authentication events trigger output binding allows a function to send authentication event actions to the Microsoft Entra event service. -### Add the snippet + +### Create and build the Azure Function app + +The first step is to create an HTTP trigger function API using your IDE, install the required NuGet packages and copy in the sample code (found below). You can build the project and run the function to extract the local function URL. + +## Examples The function API is the source of extra claims for your token. For the purposes of this article, we're hardcoding the values for the sample app. In production, you can fetch information about the user from external data store. -In your trigger class, add the contents of the following snippet: +In your trigger class (i.e: _AuthEventsTrigger.cs_), add the contents of the following snippet in your main function body: ```C# Snippet:AuthEventsTriggerExample -try +[FunctionName("onTokenIssuanceStart")] +public static WebJobsAuthenticationEventResponse Run( +[WebJobsAuthenticationEventsTriggerAttribute( + AudienceAppId = "", + AuthorityUrl = "", + AuthorizedPartyAppId = "")] WebJobsTokenIssuanceStartRequest request, ILogger log) { - // Checks if the request is successful and did the token validation pass - if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) + try { - // Fetches information about the user from external data store - // Add new claims to the token's response - request.Response.Actions.Add( - new WebJobsProvideClaimsForToken( - new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), - new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), - new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), - new WebJobsAuthenticationEventsTokenClaim( - "correlationId", - request.Data.AuthenticationContext.CorrelationId.ToString()))); + // Checks if the request is successful and did the token validation pass + if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful) + { + // Fetches information about the user from external data store + // Add new claims to the token's response + request.Response.Actions.Add( + new WebJobsProvideClaimsForToken( + new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"), + new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"), + new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"), + new WebJobsAuthenticationEventsTokenClaim( + "correlationId", + request.Data.AuthenticationContext.CorrelationId.ToString()))); + } + else + { + // If the request fails, such as in token validation, output the failed request status, + // such as in token validation or response validation. + log.LogInformation(request.StatusMessage); + } + return request.Completed(); } - else - { - // If the request fails, such as in token validation, output the failed request status, - // such as in token validation or response validation. - log.LogInformation(request.StatusMessage); + catch (Exception ex) + { + return request.Failed(ex); } - return request.Completed(); -} -catch (Exception ex) -{ - return request.Failed(ex); } ``` ### Build and run the project locally -The project has been created, and the sample code has been added. Using your IDE, we need to build and run the project locally to extract the local function URL. - ---- - -### Run the function locally (recommended) - It's a good idea to test the function locally before deploying it to Azure. We can use a dummy JSON body that imitates the request that Microsoft Entra ID sends to your REST API. Use your preferred API testing tool to call the function directly. 1. In your IDE, open *local.settings.json* and replace the code with the following JSON. We can set `"AuthenticationEvents__BypassTokenValidation"` to `true` for local testing purposes. @@ -174,71 +231,6 @@ It's a good idea to test the function locally before deploying it to Azure. We c Once it has been tested and working, deploy the function to Azure. -### Authenticate the client - -There are three ways to set up authentication for your Azure Function: - -- [Set up authentication in the Azure portal using environment variables](#set-up-authentication-in-the-azure-portal-using-environment-variables) (recommended) -- [Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute`](#set-up-authentication-in-your-code-using-webjobsauthenticationeventstriggerattribute) -- [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/configure-authentication-provider-aad?tabs=workforce-tenant) - -By default, the code has been set up for authentication in the Azure portal using environment variables. Use the tabs below to select your preferred method of implementing environment variables, or alternatively, refer to the built-in [Azure App service authentication and authorization](https://learn.microsoft.com/azure/app-service/overview-authentication-authorization). For setting up environment variables, use the following values: - - | Name | Value | - | ---- | ----- | - | *AuthenticationEvents__AudienceAppId* | *Custom authentication extension app ID* which is set up in [Configure a custom claim provider for a token issuance event](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-configuration) | - | *AuthenticationEvents__AuthorityUrl* | • Workforce tenant `https://login.microsoftonline.com/`
• External tenant `https://.ciamlogin.com/` | - | *AuthenticationEvents__AuthorizedPartyAppId* | `99045fe1-7639-4a75-9d4a-577b6ca3810f` or another authorized party | - - -#### Set up authentication in the Azure portal using environment variables - -1. Sign in to the [Azure portal](https://portal.azure.com) as at least an [Application Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#application-developer) or [Authentication Administrator](https://learn.microsoft.com/entra/identity/role-based-access-control/permissions-reference#authentication-administrator). -2. Navigate to the function app you created, and under **Settings**, select **Configuration**. -3. Under **Application settings**, select **New application setting** and add the environment variables from the table and their associated values. -4. Select **Save** to save the application settings. - -#### Set up authentication in your code using `WebJobsAuthenticationEventsTriggerAttribute` - -1. Open your trigger class in your IDE. -2. Modify the `WebJobsAuthenticationEventsTriggerAttribute` include the `AuthorityUrl`, `AudienceAppId` and `AuthorizedPartyAppId` properties, as shown in the below snippet. - -```C# Snippet:AuthEventsTriggerParameters -[FunctionName("onTokenIssuanceStart")] -public static WebJobsAuthenticationEventResponse Run( -[WebJobsAuthenticationEventsTriggerAttribute( - AudienceAppId = "Enter custom authentication extension app ID here", - AuthorityUrl = "Enter authority URI here", - AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) -``` - ---- - -## Key concepts - -### .NET SDK - -Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html). - -### Microsoft Entra custom extensions - -Custom extensions allow you to handle Microsoft Entra authentication events, integrate with external systems, and customize what happens in your application authentication experience. For example, a custom claims provider is a custom extension that allows you to enrich or customize application tokens with information from external systems that can't be stored as part of the Microsoft Entra directory. - -### Authentication events trigger - -The authentication events trigger allows a function to be executed when an authentication event is sent from the Microsoft Entra event service. - -### Authentication events trigger output binding - -The authentication events trigger output binding allows a function to send authentication event actions to the Microsoft Entra event service. - -## Examples - -To test token augmentation, please do the following. - -* Open the project that was created in the prior step. [How to get started](#how-to-get-started) -* Follow [these steps](https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup?tabs=visual-studio%2Cazure-portal&pivots=nuget-library#build-and-run-the-project-locally) to test your app locally. - ## Troubleshooting ### Visual Studio Code @@ -247,7 +239,7 @@ To test token augmentation, please do the following. ### Azure function endpoint -* 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. +* 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" ## Next steps diff --git a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs index 0ae4982975be9..f2527d0f16b0a 100644 --- a/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs +++ b/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/tests/Samples/AuthEventsTrigger.cs @@ -8,16 +8,16 @@ namespace AuthEventsTrigger { public static class AuthEventsTrigger { + #region Snippet:AuthEventsTriggerExample #region Snippet:AuthEventsTriggerParameters [FunctionName("onTokenIssuanceStart")] public static WebJobsAuthenticationEventResponse Run( [WebJobsAuthenticationEventsTriggerAttribute( - AudienceAppId = "Enter custom authentication extension app ID here", - AuthorityUrl = "Enter authority URI here", - AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log) + AudienceAppId = "", + AuthorityUrl = "", + AuthorizedPartyAppId = "")] WebJobsTokenIssuanceStartRequest request, ILogger log) #endregion { - #region Snippet:AuthEventsTriggerExample try { // Checks if the request is successful and did the token validation pass @@ -46,7 +46,7 @@ public static WebJobsAuthenticationEventResponse Run( { return request.Failed(ex); } - #endregion } + #endregion } } \ No newline at end of file