SSO Configuration

SSO configuration is the portal workflow for connecting AxonFlow to an enterprise identity provider so people can sign into the customer portal instead of relying only on local passwords. This is the setup side of portal login (plane a); the protocol flows themselves are described in Portal Login (SSO): SAML and OIDC. Portal login supports both SAML and OIDC, and this page covers configuring either.

The current portal configuration surface includes:

• GET /api/v1/sso/config
• POST /api/v1/sso/config
• PUT /api/v1/sso/config
• PATCH /api/v1/sso/config
• DELETE /api/v1/sso/config
• POST /api/v1/sso/config/test
• GET /api/v1/sso/audit
• GET /api/v1/sso/providers
• GET /api/v1/sso/providers/defaults
• GET /api/v1/sso/sp-metadata
• POST /api/v1/sso/fetch-metadata

What Platform And IAM Teams Do Here

This workflow is where an identity or platform team:

1. chooses a provider
2. loads or fetches IdP metadata
3. verifies the service provider metadata AxonFlow expects
4. tests the configuration
5. enables or disables the SSO configuration
6. reviews audit data when login issues appear

That is a much more complete workflow than simply publishing a SAML ACS URL in a setup guide.

SaaS Versus In-VPC

The portal frontend is deployment-aware. The SSO settings experience is organization-scoped in SaaS environments and more platform-oriented in In-VPC deployments. Either way, the operational pattern is the same: configure the provider from an authenticated session, then use the resulting SSO flow for user sign-in.

The effective SSO tenant differs by deployment mode:

Deployment mode	SSO tenant used by the backend
SaaS / tenant-isolated	the authenticated session tenant
In-VPC / non-tenant-isolated	the platform-wide __platform__ SSO tenant

Self-Hosted Requirements

Self-hosted (in-vpc) deployments must set one environment variable before configuring portal SSO, for either protocol:

• SSO_BASE_URL must be your portal's external URL, for example https://portal.yourcompany.com. The SAML AssertionConsumerService (ACS) URL, the OIDC redirect_uri, and the SP metadata are all derived from it, so the identity provider returns the SAML assertion or the OIDC authorization code back to your own portal. If SSO_BASE_URL is unset on a non-SaaS deployment, the identity provider is pointed at the default host and login fails; the portal logs a warning at startup when this is the case. As of v9.15.0 the ACS host is recomputed from SSO_BASE_URL on every request, so setting the variable and restarting corrects any previously stored value with no re-save; the OIDC redirect_uri (v9.16.0) is likewise recomputed on every read.

You can configure your identity provider as either a SAML application or an OIDC application:

• SAML providers use the ACS URL below and register at https://<your SSO_BASE_URL host>/auth/saml/<sso-tenant>/callback.
• OIDC providers (v9.16.0) register the redirect URI https://<your SSO_BASE_URL host>/auth/oidc/<sso-tenant>/callback.

In both, <sso-tenant> is __platform__ on in-vpc deployments and your org id on SaaS. GET /api/v1/sso/sp-metadata returns the exact SAML values; for OIDC, the config read (GET /api/v1/sso/config) returns the exact oidc_redirect_uri to register.

Configuring an OIDC provider

Saving any OIDC configuration (provider of oidc or jumpcloud) requires the three verifier inputs; interactive portal login additionally requires the client credentials:

Field	Required to save	Purpose
oidc_issuer	yes	the identity provider's issuer URL (HTTPS)
oidc_audience	yes	the audience for the fleet plane (plane b), which verifies a per-user token's aud against it. Portal login does not use this field: it verifies the id_token audience against the client_id.
oidc_jwks_uri	yes	the JWKS endpoint used to verify the token signature (HTTPS)
oidc_client_id	portal login only	the OAuth client id, sent in the browser authorize redirect
oidc_client_secret	portal login only	the OAuth client secret, used at the token endpoint

A single OIDC configuration can serve both planes at once: the fleet plane reads oidc_audience, and portal login reads the client credentials. Because a tenant has only one SSO configuration row, this is also the only way to run both browser login and fleet identity on one tenant (see the shared-configuration note); SAML portal login uses a saml configuration and cannot coexist with fleet OIDC.

Migration core/158 adds oidc_client_id and oidc_client_secret to the SSO configuration. The client secret is stored with the same at-rest posture as a SAML private key: it is never returned in any response and never logged, and a settings save that omits it keeps the stored value rather than clearing it.

Internal identity providers need AXONFLOW_OIDC_ALLOW_PRIVATE

OIDC endpoint fetches (discovery, JWKS, token exchange) are SSRF-hardened and by default reject identity-provider hosts that resolve to a private address (RFC-1918, CGNAT, link-local, or a Kubernetes ClusterIP / *.svc.cluster.local). If your identity provider runs inside your own network, set AXONFLOW_OIDC_ALLOW_PRIVATE=true on the agent and customer-portal after upgrading, or every OIDC fetch fails closed. Public-identity-provider SaaS deployments need no change.

Auto-Provisioning Roles

When the SSO configuration has Auto-provision users enabled, a first-time SSO user (one with no existing active role in the organization) is assigned the role mapped from their identity-provider group, or the configured default role, on login (v9.15.0). This is assign-if-absent: a user who already has a role, from SCIM, manual assignment, or a prior login, is left untouched.

Auto-provisioning does not remove a role when the identity provider removes the user from a group. If you need full add-and-remove lifecycle (de-provisioning when group membership changes), use SCIM group-to-role mapping, which reconciles roles on every directory sync. SCIM (provisioning and roles) and portal login (SAML or OIDC) are complementary: run SCIM when you need the directory to be the source of truth for who has which role. OIDC portal login performs the same best-effort role auto-provisioning on first login.

Metadata And Testing

Two parts of the current implementation are especially useful:

• SP metadata lets the customer see the AxonFlow entity ID and ACS URL that should be configured in the identity provider
• configuration testing validates whether the portal can actually use the supplied IdP settings before a team rolls the change out broadly

GET /api/v1/sso/sp-metadata returns deployment-specific service-provider values. The backend reads optional SAML_SP_ENTITY_ID, SAML_ACS_URL, SAML_SLO_URL, and SAML_METADATA_URL overrides, and can emit a tenant-specific ACS URL for session-aware multi-tenant deployments.

POST /api/v1/sso/fetch-metadata accepts:

{
  "metadata_url": "https://idp.example.com/app/metadata"
}

The metadata-fetch path is session-authenticated, rate-limited to 5 requests per minute per session, restricted to HTTPS URLs, blocks private and loopback network targets, limits the metadata response to 1 MB, and parses SAML metadata XML into entity_id, sso_url, optional slo_url, certificate, and detected provider name.

The provider helper endpoints are query-parameter based:

Endpoint	Behavior
GET /api/v1/sso/providers	returns the supported setup-helper list
GET /api/v1/sso/providers?provider=okta	returns setup instructions for one provider
GET /api/v1/sso/providers/defaults?provider=azure_ad	returns default configuration values for one provider

The setup-helper instruction text (GET /api/v1/sso/providers?provider=...) covers okta, azure_ad, auth0, custom_saml, and jumpcloud. The metadata-fetch endpoint (POST /api/v1/sso/fetch-metadata) is SAML-specific, since it parses SAML metadata XML; OIDC providers are configured from their issuer, audience, JWKS URI, and client credentials rather than an XML metadata document. Provider defaults (GET /api/v1/sso/providers/defaults?provider=...) are available for the SAML presets and for jumpcloud (which pre-fills the OIDC issuer and JWKS endpoints).

That makes this page valuable for reducing rollout risk. Identity integrations often fail because teams publish partially correct metadata and only discover the mismatch during a live login attempt.

Permissions And Neighboring Surfaces

The portal also uses the sso:configure permission for SCIM token management. That is a signal that SSO and provisioning should be treated as related access-control operations, not independent one-off features.

For most enterprise deployments, the right workflow is:

1. configure SSO
2. verify login behavior
3. configure SCIM if automated provisioning is required
4. align group or role mapping

Common Uses

This page matters when:

• enabling Okta, Microsoft Entra ID, Auth0, JumpCloud, or another SAML or OIDC identity provider for the first time
• rotating certificates or metadata
• debugging failed SSO handshakes
• validating service-provider metadata after deployment changes
• moving from password login to enterprise identity ownership

Related Docs

• Identity Overview: the three planes
• Portal Login (SSO): SAML and OIDC
• Enterprise Authentication Surfaces
• SCIM 2.0 Provisioning
• SCIM Group Role Mapping
• Enterprise Rollout Checklist