Who is this article for?

Administrators responsible for managing organization security settings in Mazlan Home.

Admin Console access is required.

You can set up Microsoft Entra as your corporate identity provider (IdP) in Mazlan Home using SAML or OIDC. To use an external identity provider like Microsoft Entra, you will need to ensure the Mazlan Home 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 Mazlan Home.

Creating an OIDC app

To create an OIDC app in Microsoft Entra:

1. Log in to to the Entra portal.
2. Navigate to App registrations.

3. Click New registration to create a new app.

   

Configuring the OIDC app

Mazlan Home

To configure your OIDC IDP in Mazlan Home:

1. Sign in to Mazlan Home. 
2. Navigate to the Admin Console.
3. Go to the Security Center.
4. Select Authentication.
5. Select External IDP Configuration. 
6. Click Add Identity Provider.
7. Select OIDC.
8. Click Next. 
9. Enter a Provider name.
   This name will appear as the sign-in button label at the sign-in page.
10. Complete the remaining mandatory settings based on instructions in the sub-sections below.
11. Click Apply Configuration to save the IDP configuration in Mazlan Home.

Client ID and Client Secret

You will need a client ID and secret when setting up the OIDC IdP in Mazlan Home. 

Microsoft Entra

To obtain the client ID:

1. Once the App is created, you can copy the Application (Client) ID.
   This is the Client ID to be configured in Mazlan Home.

2. Go to Certificates & secrets.
3. Click New client secret.
4. Enter a meaningful Description.
5. Set the Expiry time according to your company policies.

6. Once created, copy the Value.
   This is the Client Secret to be configured in Mazlan Home.

Mazlan Home

To configure the Client ID and Client in Mazlan Home:

1. Go to the OIDC Configuration screen.
2. Enter the Client ID and Client secret you have retrieved from Microsoft Entra.

Redirect URL

The Redirect URL for Mazlan Home needs to be added to the Micrsoft Entra app.

Mazlan Home

In Mazlan Home, copy the Redirect URL displayed at the top of the OIDC Configuration screen.

Microsoft Entra

To set up the Redirect URL in Microsoft Entra:

1. Navigate to Overview.
2. Open the Manage menu.
3. Select Authentication (Preview).
4. Click Add Redirect URI.
5. Select Web.

6. Paste the Redirect URI copied from Mazlan Home.
7. Click Configure.

Authorized scope

In Mazlan Home, you will need to configure the required authorized scope. Mazlan Home 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 Mazlan Home, 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:

1. Navigate to Overview.
2. Go to Endpoints.
3. Get the OpenID Connect metadata document URL.

4. Open the metadata document using a web browser.
5. Copy the Issuer URL.

Mazlan Home

To set up the Issuer URL in Mazlan Home:

1. Go to the OIDC Configuration screen. 
2. Select Auto fill through issuer URL.
3. 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 Mazlan Home.

Email attribute

In Mazlan Home, 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 Mazlan Home, enter email as the OpenID Connect attribute next to the email User pool attribute.

Username attribute

In Mazlan Home, 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 Mazlan Home.

Note

If you are using preferred_username, you will need to ensure that the Username value created/imported in Mazlan Home 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 in Mazlan Home.

To create a new claim:

1. Go to the application in the Entra portal.

2. Navigate to Overview.

3. Click Manage applicationi n local directory.

4. Open the Manage menu.

5. Select Single sign-on.

6. Click Edit next to Attributes & Claims.

7. Click Add New claim.

8. Enter a Name for the claim.

9. Ensure you select a Source attribute that will return the user's email address (e.g., user.employeeid).

10. 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 in Mazlan Home.

If you are using employee_id, make sure that the Username value created or imported in Mazlan Home user management matches the value returned from employee_id. You can verify this in Microsoft Entra.

Further reading

• Converting Single Sign-On (SSO) authentication types
• Configuring Single Sign-On (SSO) for Mazlan Home
• Troubleshooting single-sign on (SSO) with an external identity provider (IDP)