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's user's authentication type is set to External.

This article outlines how to configure a new SAML app in Microsoft Entra and link it to Mazlan Home.

Creating a SAML app

To create a SAML app in Microsoft Entra:

1. Log in to to the Entra portal.
2. Navigate to Enterprise applications.
3. Click New Application.

4. Click Create your own application.
5. Enter a name for your app.
6. Select the Integrate any other application you don't find in the gallery option.

7. Select SAML from the method options.

Configuring the SAML app

Provider name

To configure the provider name: 

1. Sign in to Mazlan Home. 
2. Navigate to the Admin Console.
3. Go to the Security Center.
4. Select Authentication.
5. Select Eternal IDP Configuration. 
6. Click Add Identity Provider.
7. Select SAML.
8. Click Next.
9. Enter the required Provider name.
   This will be a friendly name that will be displayed as the button label for your corporate ID on the Mazlan Home login page.

Identifier and Reply URL

Mazlan Home

To configure the Identifier and Reply URLs:

1. On the SAML Configuration screen, you will see the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL).
2. Copy these values as you will need this to configure your Microsoft Entra app.

Microsoft Entra

1. Paste the value for Entity ID copied from Mazlan Home.
2. Paste the value for Reply URL copied from Mazlan Home.

Relay State for IdP-initiated workflow

Mazlan Home

In Mazlan Home, as part of the SAML configuration, you will have to decide whether to allow IdP-Initiated SAML sign-in.

To configure this:

1. At the SAML Configuration, select Accept SP-initiated and IdP-initiated SAML assertions only to enable the IdP-initiated workflow, allowing launch of Mazlan Home from your IdP dashboard (if supported).
2. Once you allow IdP-initiated SAML assertions, the SAML signing and encryption options will not be supported and will be hidden.

SAML Configuration - Require SP-initiated SAML assertions	SAML Configuration - accept SP-initiated and IdP-initiated SAML assetions

3. Click Apply Configuration.
   You will see the Relay State at the top section of the SAML Configuration.
4. Copy this value as you will need this to configure your Microsoft Entra app.

Microsoft Entra

Metadata document endpoint

Microsoft Entra

You will need to retrieve the metadata document endpoint URL to be configured in Mazlan Home.

To retrieve the metadata document endpoint URL:

1. Go to the Entra portal.
2. Copy the App Federation Metadata URL.

Mazlan Home

To configure the metadata document endpoint URL:

1. Scroll to the Metadata document source section.
2. Paste the copied URL in the Enter metadata document endpoint URL field.
3. Click Apply Configuration.

Adding users/groups

By default, no users will be able to log in using the Microsoft Entra Enterprise application until they are explicitly assigned access. 

To grant access:

1. Go to the application in the Entra portal.

2. Navigate to Manage, Users and groups.

3. Click Add user/group.

4. Select the relevant users/groups.

5. Click Assign.

Configuring attribute mapping

Email attribute

Microsoft Entra

Whether your organisation uses Email or Username as the login identifier, you will need to add the email attribute in Microsoft Entra and map the email attribute in Mazlan Home. 

To configure the attribute:

1. Go to the application in the Entra portal.

2. Scroll to Attributes & Claims.

3. Click Edit.

4. Copy the pre-configured or custom claim to be configured in Mazlan Home.

Pre-configured claim

By default, Microsoft Entra ID's Enterprise application includes a pre-configured claim that is mapped to user.mail.

If you wish to use this default claim, copy its claim name. This value will be used later to map to the email user pool attribute in Mazlan Home.

Custom claim

You can also use any other custom claims that is mapped to an email value that is not included in the default claims provided by Microsoft Entra.

To create a new claim:

1. Click Add new claim.

2. Enter a Name for the claim.

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

4. Click Save.

Once saved, the newly created claim will be listed under Additional claims.

To use this custom claim, copy its claim name. This value will be used later to map to the email user pool attribute in Mazlan Home.

Mazlan Home

To map the attributes:

1. Scroll down to the Attribute mapping section.
2. Paste the claim name in the SAML attribute field next to the email User pool attribute.
   Depending on the claim name at your IdP set up, this could either be in a full URL format or a field name.

Username attribute

Microsoft Entra

If your organisation uses Username as login identifier, you must configure the email and preferred username attribute in Microsoft Entra and map them in Mazlan Home.

To configure the attribute in Microsoft Entra

1. Go to the application in the Entra portal.

2. Scroll to Attributes & Claims.

3. Click Edit.

4. Copy the pre-configured or custom claim.

Pre-configured claim

By default, Microsoft Entra ID's Enterprise application includes a pre-configured claim that is 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.

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. Scroll to Attributes & Claims.

3. Click Edit.

4. Click Add New claim.

5. Enter a Name for the claim.

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

7. Click Save.

Once saved, the newly created claim will be listed under Additional 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.

Mazlan Home

To map the attribute:

1. Go to Mazlan Home.
2. Scroll down to the Attribute mapping section.
3. Paste the claim name in the SAML attribute field next to the preferred_username User pool attribute.

Signing SAML response

When you sign SAML requests, your IdP can verify that a request has the expected signature. You will need to configure this in Mazlan Home and Microsoft Entra.

Mazlan Home

To enable this in Mazlan Home:

1. Access the SAML Configuration.
2. Tick Sign SAML requests to this provider.

The signing certificate will be available at the top section for download.

Microsoft Entra

To enable this in Microsoft Entra:

1. Go to the Entra portal.
2. Open the application.
3. Navigate to Single Sign-On.
4. Scroll to the Verification certifications.
5. Click Edit.
6. Tick Require Verification certificates
7. Upload the signing certificate downloaded from Mazlan Home’s SAML Configuration.
8. Click Save.

Enabling encrypted SAML assertions

To enable SAML encryption, the settings must be configured on both Mazlan Home and Microsoft Entra. 

Note

This option will not be available if you accept IDP-initiated SAML assertions.

Mazlan Home

To enable this in Mazlan Home:

1. Access the SAML Configuration.
2. Tick Require encrypted SAML assertions from this provider.
   The signing certificate will be available at the top section for download.

3. Click Download encryption certificate.
   Save the encryption certificate in the .cer format.
4. Click Apply Configuration to save the changes.

Microsoft Entra

To enable this in Microsoft Entra:

1. Go to the Entra portal.
2. Open the application.
3. Go to Token encryption.
4. Click Import Certificate.
5. Upload the encryption certificate previously downloaded from Mazlan Home.

Once the certificate is imported, it will appear with an Inactive status.

To activate it:

1. Open the context menu next to the certificate.
2. Select Activate token encryption certificate.

Single Sign-Out error

Although Mazlan Home's external IdP configuration allows for single sign-out to be enabled, this feature doesn't work when the Identity Provider (IdP) is Microsoft Entra ID.

This is because Mazlan Home's authentication provider, AWS Cognito, only supports POST requests for single sign-out, whereas Entra ID only supports GET requests, leading to an incompatibility between the two services.

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)