Single Sign-On (SSO) lets your team sign in to ReFresh with your existing identity provider (IdP): Microsoft Entra ID, Okta, Google Workspace, JumpCloud, or any provider that supports SAML or OpenID Connect. Once SSO is active for a domain, people who use an email address on that domain sign in through your IdP instead of a ReFresh password.
Two things you manage: domains and connections
SSO has two independent parts. Understanding the split is the key to everything else:
A domain is an email domain you own (e.g.
acme.com). You claim it and prove ownership once with a DNS record. A verified domain stays verified.A connection is a link to one identity provider, set up for a domain. You can create, test, activate, switch, and remove connections as often as you like.
Domain management is separate from connection management: Verifying a domain and configuring a connection are different jobs. You verify a domain once, then add, test, activate, switch, or remove connections against it as many times as you need, without ever re-verifying the domain. Switching identity providers never touches your DNS verification.
Each domain routes sign-ins through at most one active connection at a time. You can have others sitting alongside it as drafts or paused fallbacks (see Switching identity providers).
What you'll need
The Admin role in ReFresh (permission to manage SSO domains and connections).
Admin access to your identity provider, to create an application and read its details.
Access to your DNS provider to add a verification record.
Where SSO lives
Go to Settings → SSO (it opens on SSO Domains).
The SSO Domains page: enter your domain and click Claim Domain.
Step 1: Claim and verify your domain
Enter your email domain (e.g.
acme.com) and click Claim Domain.ReFresh gives you a DNS TXT record to add. At your DNS provider, create a TXT record:
Host / Name:
_refresh-verify.yourdomain.comValue: the token ReFresh shows you (begins with
refresh-verify=)
Back in ReFresh, click Verify Now.
The unverified domain card: copy the DNS TXT Host and Value, then click Verify Now.
Tip: DNS changes can take a few minutes to propagate. If verification fails on the first try, wait a moment and try again. Each domain can only be claimed by one organisation.
Once verified, activate the domain so it's live for routing. A domain has its own status (Awaiting Verification → Verified → Active) shown by a badge on the card.
A verified, activated domain, ready for you to add a connection.
Step 2: Add a connection
On a verified domain, click Add Provider to open the setup wizard. It has six steps.
Wizard step 1: pick your identity provider and protocol, and set a display name.
Step | What you do |
1. Provider | Pick your identity provider and protocol, and set a display name (shown on the sign-in button). |
2. Add ReFresh to your IdP | ReFresh shows the values to paste into your IdP (redirect/ACS URL, entity ID, required claims). You create the application in your IdP. |
3. Paste IdP details | Copy your IdP's values back into ReFresh (discovery/metadata URL, client ID/secret or SAML metadata). |
4. Mappings | Decide what role SSO users get (see Roles for SSO users). |
5. Test | Run a real sign-in in a new tab without affecting anyone. |
6. Activate | Turn SSO on for the domain. |
The exact fields in steps 2–3 depend on your provider; follow its guide:
Microsoft Entra ID: OpenID Connect
Okta: OpenID Connect (recommended) or SAML
Google Workspace: SAML
JumpCloud: OpenID Connect (recommended) or SAML
Other provider (SAML or OIDC): any other IdP
Prefer OpenID Connect (OIDC) where you have the choice: When a provider offers both, OIDC is recommended; SAML has a larger attack surface. Use SAML only when your provider doesn't support OIDC.
Roles for SSO users
When someone signs in via SSO for the first time, ReFresh creates their account automatically (just-in-time) and assigns a role. You control how that role is chosen on the Mappings step. There are two modes:
Permissive: you set a default role everyone gets, and can layer extra roles on top from IdP groups.
Strict: you set no default role, so only users who match a group/role mapping can sign in. Everyone else is blocked.
And two ways to assign roles from your identity provider. You can use either, or both (they're combined at sign-in):
Automatic (role slugs): ReFresh publishes a fixed list of role slugs (e.g.
org-admin). You attach a slug to your IdP groups/users and emit it in one claim/attribute; ReFresh grants the matching role on sign-in. Click View Role Slugs in the wizard to copy each role's slug. After setup there's nothing to maintain in ReFresh: add someone to the right IdP group and they get the role next login. Best for Entra, Okta, JumpCloud.Manual (group mappings): you map an IdP group value to a ReFresh role in a table inside ReFresh. Best for Google Workspace or directories that can't attach a custom role attribute.
One role or several? It depends on the claim you map: ReFresh puts no limit on roles per user, but your IdP does:
A single-valued attribute carries one role. The role-slug-in-a-custom-attribute path is perfect for one role per user but can't express several (a second group's value overwrites the first).
A multi-valued claim carries many. The groups claim is a list, so mapping groups (Manual) stacks a role per group. Microsoft Entra App Roles are the exception: that
rolesclaim is natively multi-valued.
Rule of thumb: one role → slug attribute (Automatic); multiple roles → map the groups list (Manual), unless your IdP emits a multi-valued role claim. Each provider guide says which path it supports.
Roles refresh on every sign-in: ReFresh recomputes a user's SSO roles at each login and reconciles: new roles granted, removed ones revoked. Change someone's IdP group and their roles follow on next sign-in. Roles you assigned manually are never touched.
The Mappings step: set a default role (Permissive) or none (Strict), and choose Automatic vs Manual.
"View Role Slugs": copy each role's slug to attach to your IdP groups or app roles.
Map on group IDs, not display names: Where your IdP gives a choice, map on the group's ID / GUID, not its display name. Display names can be renamed, which silently breaks the mapping. Matching is exact and case-sensitive.
SSO adds roles, doesn't take over: Turning on SSO never removes roles you assigned manually. SSO-managed roles layer on top of manual ones. (Full "identity provider owns all roles" lifecycle management is a separate, future capability.)
Step 3: Test before you activate
On the Test step, click Send Test Login. A new tab opens at your IdP; sign in with a real account, then return to ReFresh. You'll see whether it succeeded, a preview of the claims your IdP sent, and how they'd map to a role. You must pass a test before you can activate.
A successful test: the Success badge, a preview of the claims your IdP sent, and how they map to a role.
Step 4: Activate
On the Activate step, review what happens, tick the acknowledgement, and click Enable SSO.
The Activate step: acknowledge the lockout warning, then Enable SSO.
What happens when you enable SSO
Sign-ins for the domain are routed to your identity provider.
Password sign-in stops for accounts on that domain.
Anyone currently signed in on that domain is signed out and must sign back in via SSO.
New users are created automatically on first sign-in.
Don't lock yourself out: Before you rely on SSO, confirm a successful sign-in in a separate (incognito) browser window while keeping your current session open. If you're an admin whose own email is on the SSO domain, this is how you avoid being locked out by a misconfiguration.
Once SSO is active, people on the domain see a single sign-on button instead of the password field:
The sign-in page after SSO is enabled: the domain routes to the identity provider (Entra shown).
Managing a connection
Open a live or paused connection to reach Manage SSO.
A live connection on its domain: status pill, last-tested time, and Manage / Delete actions.
Edit configuration
Update details or role mappings and re-run a test. Saving details re-syncs with your IdP.
Disable and re-enable
Disable SSO turns routing off for the domain and re-opens password sign-in, a safe way to revert. It does not remove anyone or their roles. Re-enable SSO turns it back on.
Switching identity providers
You can migrate to a new provider with no downtime:
On the same verified domain, click Add Provider and set up the new connection.
Fully test it: this doesn't affect your live connection.
Activate it. ReFresh atomically switches routing to the new connection and pauses the old one (kept as a re-activatable fallback).
A domain with two connections: one Live, one Paused (a re-activatable fallback after switching providers).
Archive a connection
Archive SSO Connection permanently removes a connection. Archiving:
Deletes its identity-provider details and role mappings.
Removes the roles it granted (roles you assigned manually are kept).
Does not delete any user accounts.
If it was the active connection, SSO routing stops (password fallback returns) and affected users are signed out.
Archiving is not reversible.
Locked out?
There's deliberately no SSO password-bypass (that would undermine your SSO requirement). If your identity provider is down and admins can't sign in, contact ReFresh support: support can disable the connection, which re-opens password sign-in.
Provider guides
Microsoft Entra ID
Okta
Google Workspace
JumpCloud
Other provider (SAML or OIDC)
Troubleshooting
See Troubleshooting SSO and login for domain verification, sign-in denials, and mapping problems.