SAML SSO Configuration
Workspace organization admins can configure SAML SSO from Admin -> Single Sign-On. The page is available only for workspace organizations; personal organizations cannot configure SAML SSO even if the current user is an admin.
SAML SSO routes configured email domains to the organization's identity provider. Password sign-in remains available for users whose email domains do not have SSO enabled.
Bootstrap the workspace first
Before configuring SAML, create and access the workspace with an email/password account:
- Sign up with an email address on the workspace domain, such as
admin@acme.com. - Verify the email address from the verification email.
- Sign in with that email/password account.
- Open Admin -> Single Sign-On and configure SAML for the workspace org.
The verified email/password flow creates or joins the organization for the email domain. For example, admin@acme.com resolves the workspace org domain acme.com. The first user in that org is automatically assigned organization admin access, which is required to open the SAML configuration page.
Users cannot configure SAML from outside an authenticated workspace admin session. If SAML is not configured yet, the bootstrap admin needs email/password access first; otherwise there is no SAML provider to authenticate through and no session that can reach the Admin SSO page.
The bootstrap email domain must match the SAML allowed domain. If the bootstrap admin signs in as admin@acme.com, configure acme.com in Allowed domains. A different domain is rejected when saving the configuration unless the organization owns it, and SAML login later fails if the IdP asserts an email outside the allowed domains list.
Service provider values
The Service Provider Details section is shown before an identity provider configuration has been saved. Use these values when creating the SAML application in your IdP:
| Field | Value |
|---|---|
| Metadata URL | <AXIOMCLOUD_BASE_URL>/auth/saml/metadata/<organization_id> |
| Entity ID / Audience URI | Same as the Metadata URL |
| ACS URL / Reply URL | <AXIOMCLOUD_BASE_URL>/auth/saml/acs |
| NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
The Metadata URL returns SAML metadata only after a SAML configuration exists for the organization. If your IdP requires manual entry before metadata is available, enter the ACS URL, Entity ID / Audience URI, and NameID Format from the Service Provider Details section.
SAML Single Logout is not supported. AxiomCloud logout is local-only, and the service provider metadata does not advertise a Single Logout endpoint.
Identity provider fields
Enter the values from your IdP application in the Identity Provider section:
| AxiomCloud field | What to enter |
|---|---|
| Display name | A human-readable provider name, such as Okta, Entra ID, or Google Workspace. |
| IdP entity ID | The IdP issuer/entity ID for the SAML application. |
| IdP SSO URL | The IdP redirect URL where AxiomCloud sends SAML authentication requests. |
| IdP logout URL | Optional. Stored for reference, but SAML logout is not performed. |
| IdP X.509 certificate | The signing certificate from the IdP. PEM headers, whitespace, and line breaks are accepted. |
When SAML is enabled, allowed domains, IdP entity ID, IdP SSO URL, and IdP X.509 certificate are required.
Attribute mapping
Configure your SAML application to emit these attributes:
| User field | IdP attribute to emit | AxiomCloud mapping field | Required? |
|---|---|---|---|
email | Email attribute, defaults to email | Yes | |
| First name | givenName | First name attribute | No |
| Last name | surname | Last name attribute | No |
First name and last name are optional. If your IdP uses different claim names, enter those exact attribute names in the Admin SSO mapping fields.
NameID can be used as an attribute mapping value. When configured, AxiomCloud reads the value from the SAML assertion subject NameID. AxiomCloud also falls back to Subject/NameID for email when the configured email attribute is missing or not a valid email, which matches IdPs that satisfy the requested email NameID format without emitting a separate email attribute. When both are present, the configured email attribute takes precedence.
During login, AxiomCloud requires a valid email address from the configured email attribute or Subject/NameID fallback. If the SAML flow was started for a specific email address, the asserted email must match that requested email.
Allowed domains
Allowed domains decide which email domains use this SAML configuration. Enter domains as a comma-separated list, for example:
acme.com, example.com
Domains are normalized to lowercase, leading @ is removed, empty entries are ignored, and duplicates are removed.
Every allowed domain must be owned by the organization. A domain is accepted when it is either:
- The workspace organization's canonical domain, where the organization name itself is that domain.
- Present in
organization_verified_domainsfor the organization.
This ownership check runs when the configuration is saved and again during SAML login. If domain ownership is later removed, stale SAML configurations fail closed at login instead of continuing to admit users for a domain the organization no longer owns.
Local testing with localhost
localhost is accepted as an allowed domain only for local development when the configured AxiomCloud base URL uses a loopback host:
localhost127.0.0.1::1
Production and non-loopback base URLs still reject localhost as an allowed domain. This keeps local SAML testing possible without weakening domain-ownership enforcement for deployed environments.
Login behavior
The email-first login screen checks whether a SAML configuration is enabled for the submitted email domain. If one exists, the user is redirected through the IdP. If none exists, the user can continue with password sign-in.
After a successful SAML response, AxiomCloud:
- Validates the response against the stored IdP certificate and the original request.
- Reads the email from the configured email attribute, with Subject/NameID fallback when needed.
- Confirms the email domain is in the allowed domains list.
- Re-checks that the organization still owns the domain.
- Creates or updates the user as a SAML user, marks the email verified, accepts matching invites, and establishes an AxiomCloud session.