Skip to main content
This guide is for administrators who already have SAML configured and need to maintain or repair it — for example when logins suddenly stop working or the Identity Provider (IdP) certificate expires. If you are setting SAML up for the first time, start with the provider-specific guides instead: Okta, OneLogin, or Microsoft Entra ID (Azure AD). If you are replacing an existing IdP with a new one — for example moving from Okta to Microsoft Entra ID — follow Switching from Another SAML Provider instead. That is a bigger change than a certificate rotation, because every user must exist in the new IdP before the cutover, and it has its own checklist.

​
Where SAML settings live

All SAML configuration lives on a single backend page: Select SAML as the Authentication Type to reveal the SAML fields. They are grouped into four sections:
  • General — the Authentication Type selector plus the Download SAML Metadata and Import SAML Metadata buttons.
  • SAML General — the core IdP fields: Entity ID, IdP Entity ID, SignOn URL (SSO), and Logout URL (SLO).
  • SAML Attributes — custom attributes to retrieve and store as part of each user’s profile. Not relevant to the troubleshooting scenarios below.
  • SAML Advanced — everything else, including the Certificate field, Debug Mode, strict-mode and signing toggles, and the Service Provider certificate/key. This section is collapsed by default; click its header to expand it.
The Curator backend login (at /backend) is a separate account system from the frontend SAML login. A broken SAML configuration only locks users out of the frontend portal — you can still sign in to the backend with your Curator backend credentials to reach the settings above and fix the problem.

​
Common failure symptoms

​
Diagnosing a single user after an IdP switch

The guidance above is written for a cutover you have not made yet. Once the cutover is done, you are usually dealing with a different situation: most users are fine, but one user’s dashboard tabs and buttons are missing or their content is denied. The usual cause is that the username the new IdP sends for that user no longer matches their existing platform user. Curator links a Frontend User to a Tableau user by username, so when the format of that username changes, the Frontend User is left with no platform user behind it. The login itself still succeeds, which is why the failure looks like missing content rather than a login error.

​
Step 1: Find the exact username the IdP sent

Curator resolves the username from the Custom User Identifier Field when one is configured, then from a username or Username attribute, and finally from the SAML NameID. It then strips the domain prefix if Strip Domain Prefix is enabled and converts the result to lowercase. That final value is the one that must match the platform user, so guessing at the claim your IdP is configured to send is not enough — read the value Curator actually resolved.
  1. Set Debug Mode to Response User Information using Enabling Debug Mode.
  2. Have the affected user log in again.
  3. Read the captured entry: The entry records the attributes the IdP sent alongside the resolved username.
  4. Set Debug Mode back to Disabled.
Open the affected user, then click the tab for your platform — Tableau Users for a Tableau connection. The table lists Tableau User ID, Username, Full Name, Site Role, Site, Server, and Last Synced.
  • A working link shows a real ID in the Tableau User ID column, the expected Site and Site Role, and a recent Last Synced timestamp.
  • A broken link shows User not on Site '<site name>' in the Tableau User ID column, meaning Curator found no matching user for that username on that site. An empty tab reading No Tableau users found. means no platform user is associated with the Frontend User at all.
If a Sync from Tableau button is available on the tab, click it before drawing a conclusion — that re-queries the server and rules out a merely stale row.

​
Step 3: Reconcile the username formats

Compare the username from Step 1 with the username the user has on the platform. If the two differ only in format — for example the old IdP sent domain\first.last and the new one sends first.last@example.com — configure Username Mapping to translate between them. Do this instead of renaming platform users by hand, so the fix applies to every affected user at once and survives future logins.
Username Mapping can only change the format of a username, not the username itself. If the new IdP sends a genuinely different identifier (for example flast@example.com where the platform user is first.last@example.com), mapping cannot reconcile it. Either have your IdP administrators send the original value in the username claim, or point the Custom User Identifier Field at an attribute that still carries it.

​
Updating an expired or changed IdP certificate

When your IdP rotates or renews its signing certificate, the certificate stored in Curator no longer matches and logins break. There are two ways to update it.
  1. Download a fresh Federation Metadata XML file from your IdP. Each provider exposes this differently — see the Okta, OneLogin, or Azure AD guides for the exact location.
  3. With SAML selected as the Authentication Type, click Import SAML Metadata in the General section and upload the XML file.
  4. Curator re-reads the metadata and updates the IdP Entity ID, SignOn URL (SSO), Logout URL (SLO), and the Certificate field automatically.
  5. Save the page and test a login.
Re-importing metadata only updates the fields present in the XML; it does not clear your other SAML settings. If the file does not contain a value for a field, that field is left unchanged.

​
Option 2: Paste the certificate manually

If you only have the new certificate (not a full metadata file):
  2. Replace the contents of the Certificate field with the new IdP signing certificate.
  3. Save the page and test a login.
The Certificate field holds the IdP’s signing certificate. It is distinct from the Service Provider Certificate and Service Provider Private Key fields lower in the SAML Advanced section, which Curator uses to sign its own requests. See Signing Login Requests for those.

​
Enabling Debug Mode

Curator has a built-in Debug Mode that writes detailed SAML output to the system log so you can see exactly what the IdP is sending.
  2. Set Debug Mode to one of:
    • SAML Response — logs the raw SAML response and prints the parsed attributes to the browser, halting the login. Use this for a one-off inspection, not on a live production login flow.
    • Response Attributes — logs the attributes Curator parsed from the response.
    • Response User Information — logs the resolved username alongside the attributes and API calls.
  3. Save the page and reproduce the failed login.
  4. Read the captured output in the system log under storage/logs/ (files are named system-YYYY-MM-DD.log).
  5. Set Debug Mode back to Disabled when you are finished — it logs sensitive authentication data and, in the SAML Response mode, interrupts the login flow.

​
Emergency recovery: regaining access when SAML is broken

If a SAML misconfiguration is preventing all frontend users from logging in, you can temporarily restore frontend access while you diagnose the problem. Because the backend login is independent of SAML, you always retain access to the settings needed to do this.
  1. Sign in to the Curator backend at /backend with your backend credentials.
  3. Change the Authentication Type from SAML to Curator Users and save. Curator now authenticates frontend users against locally stored accounts instead of your IdP.
  4. Create or use a local frontend user so you and your team can access the portal while SAML is down. See Curator Users for managing local accounts.
  5. Diagnose and fix the SAML problem — typically by updating the IdP certificate and using Debug Mode to confirm the response now validates.
  6. Once SAML works again, switch the Authentication Type back to SAML and save.
Leave the integration on Curator Users only for as long as the recovery takes. While it is active, your IdP is not enforcing authentication for the Curator frontend.