Skip to content

Guide

Set up single sign-on (SSO)

Branding & settings · 5 min read

Single sign-on (SSO) lets members sign in to your community with their work account from your organization's identity provider (IdP), such as Okta, Microsoft Entra ID (formerly Azure AD), or Google. New setups use OIDC (OpenID Connect).

SSO setup isn't available from the menu at the moment. Admin → Settings doesn't list SSO. The rest of this article describes how SSO works.

Who can do this: Only the community owner can change SSO settings, and saving asks you to re-enter your password. Admins can view them. · Where: Web (admin console). Members use SSO on the web, and with OIDC also in the Mateflow app. · Plan: SSO depends on your platform plan. If yours doesn't include it, the SSO page says which plans do. If you move to a plan without SSO, SSO stops working and members sign in with your other methods; your settings are kept for when you upgrade.

Connect your identity provider with OIDC

Connecting your identity provider requires admin access to it.

  1. On the SSO Configuration tab of the SSO page, create a matching app in your IdP.
  2. Enter the Issuer URL, Client ID, Client Secret, and Scopes (comma separated), such as openid, email, profile.
  3. Click Save SSO Configuration and re-enter your password. Add the Redirect URI (callback URL) now shown under SP Information to your IdP app.
  4. Turn on the switch under SSO Status and save. SSO can't be turned on while the configuration is incomplete.

The SAML 2.0 option appears only on a community that already has SAML saved.

Run the SSO go-live checklist

Before you go live is a checklist on the SSO page, for the owner. It runs on the saved configuration:

  • Check the configuration: click Check.
  • Sign in with your own account: click Test sign-in. It goes to your identity provider and links it to your account, and you stay signed in.
  • Recovery admins: add at least one, so someone can still get in if the identity provider breaks. The checklist names anyone without a password, because recovery sign-in won't work for them.

Changing the identity provider settings clears the first two results, so run them again.

Choose an SSO login policy

Your SSO login policy decides which other sign-in methods stay available. On the Login Policy tab, choose a Login Mode:

  • SSO + Password: SSO or email and password. Social login is hidden.
  • SSO + Social + Password: all methods stay available.
  • SSO Only: everyone must use SSO. Password and social login, and email sign-up, are blocked.

You can't choose SSO Only until Check the configuration and Sign in with your own account have both passed. Add a recovery admin too, or a broken IdP setup could lock everyone out.

You can also set the SSO Button Text and Allowed Email Domains (comma separated). With domains set, an email outside them can't sign in with SSO, even on an account that's already linked. Only an exact domain matches, not its subdomains.

Turn JIT user provisioning on or off

JIT (just-in-time) user provisioning decides whether a first SSO sign-in can create a new account. It's the JIT User Provisioning switch on the User Sync tab, on by default.

  • On: someone new gets an account the first time they sign in with SSO.
  • Off: someone without an account can't sign in with SSO. Existing members can still use it: their first SSO sign-in links to the account with the same email.

The owner and staff are never linked by email. If they try, they see "This email belongs to a community staff account, so it can't be linked automatically." They sign in the usual way and click Link SSO under Settings → Security on the web.

Add recovery admins for SSO

Recovery admins can sign in with a password when SSO fails, even under SSO Only. Each one must be an owner or admin of your community and have a password on their account.

  1. On the User Sync tab, enter user IDs in Recovery Admin User IDs (comma separated). To find an ID, go to Admin → Members → All Members, click the person, and use Copy ID next to Member ID.
  2. Click Save SSO Configuration.

Under SSO Only, recovery admins click Recovery admin sign in on the sign-in page and enter their email and password. Two-factor authentication still applies, and each recovery sign-in is recorded and emailed to that admin.

Review SSO sign-ins in the audit log

The SSO audit log records SSO sign-ins, accounts created by JIT provisioning, configuration changes, and errors. The Audit tab shows Total SSO Users, SSO Logins (Last 30 Days), and Last SSO Login. Click Open Audit Logs for the full list, filterable by Action (SSO Login, Auto User Provisioning, Config Change, Account linked, Recovery sign-in, or Error), Start Date, and End Date.

What members see when they sign in with SSO

Members start on your community's sign-in page, click your SSO button (Use enterprise SSO by default), sign in at your IdP, and return signed in. Two-factor authentication still applies.

Sign-in must start on your community. Clicking the app tile in your IdP's portal (IdP-initiated sign-in) isn't supported.

In the Mateflow app, members can sign in with OIDC (the default button is Sign in with SSO). The app doesn't support SAML: under SSO Only it asks members to use the web; otherwise it shows only the other methods.

Troubleshooting SSO sign-in

Symptom: Members get an error when they start from the IdP's app portal. Why it happens: IdP-initiated sign-in isn't supported. Fix: Have members start on your community's sign-in page, or point the app tile's sign-on URL there if your IdP allows it.

Symptom: New people can't sign in with SSO after you turned off JIT. Why it happens: With JIT off, SSO doesn't create new accounts. They see "This community doesn't create new accounts through SSO. Contact your administrator." Fix: Turn JIT User Provisioning back on, or invite them first.

Symptom: Nobody can sign in under SSO Only. Why it happens: The IdP connection broke. Fix: A recovery admin signs in with Recovery admin sign in and fixes the settings.

Symptom: A member sees "Your identity provider didn't confirm this email. Contact your administrator." Why it happens: Your IdP didn't mark that person's email as confirmed, so Mateflow won't match it to an account. Fix: Check the email on their account in your IdP.

Related articles

Was this guide helpful?

Back to guides

Can't find what you need?

If you're a member of a community, its admins are the right people to ask. If you're building or running one on Mateflow, our team can help.