SSO Integration Guide (Microsoft Entra ID SAML 2.0)

Overview & Purpose

This guide provides step-by-step technical instructions for setting up Single Sign-On (SSO) between Sprout HR (utilizing Keycloak identity management) and Microsoft Entra ID (formerly Azure Active Directory) via the SAML 2.0 protocol.

Enabling SSO streamlines user management, enforces centralized corporate security, and allows employees to log into Sprout HR seamlessly using their existing Microsoft credentials.

💡 Integration Highlights:

• Centralized Security: Manage access rights directly through Microsoft Entra ID.
• Seamless Access: One-click corporate login for end-users.
• Automated Account Linking: Automatic profile linking using primary corporate email addresses.

What is Microsoft Entra ID?

Microsoft Entra ID (formerly known as Azure Active Directory or Azure AD) is Microsoft's cloud-based identity and access management (IAM) service. It acts as a centralized directory and security authority that manages user identities, passwords, authentication policies, and access rights across cloud applications and enterprise services.

Before You Begin

Ensure all required administrative roles and environment details are prepared before starting the setup.

People Required

Setup Timeline & Environments

• Estimated Setup Time: 1–2 business days (assuming coordinated availability between administrators).

Integration Overview & Responsibility Matrix

This guide walks through connecting Sprout HR (which uses Keycloak for authentication) with Microsoft Entra ID so that employees can log in to Sprout using their existing Microsoft credentials — a capability called Single Sign-On (SSO).

The flow works as follows: the Sprout Admin and Entra Admin exchange two pieces of information, then configure their respective systems. A test user then verifies the connection.

Handoff Flow:

Glossary of Technical Terms
Integration Steps

The Sprout Admin generates two values that will be handed off to the Entra Admin to configure Microsoft's side of the integration.

Step 1a — Enter the Alias and Display Name

The Alias is a short internal name (e.g. entra-saml). It will automatically form part of the Redirect URI, so choose something clear and consistent.

Step 1b — Set the Base URL

Update the Base URL to match your environment:

• Production: https://sso.sprout.ph
• Sandbox: https://sso-sandbox.sprout.ph

Step 1c — Note the Generated Values

Once saved, Keycloak will generate the following two values. Write these down — you will give them to the Entra Admin in the next step.

The Entra Admin sets up Sprout as a trusted application inside Microsoft Entra ID and configures how users will be authenticated.

Step 2a — Create the Application

• Enter a name for the app (e.g. Sprout).
• Select: Integrate any other application you don't find in the gallery (Non-gallery).
• Click Create.

Step 2b — Configure Single Sign-On with SAML

• In the app's left menu, go to Single sign-on.
• Select SAML as the sign-on method.
  
• In the Basic SAML Configuration section, enter the values received from the Sprout Admin:

• Identifier (Entity ID): paste the Entity ID from Step 1
• Reply URL (Assertion Consumer Service URL): paste the Redirect URI from Step 1
  

• Click Save.

Step 2c — Verify Attributes & Claims

In the Attributes & Claims section, confirm the following default mapping is in place:

Step 2d — Copy the Federation Metadata URL

In the SAML Certificates section, locate and copy the App Federation Metadata URL. It will look similar to:

https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}

Step 2e — Assign Users

Before any user can log in via SSO, they must be assigned to this Enterprise Application.

• In the app's left menu, go to Users and groups.
• Click Add user/group.
• Assign all users (or groups) who should be able to access Sprout via SSO.

The Sprout Admin now completes the Keycloak configuration using the Federation Metadata URL received from the Entra Admin.

Step 3a — Import Federation Metadata

• In the SAML entity descriptor field, paste the Federation Metadata URL received from the Entra Admin.
• Keycloak will automatically populate all required SSO settings (SSO URL, Logout URL, Identity Provider Entity ID).
• Verify that the fields have been filled in before saving.

Step 3b — Set the NameID Policy Format

• Navigate to: Identity Providers > Provider Details > Settings.
• Find the NameID Policy Format field.
• Change it from the default (Subject NameID) to Email.

Step 3c — Set the Authentication Flow

Navigate to Identity Providers > Provider Details > Settings > Advanced Settings.

• Ensure the built-in 'First Broker Login' flow is NOT used.
• Set the First Login Flow Override to the custom SAML flow (e.g. saml-login).

Then go to Authentication > Flows and confirm that your selected flow includes all of the following steps:

A test user now verifies that the integration is working correctly. This user must have an active account in both Sprout and Entra, using the same email address.

Step 4a — Initiate SSO Login

• On the Sprout login page, look for the button below the standard login form (e.g. Continue with entra-saml).
• Click this button. You will be redirected to the Microsoft login page.
• Sign in with your Microsoft/Entra credentials.

Step 4b — First-Time Account Linking

If this is your first time logging in via SSO, Sprout will detect your existing account and prompt you to link it:

1. A message will appear: 'We detected an existing user in Sprout with the same email address.'
2. Click Continue to proceed with account linking.
   
3. An email will be sent to your address with a Confirm Account Linking button.
   
4. Open the email and click Confirm Account Linking. The link expires in 5 minutes.
5. You will be redirected to the Sprout dashboard. Setup is complete!

Optional: Enable Access via Microsoft MyApps

In addition to logging in directly from the Sprout URL, users can also launch Sprout from their Microsoft MyApps portal (myapps.microsoft.com). This is especially useful in organisations where employees use MyApps as a central launchpad for all their work applications.

5a — Set the Sign-On URL

• Go to Single sign-on > Basic SAML Configuration > Edit.
• Enter the Sign on URL field with your Sprout HR URL (e.g. https://sprout.hrhub.ph).
• Save changes.
  

5b — Make the App Visible to Users

• Go to Properties in the app's left menu.
• Set Visible to users? to Yes.
• Optionally, upload the Sprout logo (available from your Sprout account manager) for easier identification in MyApps.
  

Once configured, all assigned users will see the Sprout tile when they visit https://myapps.microsoft.com.

Optional: Auto-Redirect to Microsoft Login

By default, users see the standard Keycloak login page with an option to continue via SSO. This optional configuration skips the Keycloak page entirely and sends users straight to the Microsoft login page.

• Alias: enter the same alias used in Step 1 (e.g. entra-saml).
• Default Identity Provider: enter the same alias again.
• Save.

To verify: open your Sprout HR URL. You should be taken directly to the Microsoft sign-in page instead of the Keycloak login page.

Quick Reference — Values Exchanged

Use this table as a checklist during the setup session to track the values that need to be shared between admins.

Troubleshooting

Below are the most common issues encountered during and after setup. For issues not listed here, contact Sprout Support.