SAML 2.0 Setup

Configure SAML 2.0 single sign-on so your team can authenticate to Flowstate through your identity provider (IdP). Once configured, users with matching email domains are automatically redirected to your IdP when they sign in.

Prerequisites

Before you begin, confirm that you have:

• Flowstate admin access -- you need the SETTINGS_AUTH_PROVIDERS permission to create and manage auth providers
• IdP admin access -- you need to create a SAML application in your identity provider (Okta, Azure AD/Entra ID, OneLogin, Google Workspace, etc.)
• Email domain ownership -- you must own the email domain(s) you plan to bind to SAML (e.g., acme.com)

Step 1: Create an Auth Provider in Flowstate

1. Navigate to Settings > Authentication > Auth Providers
2. Click Add Provider
3. Select SAML 2.0 as the provider type
4. Enter a display name (e.g., "Okta SSO" or "Azure AD")
5. Click Create

Flowstate generates the following values for your IdP configuration:

Field	Example Value
SP Entity ID	https://acme.flowstate.inc/auth/saml/sp
ACS URL	https://acme.flowstate.inc/auth/saml/callback
SLO URL	https://acme.flowstate.inc/auth/saml/logout

Copy these values -- you will need them when configuring your IdP.

Step 2: Configure Your Identity Provider

Create a new SAML application in your IdP using the SP values from Step 1. The exact steps vary by provider, but the general process is:

1. Create a new SAML 2.0 application
2. Set the SP Entity ID (also called "Audience URI" or "Identifier")
3. Set the ACS URL (also called "Reply URL" or "Single Sign-On URL")
4. Configure the Name ID format as urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
5. Save the application and copy the IdP metadata

Your IdP will provide three values that you need to enter back in Flowstate:

Field	Description
IdP Entity ID	The unique identifier for your IdP (also called "Issuer")
SSO URL	The URL Flowstate redirects users to for authentication
Signing Certificate	The X.509 certificate used to verify SAML assertions

Step 3: Complete the Provider Configuration

Back in Flowstate:

1. Navigate to Settings > Authentication > Auth Providers
2. Click on the provider you created in Step 1
3. Enter the IdP Entity ID, SSO URL, and paste the X.509 Certificate (PEM format)
4. Click Save

-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
(your IdP's signing certificate in PEM format)
...
-----END CERTIFICATE-----

Step 4: Bind Email Domains

Domain binding tells Flowstate which users should be routed to this SAML provider based on their email address.

1. In the provider settings, scroll to Domain Bindings
2. Click Add Domain
3. Enter the email domain (e.g., acme.com)
4. Click Save

TIP

You can bind multiple domains to the same provider. For example, if your organization uses both acme.com and acme.co.uk, add both domains.

Once a domain is bound, any user who enters an email address with that domain during sign-in will be redirected to your SAML IdP instead of receiving a magic link.

WARNING

Each email domain can only be bound to one auth provider at a time. If acme.com is already bound to another provider, you must remove it from that provider first.

Attribute Mapping

Flowstate reads user attributes from the SAML assertion. Configure your IdP to include the following attributes:

Required Attributes

SAML Attribute	Maps To	Description
NameID	User email	Must be the user's email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	First name	User's given name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	Last name	User's family name

Optional Attributes

SAML Attribute	Maps To	Description
http://schemas.xmlsoap.org/claims/Group	Groups	Group memberships for role mapping
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Display name	Full display name (fallback)

TIP

If your IdP uses different attribute URIs, you can configure custom attribute mappings in the Attribute Mapping section of the provider settings.

Group-to-Role Mapping

If your IdP sends group claims in the SAML assertion, you can map those groups to Flowstate roles. This allows you to manage Flowstate access from your IdP rather than configuring roles individually in Flowstate.

1. In the provider settings, scroll to Group-to-Role Mapping
2. Click Add Mapping
3. Enter the IdP Group Name exactly as it appears in the SAML assertion (e.g., Flowstate-Admins)
4. Select the Flowstate Role to assign (e.g., Admin, Editor, Viewer)
5. Click Save

IdP Group Name	Flowstate Role	Effect
Flowstate-Admins	Admin	Full access including settings
Flowstate-Editors	Editor	Create and modify plans and data
Flowstate-Viewers	Viewer	Read-only access to plans and data

WARNING

If a user belongs to multiple mapped groups, they receive the highest-privilege role. For example, if a user is in both Flowstate-Viewers and Flowstate-Admins, they are assigned the Admin role.

Testing the Integration

Before rolling out to your entire organization, test with a single user:

1. Verify domain binding -- confirm the domain appears in the provider's Domain Bindings section
2. Open an incognito window and navigate to https://your-tenant.flowstate.inc
3. Enter a test user's email that matches the bound domain
4. Confirm redirect -- you should be redirected to your IdP's login page
5. Authenticate at the IdP and confirm you are returned to Flowstate and signed in
6. Check user attributes -- navigate to Settings > Users and verify the test user's name and role are correct

TIP

Use an incognito/private window for testing to avoid cached sessions interfering with the flow.

Troubleshooting

User is not redirected to the IdP

• Verify the email domain is bound to the correct provider in Settings > Authentication > Auth Providers
• Confirm the domain binding is saved (not just entered but unsaved)
• Check that the user is entering an email with the correct domain

"Invalid SAML Response" error after IdP authentication

• Verify the IdP Entity ID in Flowstate matches the Issuer in the SAML response
• Confirm the ACS URL in your IdP matches exactly: https://your-tenant.flowstate.inc/auth/saml/callback
• Check that the X.509 certificate in Flowstate matches the signing certificate in your IdP
• Ensure the IdP clock is synchronized (SAML assertions have a time window)

User is authenticated but has no role or wrong role

• Check that the IdP is sending group claims in the SAML assertion
• Verify the group names in your group-to-role mappings match exactly (case-sensitive)
• If no group mapping matches, the user receives the default role configured for the provider

Certificate rotation

When your IdP rotates its signing certificate:

1. Obtain the new certificate from your IdP
2. Update the certificate in Settings > Authentication > Auth Providers > (your provider)
3. Save and test immediately

DANGER

If you do not update the certificate before the IdP starts using the new one, all SAML authentications will fail for users on that provider. Coordinate the timing with your IdP admin.