MS Entra ID (SAML v2.0)

Prerequisites

Permissions required for registering and configuring an app in Microsoft Entra ID.

The account must have permission to manage applications in Microsoft Entra ID. Ideally the account should be in the Global Admin role to grant admin consent.

Implement Single Sign-On (SSO)

It is recommended to use two separate browser tabs for the Azure (A) and Keycloak (K) portals to make it easier to apply the settings.

1. (K) Open a new tab in your browser and login to the target Spark tenant. Access the Keycloak console from the User menu.

2. (K) Login to the Keycloak Admin Console using your admin credentials.

3. (K) Click Identity Providers from the left pane.

4. (K) Expand the Add provider dropdown and choose SAML v2.0.

5. (K) Fill in values for the Alias and Display Name fields. The Alias should be a lowercase name without special symbols. Please note this Display Name will appear in the button on the Spark login page.

6. (K) Copy the Redirect URI value.

7. (A) In a second browser tab, sign in to Azure Portal.

8. (A) Navigate to Microsoft Entra ID -> Enterprise Applications -> All applications.

9. (A) On the All applications page, click on New application.

10. (A) Click on Create your own application.

11. (A) Type a name for your application.

12. (A) In the section What are you looking to do with your application?, select Integrate any other application you don't find in the gallery.

13. (A) Click Create.

14. (A) On the Overview page, in the Getting Started area, click on Set up single sign on.

15. (A) In the Select a single sign-on method area, select SAML.

16. (A) On the Set up Single Sign-On with SAML page, in the Basic SAML Configuration area, click Edit.

17. (A) Under the Basic SAML configuration, configure the following settings:

    1. In Identifier (Entity ID), click on Add identifier, use the Redirect URI copied earlier and remove everything after the tenant name, i.e. https://keycloak.{environment}.coherent.global/auth/realms/{tenant}.

    2. Click on Add reply URL and paste the edited Redirect URI into the Reply URL (Assertion Consumer Service URL), i.e. https://keycloak.{environment}.coherent.global/auth/realms/{tenant}/broker/{alias}/endpoint.

    3. Leave the default values for other fields and click Save.

18. (A) In the SAML Certificates Token signing certificate section, copy the App Federation Metadata Url. You will use this link when creating an Entra ID SAML provider on Keycloak.

19. (A) Click on Users and groups in the left pane.

20. (A) Click on the Add user/group to add the users and groups that will use Spark.

21. (K) Return to Keycloak. Paste the App Federation Metadata Url into the SAML entity descriptor field.

22. (K) Click the Add button.

23. (K) In NameID policy format, select Email.

24. (K) Click Save.

25. (K) Click on the Mappers tab and then click on Add mapper.

26. (K) Create 3 mappers with the following properties:

    1. Key	Value
       Name	firstName
       Sync mode override	Force
       Mapper type	Attribute Importer
       Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
       Name Format	ATTRIBUTE_FORMAT_BASIC
       User Attribute Name	firstName

    2. Key	Value
       Name	lastName
       Sync mode override	Force
       Mapper type	Attribute Importer
       Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
       Name Format	ATTRIBUTE_FORMAT_BASIC
       User Attribute Name	lastName

    3. Key	Value
       Name	email
       Sync mode override	Force
       Mapper type	Attribute Importer
       Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
       Name Format	ATTRIBUTE_FORMAT_BASIC
       User Attribute Name	email

27. For SAML SSO, it is important to validate signatures to prevent unauthorized access. For more information see Importance of validating signatures in SAML.

    1. (K) For the identity provider you have setup, scroll down to Signature and Encryption settings.

    2. (K) Enable the option Validate Signature.

28. Navigate to your Spark tenant and sign in using the newly created provider. There will be a button on the Keycloak login page with the display name defined earlier.

Setup users against user groups

In the documentation below, we describe how Spark user group assignment can be done with either Entra ID app roles or Entra ID groups.

• App roles: Use app roles when you need fine-grained, application-specific permissions. This is ideal for defining what users can do within a specific application.

• Groups: Use groups for broader access management that spans multiple applications and resources. This is useful for organizational roles like departments, teams, or project groups where access to various resources needs to be managed collectively.

Feature	App roles	Groups
Scope	Specific to an application	Cross-application
Management	Defined in the application's manifest	Managed in Microsoft Entra ID
Assignment	Assigned to users or groups	Users are added to groups
Granularity	Fine-grained, application-specific roles	Broader, resource-wide access control
Dynamic Membership	No	Yes
Use Case Example	Role-based access within a single app	Access control across multiple resources

Configure Entra ID app roles to Spark user groups

It is recommended to use two separate browser tabs for the Azure and Keycloak portals to make it easier to apply the settings. In this guide, we will setup the automatic roles for the tenant-admin role.

1. (A) In the first tab sign in to Azure Portal.

2. (A) Search for and select Microsoft Entra ID.

3. (A) Select App registrations, then select the application you previously created and click App roles.

4. (A) Select Create app role.

5. (A) Provide the following values and then click Apply.

   Key	Value
   Allowed member types	User/Groups
   Display name	tenant-admin
   Value	tenant-admin
   Description	Your app role description
   Do you want to enable this app role?	True

6. (A) Click Overview in the left pane and then on your application in Managed application in local directory.

7. (A) Click on Set up single sign on.

8. (A) Under Attributes & Claims click Edit.

9. (A) Click on Add new claim.

10. (A) Assign the following values:

    Key	Value
    Name	roles
    Source attribute	user.assignedroles

11. (A) Select Users and Groups from the left pane and then Add user/group.

12. (A) Assign your test account to the tenant-admin role.

13. (K) Open a new tab in your browser and login to the target Spark tenant. Access the Keycloak console from the User menu.

14. (K) Login to the Keycloak Admin Console using your admin credentials.

15. (K) Select Identity Providers from the left pane and then the identity provider you configured in the previous section.

16. (K) Select the Mappers tab and then Add mapper.

17. (K) Provide the following values.

    Name	Value
    Name	tenant-admin
    Sync mode override	force
    Mapper type	Advanced Claim to Group

18. (K) Click Add Claims.

19. (K) Provide the following values:

    Key	Value
    http://schemas.microsoft.com/ws/2008/06/identity/claims/role	tenant-admin

20. (K) Leave Regex Claim Values as Off (which is the default).

21. (K) Click Select Group, choose tenant-admin , then click Select.

22. (K) Click Save.

23. Sign in into Coherent Spark with your test account. Click on your initials and hover over the groups icon to confirm your membership in tenant-admin.

24. We highly recommend creating at least a few additional app groups relevant for Private tenants:

    • Group for supervisor:pf user accounts. In Spark, supervisor:pf members can manage permissions across all folders.

    • Groups for "standard" user accounts, e.g. user:teamA, user:teamB. These groups can be assigned to the users in your organization not responsible for tenant administration. Creating multiple roles for "standard" user accounts can be useful to separate access between teams.

Configure Entra ID groups to Spark user groups

It is recommended to use two separate browser tabs for the Azure and Keycloak portals to make it easier to apply the settings. In this guide, we will setup the automatic roles for the tenant-admin role.

1. (A) In the first tab sign in to Azure Portal.

2. (A) Search for and select Microsoft Entra ID.

3. (A) Select App registrations, then select the application you previously created and click Token Configuration.

4. (A) Click Add groups claim.

5. (A) Select the group types you want to include.

   • Note: If you have users who are members of more than 150 groups, please select the option: Groups assigned to the application. This is recommended for large enterprises to avoid exceeding the limit on the number of groups a token can emit. Additionally, ensure that you add the necessary groups as members to the application you previously created.

6. (A) Expand the SAML section, select Group ID and click Save.

7. (A) On the left pane select Groups.

8. (A) Create or search for your Spark tenant-admin group.

9. (A) Ensure your test account is a member of the group and copy the Object ID of the group.

10. (K) Open a new tab in your browser and login to the target Spark tenant. Access the Keycloak console from the User menu.

11. (K) Login to the Keycloak Admin Console using your admin credentials.

12. (K) Select Identity Providers from the left pane and then the identity provider you configured in the previous section.

13. (K) Select the Mappers tab and then Add mapper.

14. (K) Provide the following values.

    Name	Value
    Name	tenant-admin
    Sync mode override	force
    Mapper type	Advanced Claim to Group

15. (K) Click Add Claims.

16. (K) Provide the following values:

    Key	Value
    http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	Group object ID from Step 9

17. (K) Leave Regex Claim Values as Off (which is the default).

18. (K) Click Select Group, choose tenant-admin , then click Select.

19. (K) Click Save.

20. Sign in into Coherent Spark with your test account. Click on your initials and hover over the groups icon to confirm your membership in tenant-admin.

21. We highly recommend creating at least a few additional app groups relevant for Private tenants:

    • Group for supervisor:pf user accounts. In Spark, supervisor:pf members can manage permissions across all folders.

    • Groups for "standard" user accounts, e.g. user:teamA, user:teamB. These groups can be assigned to the users in your organization not responsible for tenant administration. Creating multiple roles for "standard" user accounts can be useful to separate access between teams.

Enable SAML token encryption eetween Microsoft Entra ID and Keycloak

The following steps configure:

• Keycloak: to generate an RSA encryption keypair and accept encrypted SAML assertions.

• Microsoft Entra ID: to encrypt SAML assertions using Keycloak’s certificate.

Configure Keycloak for SAML assertion decryption

Create an RSA Encryption Key

1. In Keycloak, open your realm (e.g., mytenant).

2. Go to Realm Settings → Keys (left panel).

3. Select Add provider.

4. Choose rsa-enc-generated from the list.

5. Fill in the following fields:

   Key	Value
   Name	Any descriptive name
   Priority	100
   Enabled	On
   Active	On
   Key size	2048
   Algorithm	RSA-OAEP

6. Click Save.

Export the public certificate

1. Go back to the Keys list tab.

2. Locate the newly created rsa-enc-generated key (Provider = Name).

3. Click Certificate.

4. Copy the entire certificate text and save it as a .cer file, e.g. keycloak-saml-encryption.cer.

Enable assertion encryption on the SAML Identity Provider

1. In the left navigation, go to Identity Providers.

2. Select your previously configured Microsoft Entra SAML provider.

3. Scroll down to the SAML Settings section.

4. Set Want Assertions Encrypted to On.

   Key	Value
   Want Assertions Encrypted	On
   Encryption Algorithm	RSA-OAEP

5. Click Save.

Configure Microsoft Entra ID to encrypt SAML tokens

1. In the Microsoft Entra admin center, open your Enterprise Application (the SAML app pointing to Keycloak).

2. In the left menu, under Security, select Token encryption.

3. Click Import certificate and upload the .cer file you exported from Keycloak.

4. After the certificate appears in the list, click the "three-dot menu" next to the certificate and select Activate Token Encryption Certificate.

Configure verification certificates

Enable Keycloak to sign SAML requests

Export the Keycloak Signing Certificate

1. In Keycloak, open your realm (e.g., mytenant).

2. Go to Realm Settings → Keys → Key List.

3. Locate the key with:

   Key	Value
   Algorithm	RS256
   Type	RSA
   Use	SIG

4. Click Certificate.

5. Copy the full certificate text and save it as a .cer file, e.g. keycloak-saml-sig.cer.

Enable signed AuthnRequests in Keycloak

1. Go to Identity Providers in the left navigation.

2. Select your Microsoft Entra SAML provider.

3. Scroll to the SAML Settings section.

4. Set the following:

   Key	Value
   Want AuthnRequests Signed	On
   Signature Algorithm	RSA_SHA256
   SAML Signature Key Name	KEY_ID
   Want Assertions Signed	On

5. Click Save.

Configure Microsoft Entra ID to verify the certificate

Upload the Keycloak Signing Certificate in Entra

1. In the Microsoft Entra admin center, open your Enterprise Application (the SAML app pointing to Keycloak).

2. Go to Single sign-on, scroll to SAML Certificates, and open Verification certificates (optional).

3. Ensure:

   1. Require verification certificates is Enabled.

   2. Allow requests signed with RSA-SHA1 is checked (optional fallback).

4. Upload the .cer file you exported from Keycloak earlier.

5. Click Save.

Enable Privileged Identity Management (PIM)

See MS Entra ID Privileged Identity Management (PIM).

Create an enterprise application for Coherent Spark

See Microsoft Apps.