Set up SAML single sign-on

Send people on your email domains to your SAML 2.0 identity provider (such as Okta, Microsoft Entra ID, Google Workspace or OneLogin) instead of emailing them a sign-in link. You’ll need someone who can create applications in your identity provider.

You need to be a Flowstate admin.

Before you start

• In your identity provider: rights to create a SAML 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. Create a SAML application in your identity provider

In your identity provider, create an application for Flowstate and set these values. The names vary between providers.

Keep the application’s SAML sign-in URL and signing certificate for the next step.

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 SAML 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. In Entity ID, enter the same identifier you set as the audience in step 1.
7. In SSO URL, paste your identity provider’s SAML sign-in URL.
8. In Certificate (PEM), paste the signing certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
9. Leave Want Assertions Signed on.
10. Select Create.

3. Add the callback address to your identity provider

In your identity provider’s application, set the Assertion Consumer Service URL to:

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

To find the provider ID, ask your Flowstate contact. Or go to the Flowstate sign-in page and enter an email address on your domain: the address your browser is sent to ends in /auth/sso/saml/<provider ID>.

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. Otherwise, invite them first. See Invite people and manage their access.
• Give people their role in Flowstate. Don’t add group mappings to a SAML provider. See Change someone’s name, email or role.
• 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.

Replace the signing certificate

Flowstate holds one certificate per provider. When your identity provider moves to a new signing certificate, change it in Flowstate at the same time. People can’t sign in between the two changes.

1. Go to Settings → Organisation → Single Sign On.
2. Open the provider’s menu and select Edit Provider.
3. Paste the new certificate into Certificate (PEM).
4. Select Update.

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 Assertion Consumer Service URL in your identity provider, because the new provider has a different ID.

If something’s not right

“Sign-in with your identity provider failed. Please try again.” The certificate is wrong, the Entity ID doesn’t match the audience in your identity provider, or the assertion isn’t signed.

“We could not set up your account. Please contact your administrator.” Your identity provider isn’t sending an email attribute, or the person isn’t in Flowstate and Automatically enroll new users is off.

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.

“This authentication provider is not available. Please contact your administrator.” The provider was switched off or deleted while the person was signing in.

For your technical team

• Assertion Consumer Service: https://<your Flowstate address>/auth/sso/saml/<provider ID>/callback, HTTP-POST binding.
• Sign-in start: https://<your Flowstate address>/auth/sso/saml/<provider ID>, HTTP-Redirect binding.
• Audience: must equal the Entity ID.
• Email attribute: email, mail or urn:oid:0.9.2342.19200300.100.1.3. NameID isn’t used as the email.
• Name attribute: displayName or urn:oid:2.16.840.1.113730.3.1.241.
• Clock skew: up to 5 seconds.
• Not supported: service provider metadata URL, single logout and encrypted assertions.