Single sign-on (SSO) for organizations

You can enable SSO on a per-organization basis using your existing identity provider. Supported providers are OIDC, Microsoft Entra ID (formerly Azure AD), Google, and GitHub.

Prerequisites#

A Formance Cloud organization and access to fctl
A client application created in your identity provider (Client ID and Client Secret)

When creating the app in your IdP, set the redirect URI to your membership endpoint callback: <membership_uri>/api/authorize/callback. See step 1 to determine your membership URI.

Determine your membership URI#

Use the same membership URI you pass to fctl login.

Bash

fctl login --membership-uri https://membership.BASE_URL/api

The SSO redirect URI to register in your IdP is therefore:

https://membership.BASE_URL/api/authorize/callback

After you create the SSO configuration, the exact redirect URI is also displayed in the UI.

Configure the authentication provider#

The command format is:

Bash

fctl cloud organizations authentication-provider configure <type> <name> <client-id> <client-secret> \
  [--oidc-issuer <issuer-url>] [--microsoft-tenant <tenant-id-or-domain>]

type: one of oidc, microsoft, github, google
name: human-friendly provider name shown to users
client-id / client-secret: values from your IdP app
--oidc-issuer: required for oidc (e.g., https://accounts.example.com)
--microsoft-tenant: required for microsoft (tenant ID or verified domain)

Microsoft Entra ID#

To configure Microsoft Entra ID as your identity provider, use the oidc type with the Microsoft issuer URL.

The --oidc-issuer must follow this format:

https://login.microsoftonline.com/<tenant-id>/v2.0

Replace <tenant-id> with your Entra tenant ID.

Bash

fctl cloud organizations authentication-provider configure \
  oidc "msentra" <client-id> <client-secret> \
  --oidc-issuer https://login.microsoftonline.com/<tenant-id>/v2.0

Users must have an email address configured on their Entra identity to sign in via SSO.

Ensure the redirect URI in your IdP exactly matches <membership_uri>/api/authorize/callback. Mismatches (scheme, host, path, or trailing slash) will cause sign-in failures.

Verify SSO#

Invite or use an existing user

Use the email domain associated with your IdP, if auto-login by domain is enabled.

Sign in via SSO

From the Formance Cloud portal, choose the newly configured provider and complete the sign-in flow.

You should land back in the portal authenticated to your organization. If not, confirm the redirect URI and client credentials in your IdP and re-run the configure command if needed.

Reference#

Bash

fctl cloud organizations authentication-provider configure -h

You can enable SSO on a per-organization basis using your existing identity provider. Supported providers are OIDC, Microsoft Entra ID (formerly Azure AD), Google, and GitHub.

Prerequisites#

A Formance Cloud organization and access to fctl
A client application created in your identity provider (Client ID and Client Secret)

When creating the app in your IdP, set the redirect URI to your membership endpoint callback: <membership_uri>/api/authorize/callback. See step 1 to determine your membership URI.

Determine your membership URI#

Use the same membership URI you pass to fctl login.

Bash

fctl login --membership-uri https://membership.BASE_URL/api

The SSO redirect URI to register in your IdP is therefore:

https://membership.BASE_URL/api/authorize/callback

After you create the SSO configuration, the exact redirect URI is also displayed in the UI.

Configure the authentication provider#

The command format is:

Bash

fctl cloud organizations authentication-provider configure <type> <name> <client-id> <client-secret> \
  [--oidc-issuer <issuer-url>] [--microsoft-tenant <tenant-id-or-domain>]

type: one of oidc, microsoft, github, google
name: human-friendly provider name shown to users
client-id / client-secret: values from your IdP app
--oidc-issuer: required for oidc (e.g., https://accounts.example.com)
--microsoft-tenant: required for microsoft (tenant ID or verified domain)

Microsoft Entra ID#

To configure Microsoft Entra ID as your identity provider, use the oidc type with the Microsoft issuer URL.

The --oidc-issuer must follow this format:

https://login.microsoftonline.com/<tenant-id>/v2.0

Replace <tenant-id> with your Entra tenant ID.

Bash

fctl cloud organizations authentication-provider configure \
  oidc "msentra" <client-id> <client-secret> \
  --oidc-issuer https://login.microsoftonline.com/<tenant-id>/v2.0

Users must have an email address configured on their Entra identity to sign in via SSO.

Ensure the redirect URI in your IdP exactly matches <membership_uri>/api/authorize/callback. Mismatches (scheme, host, path, or trailing slash) will cause sign-in failures.

Verify SSO#

Invite or use an existing user

Use the email domain associated with your IdP, if auto-login by domain is enabled.

Sign in via SSO

From the Formance Cloud portal, choose the newly configured provider and complete the sign-in flow.

You should land back in the portal authenticated to your organization. If not, confirm the redirect URI and client credentials in your IdP and re-run the configure command if needed.

Reference#

Bash

fctl cloud organizations authentication-provider configure -h