Microsoft Entra ID SSO

This guide guides you through setting a single SAML record between Microsoft Entra ID (formerly Azure Active Directory) and the platform.

Prerequisites

• Microsoft Entra ID administrator access (or application administrator role)
• the platform organization administrator access
• Your platform domain (for example, probo.example.com)
• Access to DNS settings for domain verification

Prepare the platform Information

Before you set up your Microsoft Entra ID, collect the following details about the platform service provider:

Field	Value
ACS URL	https://your-probo-domain.com/api/connect/v1/saml/2.0/consume
Entity ID	https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata

Replace your-probo-domain.com with your actual platform domain.

Domain Verification

Before you set up anything else, you need to check the domain property:

1. Log in to the platform as an organization administrator
2. Go to Organization Settings → Authentication → SAML
3. Click Verify Domain (If there are no configurations yet, this option will be available)
4. Copy the provided TXT record value
5. Add a TXT record to your domain’s DNS settings:

   Type: TXT
   Name: _probo-domain-verification.your-company.com
   Value: [Verification token from Probo]
   TTL: 300 (or your DNS provider's default)

6. Wait for DNS propagation (usually 5-15 minutes)
7. In the platform, click Complete Verification
8. In case of success, the domain status will be displayed as "Verified"

Configure Microsoft Entra ID

1. Signed to Microsoft Entra admin center

2. Go to Identity → Applications → Enterprise applications

3. Click New application → Create your own application

4. Enter Probo as the application name

5. Select Incorporate any other application that you do not find in the gallery (non-gallery)

6. Click Create

7. In the application view, go to Single sign-on → select SAML

8. In Basic SAML Configuration, click Edit and configure:

   Field	Value
   Identifier (Entity ID)	https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata
   Reply URL (Assertion Consumer Service URL)	https://your-probo-domain.com/api/connect/v1/saml/2.0/consume
   Relay State	[SAML Configuration ID] (optional - see note below)
   Sign on URL	https://your-probo-domain.com (optional)

   Important: The Relay State is optional, but if you want to support the connection streams initiated by IdP, it must be set to your exact SAML configuration ID (not a locholder). If the setting is incorrect, SSO will not work. You will get this ID after creating the SAML configuration in the platform. You can initially leave this ID empty and you can update it later with the exact configuration ID.

9. Click Save

10. In Attributes & Claims, click Edit Configure the following claims:

    Claim name	Source attribute
    email	user.mail
    firstName	user.givenname
    lastName	user.surname

    To add each claim:

    • Click Add new claim
    • Enter the name of the complaint (for example, email)
    • Set Source to Attribute
    • Select the corresponding Source attribute
    • Click Save

    Also check that Unique User Identifier (Name ID) is set to user.userprincipalname or user.mail with the format Email address.

11. In SAML CertificatesDownload the Certificate (Base64) and copy:

    • Login URL (This is the URL of IDP SSO)
    • Microsoft Entra Identifier (This is the ID of the IDP entity)

12. Go to Users and groups

13. Click Add user/group

14. Select users or groups that should have access to the platform

15. Click Assign

Configure the platform

1. Log in to the platform as an organization administrator

2. Go to Organization Settings → Authentication → SAML

3. Click Add SAML Configuration

4. Configure the basic settings:

   Field	Value	Notes
   Email Domain	your-company.com	Your organization’s email domain
   Enforcement Policy	OPTIONAL	Recommended for initial setup

5. Configure identity provider settings with values in Microsoft Entra ID:

   Field	Value	Notes
   IdP Entity ID	[Microsoft Entra Identifier]	Copy from Entra ID setup
   IdP SSO URL	[Login URL]	Copy from Entra ID setup
   IdP Certificate	[Certificate (Base64)]	Paste the downloaded certificate content

6. Configure the attribute mappings:

   Field	Value	Notes
   Email Attribute	email	Maps to user email
   First Name Attribute	firstName	Maps to user first name
   Last Name Attribute	lastName	Maps to user last name
   Role Attribute	[Leave empty]	Optional; map to send ___ZBT_I18N_RUNTIME_BLOCK_202__, ___ZBT_I18N_RUNTIME_BLOCK_203__, ___ZBT_I18N_RUNTIME_BLOCK_204__, or VIEWER

7. Configure user settings:

   Field	Value	Notes
   Auto Signup	Enabled	Allows new users to automatically register through SSO

8. Click Save Configuration

9. Copy the SAML Configuration ID which appears after saving (for example, saml_config_1a2b3c4d)

Update Entra ID Relay State

Return to Microsoft Entra ID to enable ID initiated authentication:

1. Go to your platform application in the Entra administration center
2. Click Single sign-on → Edit Basic SAML Configuration
3. In the Relay State field, enter your SAML configuration ID
4. Click Save

Troubleshooting

"AADSTS75005: The application is not a valid Saml2 protocol message" Error

• Cause: Incorrect Reply URL or Entity ID configuration
• SolutionCheck if the Reply URL and Entity ID in Entra ID match exactly your platform configuration:
  • Reply URL: https://your-probo-domain.com/api/connect/v1/saml/2.0/consume
  • Entity ID: https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata

“AADSTS50105: User not assigned to application” Error

• CauseThe user has not been assigned to the Enterprise application of the platform
• SolutionGo to the Enterprise App Users and groups Assign to a user or group that contains the user

“AADSTS700016: Application not found” Error

• CauseThe incorrect entity ID in the platform or application is not configured correctly
• SolutionCheck if the Microsoft Entra Identifier matches the entity ID set up on the platform

Attributes Not Mapping

• Cause: Claims not configured correctly in Entra ID
• SolutionCheck if the custom requests are configured with the exact names: email, firstName, lastName. Check below Single sign-on → Attributes & Claims

“Invalid RelayState” Error

• Cause: Incorrect Relay State configuration
• SolutionMake sure the relay status is either empty or set to the exact SAML configuration ID on the platform

Debugging Steps

Check Entra ID Sign-in Logs

1. Go to the Enter Administration Center Identity → Monitoring & health → Sign-in logs
2. Filter by application platform
3. Click a failed connection attempt to view error details and troubleshooting recommendations

Test SAML Response

1. In the Enterprise Platform application, access Single sign-on
2. Click Test this application
3. Check the SAML response for errors

Advanced Configuration

Custom Claims

To map additional Entra ID user attributes:

1. In the Enterprise app, go to Single sign-on → Attributes & Claims
2. Click Add new claim
3. Map additional directory attributes as needed
4. Updating corresponding attribute maps in the platform

Conditional Access

Control access using Microsoft Entra ID Conditional Access policies:

1. Go to Identity → Protection → Conditional Access
2. Creating a new policy targeting the application of the Platform
3. Configure conditions (location, device, risk level, etc.)
4. Set up appropriate access controls (grant, block, requires MFA)

Group-Based Access

Restrict access using Entra ID groups:

1. In the Enterprise app, go to Users and groups
2. Assign groups instead of individual users
3. Manage access by adding/removing users from assigned groups

For detailed troubleshooting and advanced configuration options, see SSO Overview guide.