SSO Setup | BttrForm

Single Sign-On (SSO) lets your team members authenticate with BttrForm using your organization's existing identity provider. Instead of managing separate BttrForm passwords, your team logs in with the same credentials they use for everything else. This simplifies access management, strengthens security, and gives IT administrators centralized control over who can access BttrForm.

SSO Overview

BttrForm supports two SSO protocols:

SAML 2.0 -- The industry standard for enterprise SSO. Works with Okta, Azure AD, OneLogin, PingFederate, and most identity providers.
OAuth 2.0 / OpenID Connect -- A lighter-weight option that works with Google Workspace, Microsoft Entra ID, and other OAuth-compatible providers.

Which Protocol Should You Use?

Criteria	SAML 2.0	OAuth / OIDC
Enterprise IdP support	Excellent	Good
Setup complexity	Moderate	Low
Attribute mapping	Full control	Limited
Session management	IdP-controlled	Token-based
Best for	Large organizations	Small to medium teams

Plan Requirement

SSO is available on Business and Enterprise plans. Enterprise plans include SAML 2.0 support with custom attribute mapping. Business plans support OAuth-based SSO with Google and Microsoft.

SAML 2.0 Configuration

SAML 2.0 provides the most robust SSO experience with full control over attribute mapping, group-based access, and IdP-initiated login flows.

Prerequisites

Before starting, you will need:

Admin access to your identity provider (Okta, Azure AD, etc.)
Admin or Owner role in your BttrForm workspace
Your BttrForm SSO metadata URL (found in Settings > Security > SSO)

Step 1: Get BttrForm Service Provider Details

Navigate to Settings > Security > SSO in your BttrForm dashboard. You will find the Service Provider (SP) details that your identity provider needs:

Entity ID:          https://auth.bttrlabs.com/saml/metadata
ACS URL:            https://auth.bttrlabs.com/saml/acs
SLO URL:            https://auth.bttrlabs.com/saml/slo
Name ID Format:     urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Metadata URL:       https://auth.bttrlabs.com/saml/metadata.xml

Step 2: Create an Application in Your IdP

In your identity provider, create a new SAML application using the SP details above. Here is an example using Okta:

Log in to the Okta Admin Console.
Go to Applications > Create App Integration.
Select SAML 2.0 and click Next.
Enter "BttrForm" as the app name.
Set the Single sign-on URL to the ACS URL above.
Set the Audience URI (SP Entity ID) to the Entity ID above.
Configure attribute statements (see below).
Click Finish.

Step 3: Configure Attribute Mapping

BttrForm expects the following SAML attributes:

SAML Attribute	BttrForm Field	Required
`email`	User email	Yes
`firstName`	First name	Yes
`lastName`	Last name	Yes
`groups`	Team roles	No
`department`	Workspace	No

<!-- Example SAML Attribute Statement -->
<saml:AttributeStatement>
  <saml:Attribute Name="email">
    <saml:AttributeValue>jane@company.com</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="firstName">
    <saml:AttributeValue>Jane</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="lastName">
    <saml:AttributeValue>Smith</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="groups">
    <saml:AttributeValue>bttrform-admins</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Step 4: Upload IdP Metadata to BttrForm

Download the IdP metadata XML from your identity provider.
In BttrForm, go to Settings > Security > SSO.
Click Upload IdP Metadata and select the XML file.
BttrForm parses the metadata and displays the IdP details for confirmation.
Click Save Configuration.

IdP Entity ID:      https://your-org.okta.com/app/abc123
SSO URL:            https://your-org.okta.com/app/abc123/sso/saml
Certificate:        Valid until 2028-01-15
Status:             Configured (not yet enforced)

Pro Tip

Do not enforce SSO immediately after configuration. First, test with a small group of users to confirm everything works correctly. Once verified, you can enforce SSO for the entire organization.

OAuth Provider Setup

For teams that prefer a simpler setup, BttrForm supports OAuth-based SSO with popular identity providers.

Google Workspace

Go to Settings > Security > SSO.
Click Connect Google Workspace.
Sign in with your Google Workspace admin account.
Authorize BttrForm to read user profile information.
Configure domain restrictions (optional -- limit to your organization's domain).

Provider:    Google Workspace
Domain:      company.com
Status:      Connected
Users:       Automatically provisioned on first login

Microsoft Entra ID (Azure AD)

Go to Settings > Security > SSO.
Click Connect Microsoft.
Sign in with your Microsoft admin account.
Grant the requested permissions (User.Read, openid, profile, email).
Configure tenant restrictions if needed.

Provider:    Microsoft Entra ID
Tenant:      company.onmicrosoft.com
Status:      Connected
App ID:      a1b2c3d4-e5f6-7890-abcd-ef1234567890

Testing SSO

Before enforcing SSO for your entire organization, test the configuration thoroughly.

Test Checklist

IdP-initiated login -- Log in from your identity provider's app dashboard and verify you land on the correct BttrForm workspace.
SP-initiated login -- Go to app.bttrlabs.com/login, click the SSO button, and verify the redirect to your IdP works.
New user provisioning -- Have a user who has never logged into BttrForm authenticate via SSO. Verify their account is created with the correct role.
Attribute mapping -- Confirm that first name, last name, and email are populated correctly in BttrForm.
Logout -- Log out from BttrForm and verify the session is terminated. If using SAML SLO, confirm the IdP session is also terminated.

# Verify SSO configuration via API
curl https://api.bttrlabs.com/v1/workspaces/{workspace_id}/sso/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "sso_enabled": true,
  "protocol": "saml",
  "idp_entity_id": "https://your-org.okta.com/app/abc123",
  "enforced": false,
  "last_tested": "2026-02-07T14:30:00Z",
  "test_result": "success"
}

Enforcing SSO

Once testing is complete, enforce SSO so that all workspace members must authenticate through your identity provider:

Go to Settings > Security > SSO.
Toggle Enforce SSO to on.
Confirm by typing your workspace name.

Before Enforcing

When SSO is enforced, team members can no longer log in with email and password. Ensure all team members are provisioned in your identity provider before enabling enforcement. The workspace Owner always retains password-based access as a recovery mechanism.

Troubleshooting

"SAML Response Signature Invalid"

This usually means the IdP certificate in BttrForm is outdated. Re-download the IdP metadata XML and upload it again in Settings > Security > SSO.

"User Not Found in Identity Provider"

The user attempting to log in is not assigned to the BttrForm application in your IdP. Add them to the application in Okta, Azure AD, or your respective provider.

This can occur when the ACS URL is misconfigured. Verify that the ACS URL in your IdP exactly matches https://auth.bttrlabs.com/saml/acs with no trailing slash.

"Email Mismatch"

The email in the SAML assertion does not match any BttrForm account. Ensure the email attribute in your IdP maps to the user's actual email address and that the email domain matches your configured domain restrictions.