OAuth 2.0 Setup

Configure OAuth 2.0 authentication so your team can sign in to Flowstate through a third-party authorization server. Use this when your identity provider does not support SAML or when you need to integrate with a custom OAuth provider.

Supported Providers

Flowstate supports any OAuth 2.0-compliant authorization server that implements the Authorization Code flow. This includes:

• Custom OAuth 2.0 authorization servers
• Identity providers with OAuth 2.0 support (Okta, Auth0, Keycloak, etc.)
• Cloud provider identity platforms (Azure AD/Entra ID, Google Cloud Identity)

TIP

If your identity provider supports SAML 2.0, we recommend using the SAML integration instead. SAML provides richer attribute mapping and is the industry standard for enterprise SSO.

Step 1: Create an Auth Provider in Flowstate

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

Flowstate generates a Redirect URI that you will need when configuring your OAuth provider:

Field	Example Value
Redirect URI	https://acme.flowstate.inc/auth/oauth/callback

Copy this value -- your OAuth provider needs it to send users back to Flowstate after authentication.

Step 2: Register Flowstate in Your OAuth Provider

Create a new OAuth 2.0 application (or "client") in your authorization server:

1. Set the application type to "Web Application"
2. Set the Redirect URI (also called "Callback URL") to the value from Step 1
3. Set the grant type to "Authorization Code"
4. Save the application

Your OAuth provider will issue:

Field	Description
Client ID	Public identifier for the Flowstate application
Client Secret	Confidential secret for token exchange

You also need the following endpoint URLs from your provider's documentation:

Endpoint	Description
Authorization URL	Where users are redirected to authenticate
Token URL	Where Flowstate exchanges the auth code for tokens
User Info URL	Where Flowstate retrieves user profile attributes

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 Client ID, Client Secret, and the three endpoint URLs
4. Click Save

Example Configuration

Field	Value
Client ID	flowstate-prod-client
Client Secret	wJalrXUtnFEMI/K7MDENG/bPxRfi...
Authorization URL	https://auth.acme.com/oauth2/authorize
Token URL	https://auth.acme.com/oauth2/token
User Info URL	https://auth.acme.com/oauth2/userinfo

Step 4: Configure Scopes

Scopes determine what user information Flowstate requests from your OAuth provider. Configure the scopes in the Scopes field of the provider settings.

At a minimum, Flowstate needs:

Scope	Purpose
openid	Required for OpenID Connect compatibility
email	Retrieve the user's email address
profile	Retrieve the user's name and display info

Enter scopes as a space-separated string:

openid email profile

If your provider supports group claims, add the appropriate scope:

openid email profile groups

TIP

The exact scope names vary by provider. Check your OAuth provider's documentation for the correct scope values.

Step 5: Bind Email Domains

Domain binding tells Flowstate which users should be routed to this OAuth 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

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

WARNING

Each email domain can only be bound to one auth provider at a time. If the domain is already bound to a SAML or another OAuth provider, remove it from that provider first.

Group Claims Configuration

If your OAuth provider includes group membership in the user info response or the ID token, Flowstate can use those claims for role mapping.

1. In the provider settings, scroll to Group Claims
2. Set the Groups Claim Name to the JSON field name your provider uses (e.g., groups, roles, or cognito:groups)
3. Configure group-to-role mappings the same way as SAML group mapping

Example User Info Response

{
  "sub": "user-12345",
  "email": "jane.chen@acme.com",
  "name": "Jane Chen",
  "given_name": "Jane",
  "family_name": "Chen",
  "groups": ["Flowstate-Admins", "Engineering"]
}

In this example, set the Groups Claim Name to groups. If the user is in Flowstate-Admins and you have a mapping from Flowstate-Admins to the Admin role, the user will be assigned the Admin role.

Testing the Integration

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 OAuth provider's login page
5. Authenticate and consent to the requested scopes
6. Confirm sign-in -- you should be returned to Flowstate and signed in
7. Check user attributes -- navigate to Settings > Users and verify the test user's name, email, and role

TIP

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

Troubleshooting

User is not redirected to the OAuth provider

• Verify the email domain is bound to the correct provider in Settings > Authentication > Auth Providers
• Confirm the domain binding is saved
• Check that the user is entering an email with the correct domain

"Invalid state" or "State mismatch" error

• Ensure the user is not using a stale bookmark or a link from an expired session
• Confirm the Redirect URI in your OAuth provider matches exactly: https://your-tenant.flowstate.inc/auth/oauth/callback

"Invalid client" error during token exchange

• Verify the Client ID and Client Secret in Flowstate match the values from your OAuth provider
• Confirm the client is not expired or disabled in your OAuth provider

User is authenticated but has no role

• Check that the OAuth provider is returning group claims in the user info response or ID token
• Verify the Groups Claim Name matches the actual field name in the response
• Confirm your group-to-role mappings match the group names exactly (case-sensitive)

Token exchange timeout

• Verify the Token URL is correct and reachable from Flowstate's servers
• Check that your OAuth provider's firewall or network rules allow inbound connections from Flowstate