{"id":8017,"date":"2026-09-17T19:27:12","date_gmt":"2026-09-17T17:27:12","guid":{"rendered":"https:\/\/blog.redbaronofazure.com\/?p=8017"},"modified":"2026-09-17T21:49:53","modified_gmt":"2026-09-17T19:49:53","slug":"password-migration-with-entra-external-id-part-2","status":"publish","type":"post","link":"https:\/\/blog.redbaronofazure.com\/?p=8017","title":{"rendered":"Password Migration with Entra External ID \u2013 part 2"},"content":{"rendered":"\n

This post continues where the previous post<\/a> ended with configuring a custom extension for password migration in Entra External ID. Having completed the configuration in Entra, we can now focus on what we have to do in code. The code here will be an aspnet webapi in the classic setup with Program.cs<\/a> and a Controller handling the API endpoints.<\/p>\n\n\n\n

One important change to highlight is that when you introduce the password migration extension, and add the certificate as the KeyCrendetials, then the access token passed to your API will be encrypted. If you only do the other extensions, as explained in the very first post<\/a>, you don’t need to handle the JWE encrypted token. I highlight this here if you plan to add password migration to an already existing extension you have.<\/p>\n\n\n\n

Sample code is available in this github repo<\/a>.<\/p>\n\n\n\n

Main topics to understand<\/h2>\n\n\n\n

There are a couple topics to understand when implementing a custom authentication extension:<\/p>\n\n\n\n

  1. The middleware – what does Program.cs need to look like?<\/li>
  2. The request\/response model Entra is using for interacting with extension APIs<\/li>
  3. How you validate a password when migrating users<\/li>
  4. How to get the Entra configuration right so your API actually gets called<\/li>
  5. From PoC to scale….<\/li><\/ol>\n\n\n\n

    The middleware – Program.cs<\/h2>\n\n\n\n

    Entra is calling your API using an access token acquired via client_credentials where the aud claim is your app with the CustomAuthenticationExtension.Receive.Payload<\/em> (see prev post). The wiring in Program.cs<\/a> must there for accept tokens issued by your Entra External tenant with the specific aud claim. To make things worse, it is not a JWT access token. It is a JWE encrypten token where the KeyVault certificate is used to encrypt the token (also see prev post where KeyCredentials is updated). Program.cs<\/a> needs to read the certificate from KeyVault at startup and tell the middleware to use it for decrypting what is passed in the HTTP header for Authorization. If you don’t, the aspnet middleware will reject the call.<\/p>\n\n\n\n

    The helper class KeyVaultHelper reads<\/a> the certificate from KeyVault and keeps it in a static X509Certificate2 variable. The TokenDecryptionKey is then used to set and indicate that when an encrypted JWT token arrives, decrypt it using this certificate.<\/p>\n\n\n\n

    var builder = WebApplication.CreateBuilder(args);\n\n\/\/ pre-load the certificate from KeyVault and do it here as we use it for TokenDecryptionKey below\nvar kvh = new KeyVaultHelper( builder.Configuration );\nkvh.LoadCertificateFromKeyVault();\n\nbuilder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)\n    .AddMicrosoftIdentityWebApi(\n        jwtOptions => {\n            jwtOptions.TokenValidationParameters = new TokenValidationParameters() {\n                ValidateIssuerSigningKey = true,\n                ValidateIssuer = true,\n                ValidIssuer = $\"{instance}{tenantId}\/v2.0\",\n                ValidateLifetime = true,\n                RequireExpirationTime = true,\n                AudienceValidator = CustomAudienceValidator,\n                \/\/ Once you add password migration and configure tokenEncryptionId in the app manifest\n                \/\/ you will get an encrypted access token. In fact, it's not a JWT but a JWE.\n                \/\/ We need to add the cert here so the aspnet middleware can decrypt it \n                TokenDecryptionKey = new X509SecurityKey(KeyVaultHelper.Certificate)\n\n            };\n        }, \n<\/code><\/pre>\n\n\n\n
    If your custom authentication extension does not use password migration, don’t use this extra code. Also, when the migration period is over, you can remove this extra code in the next release (don’t forget to remove the KeyCredentials in the app manifest too).<\/p>\n\n\n\n
    There is a custom audience validator<\/a> in the above code, and that is because you might have multiple auth extensions configured to call your API. The CustomAudienceValidator checks the incoming aud claim against configuration in appsettings.json<\/a> to see if it is a valid audience.<\/p>\n\n\n\n
    The request\/response model Entra is using<\/h2>\n\n\n\n
    The request\/response model Entra is using for password migration follows the pattern for custom authentication extensions. The request JSON will look like below. The authenticationContext<\/em> holds the relevant data where clientServicePrincipal<\/em> section describes the app the end user is trying to sign in to, and the user<\/em> section gives you information on who the end user is. Notice also the encryptedPasswordContext<\/em> attribute that holds an encrypted JWT token containing the password.<\/p>\n\n\n\n
    {\n  \"type\": \"microsoft.graph.authenticationEvent.passwordSubmit\",\n  \"source\": \"\/tenants\/11111111-2222-3333-4444-555555555555\/applications\/99999999-2222-3333-4444-555555555555\",\n  \"data\": {\n    \"@odata.type\": \"microsoft.graph.onPasswordSubmitCalloutData\",\n    \"tenantId\": \"11111111-2222-3333-4444-555555555555\",\n    \"authenticationEventListenerId\": \"1aeebe49-233d-4a1f-afe5-5c08cb8172ff\",\n    \"customAuthenticationExtensionId\": \"761fcc06-379a-4544-b2b3-f5aa1dc4ae0d\",\n    \"encryptedPasswordContext\": \"eyJhbGc...iwy4g\",\n    \"authenticationContext\": {\n      \"correlationId\": \"a2b1f0dd-19f6-43a9-be18-3ba36ad419a0\",\n      \"client\": {\n        \"ip\": \"321.456.789.255\",\n        \"locale\": \"en-gb\",\n        \"market\": \"en-gb\"\n      },\n      \"protocol\": \"OAUTH2.0\",\n      \"clientServicePrincipal\": {\n        \"id\": \"a70c1626-70cf-4657-9e4e-bbd8e8908d4e\",\n        \"appId\": \"99999999-2222-3333-4444-555555555555\",\n        \"appDisplayName\": \"ciam-test-app\",\n        \"displayName\": \"ciam-test-app\"\n      },\n      \"resourceServicePrincipal\": null,\n      \"user\": {\n        \"id\": \"77777777-2222-3333-4444-555555555555\",\n        \"userPrincipalName\": \"77777777-2222-3333-4444-555555555555@foobar.onmicrosoft.com\",\n        \"userType\": \"Member\",\n        \"createdDateTime\": \"2026-09-15T13:08:10Z\",\n        \"displayName\": \"John Doe\",\n        \"mail\": \"johndoe@live.com\"\n      }\n    },\n    \"userSignUpInfo\": null,\n    \"otpContext\": null\n  }\n}<\/code><\/pre>\n\n\n\n
    The method in the sample code<\/a> uses the KeyVaultHelper class (_kv) to decrypt the encryptedPasswordContext<\/em> value. Inside you have the userid the user typed is repeated, the password in clear text (feel the responsability!) and a nonce you need to return in your response.<\/p>\n\n\n\n
    string encryptedPasswordContext = request.data!.encryptedPasswordContext!;\nstring? decryptedPayload = _kv.DecryptRsa( encryptedPasswordContext! );\nstring? jsonPayload = _kv.DecodeRsa( decryptedPayload! );\nJsonNode? payload = JsonNode.Parse(jsonPayload!);\nstring? username = payload![\"username\"]?.ToString();\nstring? password = payload![\"user-password\"]?.ToString();\nstring? nonce = payload[\"nonce\"]?.ToString();\n<\/code><\/pre>\n\n\n\n
    After you have validated the password, you can respond to Entra in the following ways<\/p>\n\n\n\n