Connect Microsoft Entra ID (formerly Azure AD) so your Microsoft 365 users sign in to ReFresh with their work accounts. ReFresh connects to Entra over OpenID Connect (OIDC).
Before you start:
Your domain is claimed and verified in ReFresh; see Setting up and managing SSO (Step 1: Claim and verify your domain).
You have permission to register applications in the Entra admin center (Application Administrator or similar).
In the ReFresh wizard, pick Microsoft Entra ID as your provider to reach the steps below.
In the wizard, select Microsoft Entra ID and OpenID Connect, then give the connection a display name.
1. Get your values from ReFresh
On the wizard's Add ReFresh to your IdP step, ReFresh shows what to paste into Entra. For OIDC that's the Redirect URI, the Scopes (openid, profile, email), and the Required claims (email, given_name, family_name, groups). Copy the Redirect URI now.
ReFresh: the "Add ReFresh to your IdP" step. Copy the Redirect URI and note the required claims.
2. Register the app in Entra
In the Entra admin center, go to App registrations → New registration. Name it (e.g. "ReFresh SSO"), and under Redirect URI choose Web and paste the Redirect URI from ReFresh. Register the app.
Entra, Register an application: name it, keep single-tenant, and paste the ReFresh Redirect URI as a Web platform.
3. Collect the details Entra generates
From the app's Overview, copy the Directory (tenant) ID and the Application (client) ID.
Entra: the app Overview. Copy the Application (client) ID and the Directory (tenant) ID.
Then go to Certificates & secrets → New client secret, add a secret, and copy its Value immediately; it's only shown once.
Entra: add a client secret (set a description and expiry).
Entra: copy the secret Value now; you can't see it again after leaving this page.
4. Assign roles: use App Roles (recommended)
Entra is the best-case provider for ReFresh's automatic (role slugs) method, because Entra App Roles produce a natively multi-valued roles claim, so a user can hold several ReFresh roles.
Create an app role per ReFresh role. In your App registration → App roles, create an app role whose Value is the ReFresh slug (e.g.
organization-admin). Copy slugs from View Role Slugs in the ReFresh wizard. Repeat per role.
Entra, Create app role: set the Value to the ReFresh role slug (here
organization-admin).Assign users/groups to the app role. In the matching Enterprise application → Users and groups, add an assignment and pick the app role. (Assigning a group is tidiest; create a security group for each role and assign the group.)
Entra: assign a user or group to the app role in the Enterprise application.
Grant admin consent if prompted, so the app can read the sign-in claims for your organisation.
Entra: grant admin consent on behalf of your organisation.
Entra then emits the assigned slugs in the roles claim. In ReFresh's Mappings step, choose Automatic and set the role-claim attribute to roles.
Prefer App Roles over the groups claim: The Entra groups claim carries opaque group object GUIDs (not names) and is capped; past ~200 groups Entra drops the list and returns an overage marker, and the sign-in can't read the user's groups (ReFresh detects this and warns). App Roles don't overflow. If you must use groups, map them manually by GUID. See Troubleshooting SSO and login.
5. Paste the details back into ReFresh
On the wizard's Paste IdP details step, enter the Entra Tenant ID (Directory ID), the Application (Client) ID, and the Client Secret (encrypted in your browser; ReFresh never stores it in the clear, and it can't be shown again after saving).
ReFresh: paste the Tenant ID, Client ID, and Client Secret.
Optionally expand Advanced to set the groups-claim name or the session lifetime.
ReFresh, advanced options: groups claim name and session lifetime (default 8 hours).
Then set your roles on the next step (see Setting up and managing SSO (Roles for SSO users)), test, and activate.
Entra-specific notes
Cross-tenant / guest accounts are blocked. ReFresh validates the Entra tenant ID (
tid) on every sign-in, so guests from another Entra tenant can't use this connection. This is a security feature, not a bug.If sign-in is refused with a security-policy message, it's usually a tenant mismatch or a guest account; see Troubleshooting SSO and login.