Set up OAuth single sign-on

Send people on your email domains to your identity provider (such as Okta, Microsoft Entra ID, Google or Auth0) instead of emailing them a sign-in link. Any OAuth 2.0 or OpenID Connect provider works. You can also give people their Flowstate role from their groups.

You need to be a Flowstate admin.

Before you start

• In your identity provider: rights to register an application.
• Allowed email domains: if Settings → Organisation → Authentication lists any Allowed Email Domains, your single sign-on domain must be one of them. See Sign-in settings.

1. Register Flowstate in your identity provider

1. Create a web application that uses the authorisation code flow with a client secret.
2. Allow the scopes openid, profile and email. If you’ll use groups for roles, also allow whatever your provider needs to include groups.
3. Keep the client ID, client secret, and the authorisation, token and UserInfo endpoint addresses for the next step.

OpenID Connect providers list the endpoint addresses at /.well-known/openid-configuration.

2. Add the provider in Flowstate

1. Go to Settings → Organisation → Single Sign On and select Add Provider.
2. Enter a Provider Name. People see it on the “Redirecting to …” screen.
3. Set Provider Type to OAuth 2.0. You can’t change this later.
4. Under Email Domains, type each domain this provider covers and press Enter after each one.
5. Switch Enabled on.
6. Enter the Client ID and Client Secret.
7. Enter the Authorization Endpoint, Token Endpoint and UserInfo Endpoint. Flowstate reads the person’s email from the UserInfo endpoint, so don’t leave it out.
8. Leave Scopes as openid profile email unless your provider needs more.
9. Select Create.

3. Add the redirect address to your identity provider

In your identity provider’s application, add this redirect address:

https://<your Flowstate address>/auth/sso/oauth/<provider ID>/callback

To find the provider ID, ask your Flowstate contact. Or try signing in with a test account on your domain: your identity provider shows the redirect_uri Flowstate sent. Copy that exact value into your application.

4. Test sign-in

1. Open a private browser window and go to the Flowstate sign-in page.
2. Enter the email address of a test user on your domain.
3. Check you see “Redirecting to …”, then sign in at your identity provider.

Done when: the test user lands in Flowstate.

What happens next

• Everyone on the provider’s email domains signs in through your identity provider.
• Someone who isn’t in Flowstate yet only gets an account if Automatically enroll new users is on, or if one of their groups gives them a role (below).
• Session Duration under Settings → Organisation → Authentication decides how long people stay signed in.
• Flowstate doesn’t ask for its own second factor after single sign-on, so enforce multi-factor authentication in your identity provider.

Give people roles from their groups (optional)

Each time someone signs in, Flowstate can set their organisation and role from their groups in your identity provider.

1. Go to Settings → Organisation → Single Sign On, open the provider’s menu and select Edit Provider. Group Mappings appears once the provider is saved.
2. Check Group Claim Attribute is the name of the claim that lists a person’s groups. It’s groups unless you change it.
3. Under Group Mappings, enter a Group Name exactly as your identity provider sends it.
4. Choose the Organization and the Role.
5. Select Add mapping. Repeat for each group.

Good to know:

• A role set by a group replaces any change you make by hand, the next time the person signs in.
• If someone is in several mapped groups for the same organisation, the mapping you added first wins.
• Signing in doesn’t reactivate someone you’ve suspended.
• Mappings can’t be edited. To change one, remove it and add it again.

Remove a group mapping

1. Go to Settings → Organisation → Single Sign On, open the provider’s menu and select Edit Provider.
2. Under Group Mappings, select the bin next to the mapping.
3. In Delete Group Mapping, select Delete.

To change the role someone already has, see Change someone’s name, email or role.

Change the client secret

Do this when you create a new client secret in your identity provider.

1. Go to Settings → Organisation → Single Sign On.
2. Open the provider’s menu and select Edit Provider.
3. In Client Secret, enter the new secret. If you leave it empty, the current secret is kept.
4. Select Update.

Update Flowstate as soon as you create the new secret. If the old secret stops working first, people can’t sign in until you do.

Switch off or delete a provider

To switch a provider off for now, turn off the switch on its row under Settings → Organisation → Single Sign On. People on its email domains get emailed sign-in links instead, as long as their domain is allowed under Allowed Email Domains. Turn the switch back on to send them to your identity provider again.

To delete a provider:

1. Go to Settings → Organisation → Single Sign On.
2. Open the provider’s menu and select Delete Provider.
3. Select Delete.

People on its email domains get emailed sign-in links instead, as long as their domain is allowed. Their accounts and roles stay. Anyone already signed in stays signed in until their session ends.

Deleting can’t be undone. To use the provider again, add it again and update the redirect address in your identity provider, because the new provider has a different ID.

If something’s not right

Your identity provider reports a redirect URI mismatch. Copy the redirect_uri from the error into your application.

“Sign-in with your identity provider failed. Please try again.” The client ID, client secret or one of the endpoint addresses is wrong.

“We could not set up your account. Please contact your administrator.” The person isn’t in Flowstate and Automatically enroll new users is off, or the UserInfo endpoint didn’t return their email.

“You do not have permission to use this service.” The provider has group mappings and none of the person’s groups match. With Microsoft Entra ID, groups are sent as object IDs unless you configure it to send names. If someone belongs to a very large number of groups, limit the groups Entra ID sends to the application.

People get an emailed link instead of going to your identity provider. Their domain isn’t in the provider’s Email Domains, or the switch on the provider’s row is off.

For your technical team

• Flow: authorisation code, with login_hint set to the email entered on the sign-in page.
• Redirect URI: https://<your Flowstate address>/auth/sso/oauth/<provider ID>/callback
• UserInfo: called with the access token. Flowstate reads email, name (or displayName) and sub (or id).
• Groups: read from the claim named in Group Claim Attribute, first from the ID token, then from the UserInfo response. A list or a single string both work.