Bypass Identity Provider Authentication for Troubleshooting

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

When your catalog is configured for SAML, OpenID Connect (OIDC), or LDAP authentication, a misconfiguration or disruption in the identity provider can result in a situation where no one, including Server Admins, is able to log in to Alation. The Bypass Identity Provider Authentication for Troubleshooting flag gives you a recovery path as a Server Admin: you can sign in with built-in credentials, fix the identity provider configuration, and restore your configured authentication method.

To use the bypass, at least one Server Admin account must already have a built-in (Alation) password set. If no Server Admin has built-in credentials, the bypass cannot help you sign in. Set or reset a built-in password for at least one Server Admin account before you activate SAML, OIDC, or LDAP, so a recovery account is ready when you need it.

In this topic:

Configuration Flag Overview

Bypass Identity Provider Authentication for Troubleshooting is a Server Admin feature flag exposed in Admin Settings > Feature Configuration. The underlying alation_conf parameter is alation.feature_flags.bypass_idp_auth_for_troubleshooting.

Where the flag appears depends on the user experience:

  • New User Experience: the flag is grouped under the System & Administration section (or tab) of Feature Configuration.

  • Classic User Experience: the flag appears directly in the Feature Configuration list.

The flag is off by default. While it is off, the configured identity provider (SAML, OIDC, or LDAP) is the only sign-in option for users who authenticate through it, and the ?bypass_idp_auth=true query parameter has no effect.

When the flag is on, Alation accepts the ?bypass_idp_auth=true query parameter on the sign-in URL. Visiting /login/?bypass_idp_auth=true skips the configured identity provider and falls back to built-in username and password authentication for that sign-in. All other sign-in flows continue to use the identity provider as configured.

Turn the flag on when both of the following are true:

  • Your catalog is configured to use SAML, OIDC, or LDAP authentication.

  • The identity provider is misconfigured, unreachable, or otherwise preventing Server Admins from signing in.

Typical scenarios include:

  • A SAML metadata change that breaks the trust between Alation and the identity provider.

  • An OIDC client secret rotation that has not been propagated to Alation.

  • An LDAP server outage or directory schema change that fails authentication for every user.

Turn the Flag On From Feature Configuration

Before version 2026.7.0.0, Server Admins on Alation Cloud Service had to contact Alation Support to toggle this flag. Starting in version 2026.7.0.0 of Alation Cloud Service, the flag is editable directly from the Feature Configuration page.

Note

To use the Feature Configuration page, you need to be signed in to Alation. If every Server Admin is locked out and no one can reach Feature Configuration, contact Alation Support to enable the flag.

After the flag is on, follow Sign In Using the Bypass to sign in with built-in credentials. You can then keep the flag on (or turn it off when you are done) from Feature Configuration.

To turn the flag on in the user interface:

  1. Sign in to Alation as a Server Admin from any account that still has access (for example, a built-in account that does not depend on the identity provider).

  2. Go to Admin Settings > Feature Configuration.

  3. Locate Bypass Identity Provider Authentication for Troubleshooting:

    • New User Experience: open the System & Administration section (or tab).

    • Classic User Experience: find the flag directly in the Feature Configuration list.

  4. Turn the toggle on.

  5. Click Save changes and confirm in the Save Configuration dialog.

Note

The change does not take effect immediately. Wait 1–2 minutes after saving for the new value to propagate. If the flag still has no effect after 3 minutes, contact Alation Support.

Sign In Using the Bypass

After the flag is active (allow 1–2 minutes after saving for the change to propagate):

  1. In a browser, open the full sign-in URL on your Alation host with the ?bypass_idp_auth=true query parameter, for example https://<your-alation-host>/login/?bypass_idp_auth=true. Replace <your-alation-host> with the fully qualified domain of your Alation instance, for example catalog.example.com.

  2. Enter the username and built-in password for a Server Admin account that has built-in credentials.

  3. Sign in. The configured identity provider is skipped for this sign-in only.

  4. Fix the identity provider configuration that caused the lockout. For example, update SAML metadata, rotate the OIDC client secret, or repair the LDAP connection.

  5. Sign in again without the query parameter to verify the identity provider works correctly for normal flows.

Turn the Flag Off After Troubleshooting

Important

Turn this flag off as soon as the identity provider is working again. While the flag is on, anyone with a valid built-in username and password can use ?bypass_idp_auth=true to sign in without going through the identity provider, which weakens the single sign-on policy your catalog enforces.

To turn the flag off:

  1. Go to Admin Settings > Feature Configuration.

  2. Locate Bypass Identity Provider Authentication for Troubleshooting:

    • New User Experience: open the System & Administration section (or tab).

    • Classic User Experience: find the flag directly in the Feature Configuration list.

  3. Turn the toggle off.

  4. Click Save changes and confirm.

Note

The change does not take effect immediately. Wait 1–2 minutes after saving for the new value to propagate. If the bypass still works after 3 minutes, contact Alation Support.

Once the flag is off, the ?bypass_idp_auth=true query parameter no longer skips the identity provider, and every sign-in goes through SAML, OIDC, or LDAP as configured.