> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.curator.interworks.com/setup/authentication/okta_saml.md), [OneLogin](https://docs.curator.interworks.com/setup/authentication/one_login_saml.md), or
[Microsoft Entra ID (Azure AD)](https://docs.curator.interworks.com/setup/authentication/azure_ad_saml.md). 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](https://docs.curator.interworks.com/setup/authentication/azure_ad_saml.md#switching-from-another-saml-provider-eg-okta) 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:

In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Security**
\>
**Authentication Settings** page.

On the  page
click the **Sign-in Method** tab

.

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.

> [!NOTE]
>
> 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](#enabling-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](#updating-an-expired-or-changed-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](https://docs.curator.interworks.com/setup/authentication/azure_ad_saml.md#switching-from-another-saml-provider-eg-okta). |

## 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](#enabling-debug-logging).
2. Have the affected user log in again.
3. Read the captured entry:

   In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Logs**
   \>
   **Event Log** page.

   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

In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Users**
\>
**Frontend Users** page.

On the  page

expand the **Platform Users** section.

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](https://docs.curator.interworks.com/users_groups/user_management/username_mapping.md) 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.

> [!NOTE]
>
> 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.

### 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](https://docs.curator.interworks.com/setup/authentication/okta_saml.md), [OneLogin](https://docs.curator.interworks.com/setup/authentication/one_login_saml.md), or
   [Azure AD](https://docs.curator.interworks.com/setup/authentication/azure_ad_saml.md) guides for the exact location.
2. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Security**
   \>
   **Authentication Settings** page.
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.

> [!NOTE]
>
> 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):

1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Security**
   \>
   **Authentication Settings** page.

   On the  page

   expand the **Request signing and certificates** section.
2. Replace the contents of the **IdP signing certificate** field with the new certificate.
3. Save the page and test a login.

> [!NOTE]
>
> 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](https://docs.curator.interworks.com/setup/authentication/signing_saml_login_requests.md) 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.

1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Security**
   \>
   **Authentication Settings** page.

   On the  page

   expand the **Compatibility overrides** section.
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:

In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Logs**
\>
**Event Log** page.

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.
2. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Security**
   \>
   **Authentication Settings** page.
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](https://docs.curator.interworks.com/setup/authentication/curator_users.md) for managing local accounts.
5. Diagnose and fix the SAML problem — typically by [updating the IdP
   certificate](#updating-an-expired-or-changed-idp-certificate) and using [Debug
   logging](#enabling-debug-logging) to confirm the response now validates.
6. Once SAML works again, switch the **Authentication Type** back to **SAML** and save.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.