SAML Troubleshooting & Maintenance

Diagnose broken SAML logins, rotate an expired IdP certificate, enable SAML debug logging, and recover access when SAML locks users out.

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 the SAML tile to reveal the SAML setup. Once SAML is configured, a summary card at the top shows the IdP details, the username source, both certificates with their expiry, and the last successful sign-in and test. Below it, the fields are grouped into sections:

• Guided setup — three steps: download Curator’s metadata for your IdP, import the IdP’s metadata, and run a test sign-in. The test opens the IdP in a new window and lists the attributes it returned without signing anyone in.
• SAML connection details — the core IdP fields: Curator Entity ID (Issuer), IdP Entity ID, Sign-in URL (SSO), and Logout URL (SLO). Filled in by the import; edit them here only when you have values by hand.
• User provisioning and Attributes to store on the user profile — not relevant to the troubleshooting scenarios below.
• Request signing and certificates — the IdP signing certificate, the Curator signing certificate and private key, and the signing toggles.
• Compatibility overrides — Debug logging, strict mode, the skip-validation switches, bindings and algorithms. Every section below the guide is collapsed by default; click its header to expand it. The summary card shows an Overrides active chip whenever one of these is turned on.

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

Symptom	What it usually means
Blank gray page / blank box on every page	The frontend cannot complete authentication. This commonly indicates an expired or mismatched IdP signing certificate, or a SignOn URL that no longer matches the IdP. Turn on Debug logging to see the underlying SAML error in the system log.
Redirect loop (the page bounces between Curator and the IdP)	The IdP returns a response Curator rejects — frequently a certificate mismatch, a clock skew between servers, or an Entity ID that no longer matches what the IdP is configured to send.
”User not found” or access denied after a successful IdP login	The IdP authenticated the user, but the username Curator received does not match a Curator/Tableau user. Check the Strip Domain Prefix setting and the Custom User Identifier Field, and confirm the user exists on the connected platform.
Login worked yesterday, fails today with no config change	Most often an expired IdP certificate. Follow Updating the IdP certificate.
Login worked with the old IdP, but breaks right after switching to a new one (e.g. Okta to Entra)	You replaced the provider rather than updating it in place, so every user must be provisioned again in the new IdP. Most failures trace back to a user missing from the new IdP, or a username claim that does not match the Tableau Server username exactly. See Switching from Another SAML Provider.

​

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 logging to Response User Information using Enabling Debug Logging.
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 logging back to Off.

​

Step 2: Check whether the platform user link resolved

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 [e-mail] — 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 [e-mail] where the platform user is [e-mail]), 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.

​

Option 1: Re-import the IdP metadata (recommended)

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, click Re-import metadata on the summary card (or open step 2 of the guide) and drop the XML file onto the upload area. You can paste the IdP’s metadata URL instead.
4. Curator shows the IdP Entity ID, Sign-in URL (SSO), Logout URL (SLO) and certificate it found, with the certificate’s expiry date. Click Apply these settings.
5. Click Test sign-in in step 3 to confirm the IdP signs you in.

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 IdP signing certificate field with the new certificate.
3. Save the page and test a login.

The IdP signing certificate field holds the IdP’s certificate. It is distinct from the Curator signing certificate and Curator private key fields in the same section, which Curator uses to sign its own requests. See Signing Login Requests for those.

​

Enabling Debug Logging

Curator has a built-in Debug logging setting that writes detailed SAML output to the system log so you can see exactly what the IdP is sending.

2. Set Debug logging 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 logging back to Off when you are finished. It logs sensitive authentication data and, in the SAML Response mode, interrupts the login flow.

​

Strict mode and sign-in response checks

Strict mode is in the Compatibility overrides section. With strict mode on, Curator rejects a sign-in response when its audience, destination or issuer does not match Curator’s settings. New SAML setups use strict mode. Sites that used SAML before strict mode became the default keep the setting they had, so their sign-ins work as before.

Whatever the strict mode setting, Curator checks every signed sign-in response in two more ways:

• Expiry. The response is refused when its validity period ended more than 5 minutes ago, or starts more than 5 minutes from now. The 5 minutes allow for a small difference between the clocks on Curator and the IdP.
• One-time use. Each response can sign someone in only once. If the same response arrives again, for example when a user refreshes the page or uses the back button right after signing in, Curator refuses it. Curator remembers each response until it expires. A response with no expiry is remembered for 24 hours, and Curator does not refuse it for having no expiry.

When Curator refuses a response, it writes the reason to the Event Log, at most once every 10 minutes for the same reason and address, and sends the user to start a new sign-in. Most users only see a quick trip through the IdP. If the new sign-in is refused too, the user sees an error page that asks them to sign in again. If users keep seeing that page, the clock on the Curator server or the IdP server is usually wrong.

While strict mode is off, Curator also writes an Event Log warning for the common mismatches strict mode would reject, such as a wrong audience, issuer, destination or recipient. For example: “SAML strict mode would reject this sign-in: the IdP sends audience X but Curator’s entity ID is Y.” The sign-in still succeeds. Each distinct warning is written at most once a day. To read the warnings:

Fix each warning in the IdP or in Curator’s SAML connection details, then turn on strict mode and run a test sign-in to confirm it works.

​

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 logging 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.