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

export const BackendNavPath = ({levelOne, levelTwo, levelThree, tab, section}) => {
  const levels = [levelOne, levelTwo, levelThree].filter(Boolean);
  const lastLevel = levels.length ? levels[levels.length - 1] : '';
  return <span>
      In the <a href="/setup/installation/linux_installation">backend of Curator</a> using the left-hand navigation,
      navigate to the
      {levelOne && <strong>{" " + levelOne}</strong>}
      {levelOne && levelTwo && " > "}
      {levelTwo && <strong>{levelTwo}</strong>}
      {levelTwo && levelThree && " > "}
      {levelThree && <strong>{levelThree}</strong>} page.
      {(tab || section) && <>
          {" "}On the {lastLevel} page
          {tab && <> click the <strong>{tab}</strong> tab</>}
          {tab && section && " and"}
          {section && <> expand the <strong>{section}</strong> section</>}.
        </>}
    </span>;
};

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](/setup/authentication/okta_saml), [OneLogin](/setup/authentication/one_login_saml), or
[Microsoft Entra ID (Azure AD)](/setup/authentication/azure_ad_saml).

## Where SAML settings live

All SAML configuration lives on a single backend page:

<BackendNavPath levelOne="Settings" levelTwo="Security" levelThree="Authentication Settings" tab="General" />

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.

<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.
</Note>

## 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. Enable [Debug Mode](#enabling-debug-mode) 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).                                                                                                                                   |

## 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](/setup/authentication/okta_saml), [OneLogin](/setup/authentication/one_login_saml), or
   [Azure AD](/setup/authentication/azure_ad_saml) guides for the exact location.
2. <BackendNavPath levelOne="Settings" levelTwo="Security" levelThree="Authentication Settings" />
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.

<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.
</Note>

### Option 2: Paste the certificate manually

If you only have the new certificate (not a full metadata file):

1. <BackendNavPath levelOne="Settings" levelTwo="Security" levelThree="Authentication Settings" section="SAML Advanced" />
2. Replace the contents of the **Certificate** field with the new IdP signing certificate.
3. Save the page and test a login.

<Note>
  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](/setup/authentication/signing_saml_login_requests) for
  those.
</Note>

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

1. <BackendNavPath levelOne="Settings" levelTwo="Security" levelThree="Authentication Settings" section="SAML Advanced" />
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.
2. <BackendNavPath levelOne="Settings" levelTwo="Security" levelThree="Authentication Settings" />
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](/setup/authentication/curator_users) 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
   Mode](#enabling-debug-mode) 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.
</Warning>