Enterprise SSO

Enterprise SSO lets your team sign in to Formael using your existing corporate identity provider — Okta, Google Workspace, Azure AD, or any standard OIDC or SAML 2.0 provider. Once configured, new members are provisioned automatically on their first login with no invitations or manual setup.

Enterprise plan required. SSO configuration is available exclusively on the Enterprise plan. Non-enterprise organizations can see this section with an upgrade prompt.

How It Works

Setting up SSO has three steps:

Claim your domain — prove you own your company's email domain
Configure your identity provider — tell Formael how to connect to your IdP
Activate JIT provisioning — switch your membership strategy to SSO

Once active, when someone from your company signs in to Formael for the first time, they're automatically added to your organization. Subsequent logins are seamless — no extra steps for users.

Step 1 — Claim Your Domain

Go to Settings → Enterprise SSO → Verified Domains and click Claim Domain.

Enter your company domain (e.g. acme.com) and click Claim.

Formael will show you a DNS TXT record to add:

Type:   TXT
Name:   @
Value:  formael-verify=<unique-token>
TTL:    300

Add this record to your DNS provider (Route 53, Cloudflare, GoDaddy, etc.) and then click Verify Now. DNS propagation typically takes a few minutes but can take up to 48 hours.

Once verified, the domain shows a green Active badge. Verification is a one-time step — you don't need to re-verify unless you remove and re-claim the domain.

Multiple domains: You can claim more than one domain. If your company uses acme.com and acme-labs.io, claim both.

Step 2 — Configure Your Identity Provider

Go to Settings → Enterprise SSO → Identity Providers and click Add Identity Provider.

Choose your IdP type:

OIDC (OpenID Connect)

Use this for: Google Workspace, Okta, Auth0, Ping Identity, and most modern IdPs.

You'll need:

Discovery URL — your IdP's OpenID Connect discovery document URL
(e.g. https://accounts.google.com/.well-known/openid-configuration)
Client ID — the application client ID from your IdP
Client Secret — the application client secret from your IdP

OIDC Setup by Provider

Google Workspace
Create an OAuth 2.0 application in Google Cloud Console. Set the authorized redirect URI to the value shown in Formael's SSO settings page.
Discovery URL: https://accounts.google.com/.well-known/openid-configuration

Okta
Create an OIDC Web Application in Okta Admin. Set the sign-in redirect URI to the value shown in Formael's SSO settings page.
Discovery URL: https://<your-domain>.okta.com/.well-known/openid-configuration

Azure AD
Create an App Registration in Azure. Use the "OpenID Connect" protocol.
Discovery URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

SAML 2.0

Use this for: Azure AD (SAML), ADFS, Ping, OneLogin, and legacy enterprise IdPs.

You'll need:

Entity ID — your IdP's SAML entity identifier (also called Issuer)
SSO URL — your IdP's SAML Single Sign-On endpoint
Signing Certificate — your IdP's public X.509 certificate (PEM format)

Formael's Service Provider metadata (Entity ID and ACS URL) is shown on the IdP configuration page — copy these into your IdP's application settings.

Linking to a Domain

When creating your IdP, you can optionally link it to one of your verified domains. This associates the IdP with users from that domain, enabling automatic routing — users with @acme.com emails are directed to the correct login flow without needing to type their domain.

Security Notes

Client secrets and signing certificates are encrypted at rest and never returned by the API — the console shows only whether a secret is configured and when it was last updated
To rotate a secret, open the IdP from the list, click Edit, and enter the new secret — the old secret is immediately replaced
Secret fields on the edit form are intentionally blank — this is not an error; it prevents displaying credential values in the browser

Step 3 — Activate SSO Provisioning

Once your IdP is active, go to Settings → Provisioning and switch to SSO / JIT Provisioning.

From this point:

Users from your organization who sign in using your IdP are automatically provisioned as Members
They appear in your member list immediately after their first login with SSO shown in the "How joined" column
No invitations are required

For details on provisioning strategies and how to switch between them, see Provisioning Settings.

Role Mapping (Optional)

By default, users provisioned via SSO receive the Member role. If you want to assign roles based on groups in your IdP, you can configure role mappings on your identity provider.

Role mappings translate an IdP group name to a Formael role:

IdP Group	Formael Role
`platform-admins`	Admin
`platform-members`	Member
`platform-readonly`	Viewer

When a user logs in, Formael checks their IdP group memberships and assigns the highest matching role. If no mapping applies, they receive Member by default.

Safety constraints on role mapping:

The Owner role is never assigned through SSO role mapping
Existing Owners are never demoted by a role mapping change

Role mapping configuration is available in the identity provider settings under Settings → Enterprise SSO → Identity Providers → Edit.

Managing Your SSO Configuration

Updating an IdP

Go to Settings → Enterprise SSO → Identity Providers, find your IdP, and click Edit. Changes take effect immediately — users signing in after the update use the new configuration.

Deleting an IdP

Open the IdP from the list and click Delete at the bottom of the page. Confirm the dialog.

Deleting an IdP:

Stops new SSO logins immediately
Does not remove existing members who joined via SSO
Requires switching away from SSO JIT provisioning if it's your active strategy

Removing a Domain

Go to Settings → Enterprise SSO → Verified Domains and click Remove next to the domain.

Removing a domain does not affect existing members. If you plan to re-claim the domain later, you'll need to go through domain verification again.

Emergency: Disabling SSO

If you need to immediately stop SSO access, go to Settings → Provisioning and switch to Manual Invitation. This stops new members from being provisioned via SSO instantly. Existing SSO members retain their access.

For a full lockdown (e.g. suspected IdP compromise), contact [email protected] immediately.

Troubleshooting

Domain shows "Failed" after clicking Verify Now
The DNS lookup encountered an error. Remove the domain and re-claim it to get a fresh verification token, then add the new TXT record to DNS.

Domain shows "Pending" after clicking Verify Now
DNS propagation hasn't completed yet. The TXT record may take up to 48 hours to propagate globally. Click Verify Now again after waiting.

Users are not being provisioned after SSO login
Check that:

The provisioning strategy is set to SSO / JIT Provisioning in Settings → Provisioning
The IdP is showing as Active in Settings → Enterprise SSO → Identity Providers
The user's email domain matches your verified domain

SSO login redirects back with an error
This usually indicates a misconfigured client secret, expired certificate, or incorrect redirect URI in your IdP. Open the IdP in Formael, click Edit, re-enter the client secret or certificate, and try again.

Plan Details

Enterprise SSO is available exclusively on the Enterprise plan.

Contact sales →

←

Provisioning Settings