Configure single sign-on
Single sign-on (SSO) lets your team sign in with the same identity they already use for email and the rest of your work tools. AxisSynapse is a SAML 2.0 service provider with first-class presets for Microsoft Entra ID, Okta, Google Workspace, Auth0, and OneLogin, plus a Generic SAML 2.0 mode for any other provider. Once an identity provider is wired in, your team's day-to-day sign-in is one tap: enter email → continue with provider → land in workspace.
TL;DR — Open Settings → Identity & SSO, click Add identity provider, pick a preset or Generic SAML 2.0, paste the metadata XML (or the sign-in URL + certificate + issuer individually), confirm the attribute mappings, run Test sign-in, flip Enabled on. Production team is on SSO in about ten minutes.
Before you start
- You must be a Workspace admin to add or change an identity provider.
- Gather from your identity provider's admin console:
- The sign-in URL the provider exposes for inbound SAML requests.
- The certificate the provider signs assertions with (PEM or X.509).
- The entity ID (also called issuer) the provider stamps on each assertion.
- The attribute names your provider sends for email, first name, and last name. Some providers also send groups for role mapping.
- If your provider exports a metadata XML file (most do), download it once — AxisSynapse can read all four fields above from it in one paste.
- Have a test user account at your identity provider you can use to verify the round trip before flipping the integration on for everyone.
Service-provider details
AxisSynapse publishes its SP metadata at a stable URL under Settings → Identity → Service-provider metadata. Your IdP-side configuration uses the SP entity ID and ACS URL from that page. Both values are workspace-scoped — every workspace has its own.
Add the identity provider
Open Settings → Identity & SSO
From the workspace nav, click Settings, then Identity & SSO. The page lists every identity provider your workspace has configured. New providers start in Draft so you can test before flipping them on.
Click "Add identity provider"
The provider-picker slides in. Pick a preset (Microsoft Entra ID, Okta, Google Workspace, Auth0, OneLogin) or Generic SAML 2.0 for anything else. Presets pre-fill the attribute mappings so you can skip ahead to the metadata step.
Name the provider
Pick a short display name (e.g. Microsoft Entra ID (prod)). Appears on the sign-in card next to the Continue with… button.
Paste the metadata
Drop the metadata XML onto the Metadata XML dropzone, OR expand Advanced to paste Sign-in URL, Certificate, and Entity ID separately. AxisSynapse validates the certificate and surfaces any parsing errors before saving.
Confirm the attribute mappings
The preset picks the right attribute names for the major providers; Generic SAML 2.0 lets you set them by hand. Hover the question mark next to each row for the example values the provider sends.
Run a test sign-in
Click Test sign-in. A sandboxed window completes one round trip against your provider, surfaces the attributes it received, and confirms the certificate signature. If anything looks off, AxisSynapse names the field and what to fix.
Flip the integration on
When the test passes, toggle Enabled on the provider. New sign-ins immediately route through it. Existing email + password sessions stay alive until they expire, so there's no abrupt cutover.
Provider presets
Pick the preset that matches your identity provider; the field names in the "Every field, explained" table below are the labels you'll see inside the AxisSynapse form, not the IdP-side labels.
| Field | What it does | Accepted values / default |
|---|---|---|
| Microsoft Entra ID | The preset for Microsoft's enterprise SSO. Attribute names default to Microsoft's claim URIs. | Export federation metadata from the Entra ID enterprise application; paste into Metadata XML. |
| Okta | Default attribute mapping for Okta's SAML applications. | Add a SAML 2.0 app in Okta, set Single sign on URL to the workspace's ACS URL, audience URI to the SP entity ID, export metadata. |
| Google Workspace | Default attribute mapping for Google's SAML apps. | Create a custom SAML app in the Google Admin console, download the metadata, paste here. |
| Auth0 | Default attribute mapping for Auth0's SAML add-on. | Enable the SAML 2.0 add-on on your Auth0 application; the metadata URL is downloadable from the Usage tab. |
| OneLogin | Default attribute mapping for OneLogin's SAML connectors. | Create a SAML Test Connector (Advanced); paste the IdP metadata URL into the dropzone. |
| Generic SAML 2.0 | For ADFS, PingFederate, Shibboleth, Keycloak, JumpCloud, and any other SAML 2.0 IdP. | Paste metadata XML, OR enter sign-in URL + certificate + entity ID by hand. Map attribute names yourself. |
Every field, explained
| Field | What it does | Accepted values / default |
|---|---|---|
| Display name | Appears on the sign-in card next to the Continue with… button. | Up to 60 characters. Use something users will recognize ('Entra ID', 'Okta'). |
| Provider type | Selects the preset that controls default attribute mappings. | One of the six presets above. |
| Metadata XML | Single-file paste of the IdP's federation metadata. | Drop the .xml file or paste its contents. If the file is signed, the certificate is verified before save. |
| Sign-in URL | Where AxisSynapse POSTs the AuthnRequest. Required if you don't use Metadata XML. | Absolute HTTPS URL. Provided by your IdP. |
| Certificate | Public key used to verify the IdP's signature on every assertion. | PEM or X.509 block. Expiry is tracked; alerts fire 30, 7, and 1 days before expiration. |
| Entity ID (Issuer) | The unique string the IdP stamps on every assertion. | Matches the IdP-side configuration verbatim. |
| Email attribute | Which assertion attribute carries the user's email address. | Preset defaults: NameID/EmailAddress, Email, mail. Case-sensitive — copy from your IdP's test response if in doubt. |
| First name attribute | Which attribute carries the user's first name. | Preset defaults: given_name, firstName, FirstName, givenName. |
| Last name attribute | Which attribute carries the user's last name. | Preset defaults: family_name, lastName, LastName, surname. |
| Groups attribute (optional) | Which attribute carries the user's group memberships, used for role mapping. | Optional. Comma- or semicolon-separated string of group names. |
| Just-in-time provisioning | Creates the AxisSynapse account on first SSO sign-in if none exists. | On by default. Defaults the JIT user to the Member role; cannot grant Workspace admin. |
| JIT default role | Role granted to JIT-provisioned accounts. | Member by default. Cannot be Workspace admin (those promotions require an explicit admin action). |
| Domain restriction | Limit which email domains are routed to this provider. | Comma-separated list of domains. Empty = all domains. Useful when one workspace has multiple SAML providers. |
| Enabled | Whether new sign-ins are routed through this provider. | Off (Draft) by default. Flip on after Test sign-in passes. |
What appears in the audit log
Every SSO configuration change and every sign-in attempt is recorded.
TENANT_SAML_PROVIDER_CREATED/..._UPDATED/..._DELETED— configuration lifecycle.TENANT_SAML_PROVIDER_ENABLED/..._DISABLED— going live or pausing. Review these around any incident.ACCOUNT_SAML_SIGNIN_SUCCESS/..._FAILED— every user sign-in attempt routed through SAML.ACCOUNT_SAML_JIT_PROVISIONED— emitted the first time an unknown email lands via SSO and the account is auto-created. Periodically review for unexpected domains.
Stream these to your SIEM
The same audit codes feed any webhook subscription with the
platform.saml.* event filter. See
Webhooks &
event subscriptions to subscribe your SIEM for real-time SSO
visibility.
Common gotchas
- Attribute case sensitivity. Some IdPs send
emailAddress, others sendemail, and a few sendEmail. The mapping screen is case-sensitive — when in doubt, copy the attribute name straight from your IdP's test response. - Certificate expiry. SAML certificates expire on a schedule. AxisSynapse emails the workspace admins 30, 7, and 1 days before expiration. Add the rotation to a recurring calendar event from day one so it's on the team's radar.
- Group mappings. If you map IdP groups to AxisSynapse roles, every new sign-in re-evaluates the user's role. Don't grant permissions in AxisSynapse that you intend to revoke by removing someone from a group — the next sign-in will undo your change.
- One IdP per email domain. If you wire two SAML providers and both claim the same domain, the routing is ambiguous. Use Domain restriction on each to scope ownership.
- NameID format. Some IdPs default to a persistent NameID rather than the email address. AxisSynapse expects the email attribute to carry the address; the NameID format itself can be persistent, transient, or unspecified — we don't care.
- Clock skew. SAML assertions are time-bound. If your IdP and our service clocks drift by more than five minutes, the assertion is rejected as expired. Use NTP on your IdP host.
Troubleshooting
| Error code | What it means | Fix |
|---|---|---|
| SAML_SIGNATURE_INVALID | The certificate in the assertion doesn't match the one we have stored. | Re-export the IdP metadata; the signing certificate may have rotated. |
| SAML_AUDIENCE_MISMATCH | The assertion's Audience doesn't match the SP entity ID. | Set the IdP-side audience URI to the SP entity ID shown in Settings → Identity → Service-provider metadata. |
| SAML_RESPONSE_EXPIRED | The assertion's NotOnOrAfter is in the past. | Sync clocks via NTP; ensure the IdP isn't reusing an assertion. |
| SAML_INRESPONSETO_MISMATCH | The InResponseTo doesn't match an active AuthnRequest. | Don't retry stale assertions; restart the sign-in flow. |
| SAML_ATTRIBUTE_MISSING | The email attribute couldn't be read from the assertion. | Confirm the IdP is sending the attribute you mapped, with that exact name. |
| JIT_DISABLED | Sign-in for an unknown email arrived, JIT is off. | Invite the user explicitly, or re-enable JIT. |
See the full catalogue at Reference → Error codes.
Related