Migration from Azure ID provider
Contents
This guide describes how to migrate from the legacy com.enonic.app.azureadidprovider.cfg configuration format to the new Entra ID Provider configuration format com.enonic.app.entraidprovider.cfg.
Migrating Redirect URI
With the new version of the ID provider, the Redirect URI format has changed to match the virtual host source path mapping.
The Redirect URI now matches virtual host source path mapping. For instance, you have the following vhost mapping:
mapping.myoidc.host = xp.example.com
mapping.myoidc.source = /my-admin
mapping.myoidc.target = /admin
mapping.myoidc.idProvider.myoidc = defaultThe correct Redirect URI should be:
https://xp.example.com/my-admin/_/idprovider/myoidcMigrating Core Configuration
- NOTE
-
The ID provider configuration supports only Microsoft identity platform v2.0 endpoints.
tenantId
The tenantId property is no longer available. You should use oidcWellKnownEndpoint instead. This approach is recommended for all new configurations, as the properties issuer, authorizationUrl, tokenUrl, userinfoUrl, and jwksUri will then be populated automatically.
Before:
idprovider.<name>.tenantId=<tenantid>After:
idprovider.<name>.oidcWellKnownEndpoint=https://login.microsoftonline.com/<tenantid>/v2.0/.well-known/openid-configuration- NOTE
-
<tenantid>placeholder must be replaced with your real tenant identifier.
logoutUrl
The logoutUrl property is no longer used. You should use endSession.url instead.
Before:
idprovider.<name>.logoutUrl=https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri=https://yourdomain.comAfter:
idprovider.<name>.endSession.url=https://login.microsoftonline.com/common/oauth2/v2.0/logout
idprovider.<name>.endSession.postLogoutRedirectUriKey=https://yourdomain.comforceHttpsOnRedirectUri
This property is not supported by this ID provider. With proper XP configuration a virtual host knows that https is in use.
user…
The user.name property is no longer available. You should use claimUsername instead. The default value is oid, which is extracted from the JWT token and serves as a unique and immutable user identifier.
The user.displayName and user.email properties are no longer available. You should use mappings.displayName and mappings.email instead.
Before:
idprovider.<name>.user.name=@@{oid}
idprovider.<name>.user.displayName=@@{given_name} @@{family_name}
idprovider.<name>.user.email=@@{email}After:
idprovider.<name>.claimUsername=oid # default
idprovider.<name>.mappings.displayName=@@{userinfo.given_name} @@{userinfo.family_name}
idprovider.<name>.mappings.email=@@{userinfo.email}groupPrefix
The groupPrefix property allows you to specify a prefix for Enonic XP groups to which the user will be added. The default value is azure-ad- for backward compatibility.
User events
User events configuration allows you to customize the event prefix and mode. The default value for the userEventPrefix is the name of the current application. Default value for the userEventMode is local. To replicate the behavior of the legacy Azure ID Provider, use the following settings:
idprovider.<name>.userEventPrefix=azure
idprovider.<name>.userEventMode=distributedforceEmailVerification
forceEmailVerification should be always set to false (default value) - as Entra ID does not send a email_verified claim.
Full Migration Example
Old configuration
autoinit=true
idprovider.azure.tenantId= <your-tenant-id>
idprovider.azure.clientId= <your-client-id>
idprovider.azure.clientSecret= <your-client-secret>
idprovider.azure.logoutUrl=https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri=https://yourdomain.com
idprovider.azure.createAndUpdateGroupsOnLoginFromGraphApi=true
idprovider.azure.user.name=@@{oid}
idprovider.azure.user.displayName=@@{given_name} @@{family_name}
idprovider.azure.user.email=@@{email}
idprovider.azure.forceHttpsOnRedirectUri=trueNew configuration
autoinit=true
idprovider.azure.oidcWellKnownEndpoint=https://login.microsoftonline.com/<your-tenant-id>/v2.0/.well-known/openid-configuration
idprovider.azure.clientId=<your-client-id>
idprovider.azure.clientSecret=<your-client-secret>
idprovider.azure.createAndUpdateGroupsOnLoginFromGraphApi=true
idprovider.azure.claimUsername=oid
idprovider.azure.mappings.displayName=@@{userinfo.given_name} @@{userinfo.family_name}
idprovider.azure.mappings.email=@@{userinfo.email}
idprovider.azure.endSession.url=https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/logout
idprovider.azure.endSession.postLogoutRedirectUriKey=https://yourdomain.com