Microsoft Entra ID

This guide federates EUnifyer with Microsoft Entra ID (formerly Azure Active Directory). After setup, users in your Entra tenant sign in to EUnifyer with their existing Microsoft credentials. No new passwords, no parallel user database.

EUnifyer remains the platform identity layer for every internal service (Drive, Mail, Chat, Calendar, …). Entra ID becomes the upstream authority for who exists and who is allowed in.

Federation vs SCIM: pick the right one (or both):

• Federation (this guide) covers sign-in. Users land in EUnifyer the first time they sign in via Entra. New hires don’t exist in EUnifyer until they log in once; offboarded users lose access at next token refresh.
• SCIM provisioning covers the roster. Entra pushes user lifecycle changes to EUnifyer continuously, new hires appear before day one, offboarding propagates in minutes.

Most enterprise deployments configure both: federation for sign-in convenience, SCIM for roster correctness. You can ship federation first and add SCIM later.

Prerequisites

• An Entra ID tenant where you can register an enterprise application (Global Administrator or Application Administrator role).
• An EUnifyer organisation admin account (you need the Single Sign-On page in the admin panel).
• Your EUnifyer hostname (for example app.example.com).

Step 1: Get the redirect URI from EUnifyer

In EUnifyer, open Admin → Single Sign-On. If SSO is not configured yet, click Configure SSO, then pick the Microsoft Entra ID card.

Click Test connection once (any inputs are fine for now, leave them blank) to make EUnifyer print the redirect URI. It looks like this:

https://<your-eunify-host>/auth/realms/eunify/broker/org-<slug>-oidc/endpoint

Copy this URI. You will paste it into Azure in the next step.

Step 2: Register an application in Entra ID

1. Sign in to the Microsoft Entra admin centre .
2. Go to Applications → App registrations → New registration.
3. Fill in:
   • Name: EUnifyer
   • Supported account types: Accounts in this organisational directory only (single tenant) is the most common choice. Pick multi-tenant if you intend to onboard users from multiple Entra tenants.
   • Redirect URI: select Web and paste the URI you copied in Step 1.
4. Click Register.

On the Overview page, copy:

• Application (client) ID.
• Directory (tenant) ID.

Step 3: Create a client secret

1. In your new application, open Certificates & secrets → Client secrets → New client secret.
2. Description: EUnifyer federation. Expiry: 24 months (or your policy).
3. Click Add and immediately copy the Value column. You cannot read it again after leaving the page.

Store this secret in your secret manager. EUnifyer will need it in the next step.

Step 4: Grant API permissions

1. Open API permissions → Add a permission → Microsoft Graph → Delegated permissions.
2. Add:
   • openid
   • profile
   • email
   • offline_access
   • User.Read
3. Click Grant admin consent for <tenant>.

Note on offline_access: required for EUnifyer to refresh the upstream session without forcing the user back through Microsoft on every page load. Skipping it means users get redirected to log in again after their access token expires (around 60 minutes).

Step 5: Configure EUnifyer

Go back to Admin → Single Sign-On in EUnifyer, click Configure SSO, and pick Microsoft Entra ID. Fill in:

Click Test connection. EUnifyer fetches Entra’s OIDC discovery document and shows the resolved endpoints. A green panel means Azure is reachable and the tenant is valid.

Click Configure SSO to save.

Step 6: Test the sign-in flow

1. Open EUnifyer in a private browser window.
2. On the login page you should now see a Sign in with Microsoft button.
3. Click it. You are redirected to the standard Microsoft login screen.
4. Authenticate. You are redirected back into EUnifyer with a freshly provisioned account.

If anything looks off, click Test connection again on the SSO page. The red panel will name the exact discovery field that failed (most common: redirect URI mismatch, missing admin consent on offline_access).

Step 7: Optional: require Entra for everyone

Once the flow works for at least one test user, you can require Entra for the whole organisation:

1. Back in Admin → Single Sign-On, edit the configuration.
2. Turn on Require SSO for all org users.
3. Save.

From now on, anyone whose email matches one of the email domains is forced through Entra. Local password login is disabled for them.

Always keep one break-glass admin. Create a local-only admin account whose email is not in the federated domains, with a strong password and MFA. This is your way back in if Azure has an outage or the SSO config breaks.

Step 8: Map Entra groups to EUnifyer roles

If you use Entra security groups to govern access, map them onto EUnifyer roles so admin privileges follow group membership automatically.

1. In Entra ID, open your application’s Token configuration and add the groups claim with Group ID as the value (and Filter groups: Security groups).
2. Back in EUnifyer Admin → Single Sign-On, scroll to Group → role mapping.
3. Click Add rule and fill in:
   • Group claim value: the Entra group object ID (a UUID), e.g. c0ffee01-1234-….
   • EUnifyer role: the name of the realm role to grant, e.g. Admin.
4. Add more rules as needed and click Save mappings.

The next time someone in that Entra group signs in, EUnifyer will grant them the matching role automatically. Removing a user from the Entra group revokes the role at their next session refresh.

Step 9: Force sign-out an offboarded user

In Admin → Users, open the action menu on the row and pick Force sign-out. EUnifyer immediately invalidates the user’s Keycloak sessions. Any short-lived access token already issued (typically 60 seconds in our config) stops being refreshable, so the user loses access within seconds.

Combine this with disabling the user in Entra to get a clean cut.

Step 10: Map extra Entra claims onto user profiles

In Admin → Single Sign-On, scroll to Custom claim mappings. Use this table to pull additional attributes (department, employee number, cost centre, …) from the Entra token onto the EUnifyer user profile.

Each row maps an upstream claim name to a EUnifyer user attribute. Add the matching optional claims to your Azure app’s Token configuration first so the Entra token actually carries the value.

Step 11: Org-wide MFA enforcement

In Admin → Single Sign-On → Security policy, toggle Require multi-factor authentication for every org member. EUnifyer adds Keycloak’s CONFIGURE_TOTP required action to every org user with a Keycloak account; on their next sign-in they must set up an authenticator app.

Use Re-apply to all members after inviting new users so they pick up the current policy without you needing to flip the toggle off and on again.

Note: federated users still authenticate against Entra ID; this enforcement applies to local EUnifyer credentials and any service that exposes the EUnifyer realm directly.

What is not yet self-service

• SCIM bulk provisioning: pushing users in advance of their first sign-in is on the roadmap; today user accounts are created on first sign-in.
• Per-application audit view: sign-in events for each downstream application are visible on the Identity-Clients detail panel (“Recent sign-in events”). Realm-wide cross-app audit lives at Admin → Audit.

For SCIM, contact your EUnifyer onboarding engineer.

Common questions

Will users have to set up MFA again?. No. MFA stays with Entra. If your conditional access policy requires MFA, it is enforced at the Entra login screen exactly as it is today. EUnifyer trusts the assertion that comes back.

What if we disable a user in Entra?. Their access token stops being refreshable, and they are locked out of EUnifyer within minutes (next token refresh fails). For instant revocation, see the roadmap note above.

Can we federate multiple Entra tenants?. Not yet from a single EUnifyer organisation through the self-service UI. Contact onboarding if you need multi-tenant federation today.

What happens during an Entra outage?. Federated users cannot sign in until Entra is reachable again. Local break-glass accounts (created directly in EUnifyer, not via federation) continue to work. We strongly recommend keeping at least two break-glass admin accounts for exactly this reason.

Do we lose access to data if we later move off Entra?. No. EUnifyer accounts and data are entirely local. Federation is a sign-in shortcut, remove the Entra configuration and users fall back to local credentials (which they can set by triggering a password reset).