Setting up Microsoft Entra for OIDC-based Single Sign-On (SSO)
Who is this article for?
Administrators responsible for managing organization security settings in Ideagen solutions and Mazlan.
Admin Console access is required.
You can set up Microsoft Entra as your corporate identity provider (IdP) in Ideagen using SAML or OIDC. To use an external identity provider like Microsoft Entra, you will need to ensure the user's authentication type is set to External.
This article outlines how to configure a new OIDC app in Microsoft Entra and link it to Ideagen.
Creating an OIDC app
To create an OIDC app in Microsoft Entra:
- Log in to to the Entra portal.
- Navigate to App registrations.
-
Click New registration to create a new app.
Note: Ideagen is not published as a pre-integrated app in the Microsoft Entra ID App Gallery. You will need to manually create a new Enterprise Application (sometimes called a "non-gallery application") in your own Entra ID tenant, rather than searching for an Ideagen solution by name in the gallery.
Configuring the OIDC app
Ideagen
To configure your OIDC IDP in Ideagen:
- Sign in to Ideagen.
- Navigate to the Admin Console.
- Go to the Security Center.
- Select Authentication.
- Select External IDP Configuration.
- Click Add Identity Provider.
- Select OIDC.
- Click Next.
- Enter a Provider name.
This name will appear as the sign-in button label at the sign-in page. Note: Do not use these reserved authentication provider names:Google,Facebook,LoginWithAmazon, orSignInWithApple. - Complete the remaining mandatory settings based on instructions in the sub-sections below.
- Click Apply Configuration to save the IDP configuration in Ideagen.
Client ID and Client Secret
You will need a client ID and secret when setting up the OIDC IdP in Ideagen.
Microsoft Entra
To obtain the client ID:
- Once the App is created, you can copy the Application (Client) ID.
This is the Client ID to be configured in Ideagen.
- Go to Certificates & secrets.
- Click New client secret.
- Enter a meaningful Description.
- Set the Expiry time according to your company policies.
- Once created, copy the Value.
This is the Client Secret to be configured in Ideagen.
Ideagen
To configure the Client ID and Client in Ideagen:
- Go to the OIDC Configuration screen.
- Enter the Client ID and Client secret you have retrieved from Microsoft Entra.
Redirect URL
The Redirect URL for Ideagen needs to be added to the Microsoft Entra app.
Ideagen
In Ideagen, copy the Redirect URL displayed at the top of the OIDC Configuration screen.
Microsoft Entra
To set up the Redirect URL in Microsoft Entra:
- Navigate to Overview.
- Open the Manage menu.
- Select Authentication (Preview).
- Click Add Redirect URI.
- Select Web.
- Paste the Redirect URI copied from Ideagen.
- Click Configure.
Authorized scope
In Ideagen, you will need to configure the required authorized scope. Ideagen only populates openid by default. You will need to populate the additional scope as required, separated with spaces.
Refer to this page ID token claims reference - Microsoft identity platform for information on the scope required for each claim.
For example, you will need to add:
- profile scope to use the preferred_username claim
- email scope to use the email claim
- profile scope to use the name claim.
Attribute request method
In Ideagen, select one of the methods for the attribute request method. For example, GET. Both GET and POST methods should be supported by Microsoft Entra.
Issuer URL
Microsoft Entra
To retrieve the Issuer URL from Microsoft Entra:
- Navigate to Overview.
- Go to Endpoints.
- Get the OpenID Connect metadata document URL.
- Open the metadata document using a web browser.
- Copy the Issuer URL.
Ideagen
To set up the Issuer URL in Ideagen:
- Go to the OIDC Configuration screen.
- Select Auto fill through issuer URL.
- Paste the Issuer URL obtained from Microsoft Entra.
Configuring attribute mapping
In most cases, you will be required to map both the email and preferred_username values in Ideagen.
Email attribute
In Ideagen, on the OIDC Configuration screen, you will always see email listed as a fixed User pool attribute that you need to map. By default, Microsoft Entra ID's Enterprise Application includes a pre-configured claim named email that is mapped to user.mail.
To set up the email attribute in Ideagen, enter email as the OpenID Connect attribute next to the email User pool attribute.
Username attribute
In Ideagen, on the OIDC Configuration screen, if you see preferred_username listed as a fixed User pool attribute that you need to map, ensure it is mapped to an attribute from your IdP that contains a unique and consistent identifier for each user.
Pre-configured claim
By default, Microsoft Entra ID's Enterprise Application includes a pre-configured claim named preferred_username mapped to user.userprincipalname. Assuming that user.userprincipalname contains a unique value for each user, you can copy the default claim name to be mapped to the preferred_username attribute in Ideagen.
Note
If you are using preferred_username, you will need to ensure that the Username value created/imported in User Management is consistent with the value returned from preferred_username, which follows the format of user@domain.com.
Custom claim
You can also use any other unique value that is not included in the default claims provided by Microsoft Entra as the preferred username.
For example, if your organisation uses Employee ID as a unique identifier, you can create a custom claim to map Microsoft Entra's Employee ID to the preferred_username user pool attribute.
To create a new claim:
Go to the application in the Entra portal.
Navigate to Overview.
Click Manage applicationi n local directory.
Open the Manage menu.
Select Single sign-on.
Click Edit next to Attributes & Claims.
Click Add New claim.
Enter a Name for the claim.
Ensure you select a Source attribute that will return the user's email address (e.g., user.employeeid).
-
Click Save.
After adding the new attribute, configure the application to permit these changes. For a single-tenant app, like ours, the easiest method is to update the application manifest to recognise the modified claims.
To use this custom claim, copy its claim name. This value will be used later to map to the preferred_username user pool attribute.
If you are using employee_id, make sure that the Username value created or imported in Ideagen user management matches the value returned from employee_id. You can verify this in Microsoft Entra.