This post shows how Azure Key Vault certificates can be used with Microsoft.Identity.Web in an ASP.NET Core application which requires a downstream “access_as_user” API. The Microsoft Entra ID App Registrations requires a certificate instead of a client secret.

Code: https://github.com/damienbod/MicrosoftEntraIDAuthMicrosoftIdentityWeb

Posts in this series

• Implement Microsoft Entra ID Client credentials flow using Client Certificates for service APIs
• Using Key Vault certificates with Microsoft.Identity.Web and ASP.NET Core applications
• Using encrypted access tokens in Azure with Microsoft.Identity.Web and Azure App registrations
• Implement a Web APP and an ASP.NET Core Secure API using Microsoft Entra ID which delegates to a second API
• Using multiple APIs in Angular and ASP.NET Core with Microsoft Entra ID authentication
• Using multiple APIs in Blazor with Microsoft Entra ID authentication
• Microsoft Entra ID Access Token Lifetime Policy Management in ASP.NET Core
• Implement OAUTH Device Code Flow with Microsoft Entra ID and ASP.NET Core
• Implement app roles authorization with Microsoft Entra ID and ASP.NET Core

History

2023-11-28 Updated to .NET 8

Creating the Key Vault certificates

The certificate which will be used in the ASP.NET Core applications can be created in Azure Key Vault. The .cer export needs to be downloaded after the certificate has been created.

The certificate can then be uploaded to the Azure App Registration. Certificates are used for authentication instead of secrets.

The Azure App Registration and the downstream API App Registration is configured as shown in this post.

The delegated API permission with the access_as_user scope is added. Other standard OIDC delegated permissions are added as required.

The Startup class uses Microsoft.Identity.Web to setup the authentication and configure the API access like in the documentation. AddMicrosoftIdentityWebAppAuthentication is used and the EnableTokenAcquisitionToCallDownstreamApi for the user access token.

Note: when using AddInMemoryTokenCaches, there is a problem when running in Visual studio 2019. After every start, you need to delete the cookies manually from the browser, otherwise an exception is thrown. This is because after each restart, the cache gets emptied but the cookie remains. This is a bit of a pain using Microsoft.Identity.Web. At present, this can only be fixed by using a persistent cache.

public void ConfigureServices(IServiceCollection services)
{
	services.AddTransient<ApiService>();
	services.AddHttpClient();

	services.AddOptions();

	string[]? initialScopes = Configuration
		.GetValue<string>("CallApi:ScopeForAccessToken")?.Split(' ');

	services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
		.EnableTokenAcquisitionToCallDownstreamApi(initialScopes)
		.AddInMemoryTokenCaches();

	services.AddRazorPages().AddMvcOptions(options =>
	{
		var policy = new AuthorizationPolicyBuilder()
			.RequireAuthenticatedUser()
			.Build();
		options.Filters.Add(new AuthorizeFilter(policy));
	}).AddMicrosoftIdentityUI();
}

Azure Key Vault Certificate Setup

The Azure Key Vault certificates can now be configured in the ASP.NET Core application. The applications need to work in Azure when deployed and also when debugging locally in Visual Studio 2022.

The Certificate configuration is added to the AzureAd app.settings. The ClientCertificates settings using Key Vault is configured to use the same certificate created above which was uploaded to the Azure App Registration for the application.

  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "damienbodhotmail.onmicrosoft.com",
    "TenantId": "7ff95b15-dc21-4ba6-bc92-824856578fc1",
    "ClientId": "8e2b45c2-cad0-43c3-8af2-b32b73de30e4",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath ": "/signout-callback-oidc",
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://damienbod.vault.azure.net",
        "KeyVaultCertificateName": "DcPortalCert"
      }
    ]
  },

The DefaultAzureCredential from Azure SDK is used to access the Azure Key Vault. In Visual Studio 2019, the Environment variables can be used to setup the access, together with your Visual Studio account. If the Azure SDK is setup incorrectly, local debugging will not work when fetching the access token for the API access.

This can be setup by right clicking your project and adding the AZURE_CLIENT_ID, AZURE_TENANT_ID settings for you project.

This can also be configured directly in the launchSettings.json using the environmentVariables. This can then be added to the profiles as required.

 "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "damienbodhotmail.onmicrosoft.com",
    "TenantId": "7ff95b15-dc21-4ba6-bc92-824856578fc1",
    "ClientId": "fdc48df2-2b54-411b-a684-7d9868ce1a95",
    "TokenDecryptionCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://damienbod.vault.azure.net",
        "KeyVaultCertificateName": "DecryptionCertificateCert2"
      }
    ],
    "SendX5C": "true"
  },

Now the Microsoft Entra ID authentication can be used with Azure App Registrations using certificates and run from both Visual Studio 2019 or local debugging and of course Azure deployments.

Links

Authentication and the Azure SDK

https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#second-case-access-token-request-with-a-certificate

https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Client-credential-flows

https://tools.ietf.org/html/rfc7523

https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication

https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens

https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Client-Assertions

https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow

https://github.com/AzureAD/microsoft-identity-web/wiki/Using-certificates#describing-client-certificates-to-use-by-configuration

https://github.com/KevinDockx/ApiSecurityInDepth

https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki