Federated authentication and SSO troubleshooting¶

This topic provides information to help troubleshoot a federated authentication environment, including the error codes and messages that are generated during an unsuccessful user login attempt.

Password-related errors¶

A user with an expired Snowflake password cannot log in with SSO even though they are not using the password. This behavior is intentional and prevents someone from logging in using expired credentials.

SSO logins are also rejected if an administrator set the MUST_CHANGE_PASSWORD parameter to TRUE when creating the user, but the user has not changed the password yet.

Error codes¶

Errors are generated for each failed login attempt. These errors can be obtained from the Snowflake Information Schema or the ACCOUNT_USAGE schema:

• The Snowflake Information Schema provides data from within the past 7 days and can be queried using the LOGIN_HISTORY , LOGIN_HISTORY_BY_USER table functions.
• The LOGIN_HISTORY view in the ACCOUNT_USAGE schema provides similar data from within the past year.

Federated authentication error codes¶

The table below contains error codes and messages related to federated authentication that are not specific to SAML or OIDC. For protocol-specific codes, see SAML error codes and OIDC error codes.

SAML error codes¶

Troubleshooting a login failure differs depending on whether the error message has an UUID.

If you encounter an error message associated with a failed SAML SSO login attempt, and the error message does not have a UUID, then ensure the user exists. If the user exists, then the SAML response is invalid and the number of login attempts is too high.

If you encounter an error message associated with a failed SAML SSO login attempt, and the error message has a UUID, you can ask an administrator that has MONITOR privilege assigned to their role to get a more detailed description of the error by following the steps below:

1. Find the UUID in the error message:

   SAML response is invalid or matching user is not found. Contact your local system administrator. [eb55b777-50a4-4db5-b231-9ee457fb3981]
   

2. Use the UUID as an argument to the SYSTEM$GET_LOGIN_FAILURE_DETAILS function, and extract the error using the JSON_EXTRACT_PATH_TEXT function:

   Copy code

   SELECT JSON_EXTRACT_PATH_TEXT(SYSTEM$GET_LOGIN_FAILURE_DETAILS('eb55b777-50a4-4db5-b231-9ee457fb3981'), 'errorCode');
   

3. Find the error description in the table below:

OIDC error codes¶

The table below contains error codes related to OIDC federated authentication. For configuration guidance, see Configuring OpenID Connect (OIDC) federated authentication. For troubleshooting steps, see OIDC troubleshooting.

OIDC troubleshooting¶

The sections below describe common OIDC configuration and login issues. For error code definitions, see OIDC error codes.

Common issues¶

Users can’t see the OIDC login button on the Snowflake login page.

• Verify the integration is enabled: DESC SECURITY INTEGRATION <integration_name>; and confirm that ENABLED is TRUE.
• Verify OIDC_ENABLE_SSO_LOGIN_PAGE is TRUE.
• Verify OIDC_LOGIN_PAGE_LABEL is set (otherwise the integration name is used as the label).
• If the user has an authentication policy attached, verify that the policy’s AUTHENTICATION_METHODS includes OIDC (or ALL), and that SECURITY_INTEGRATIONS either includes this integration or is empty.
• If ALLOWED_USER_DOMAINS or ALLOWED_EMAIL_PATTERNS is set, verify that the user’s email domain or address matches.

A driver or client login with authenticator=externalbrowser doesn’t use OIDC.

This is expected. OIDC isn’t available through the external-browser authenticator, which supports SAML 2.0 only. For driver SSO, use authenticator=OAUTH_AUTHORIZATION_CODE with an OIDC integration, or configure a SAML 2.0 integration. See Supported sign-in surfaces.

Authentication fails with a generic “incorrect username or password” error after IdP login.

Snowflake deliberately returns the same generic error (390100) whether the password was wrong or the OIDC user couldn’t be resolved. This covers several user-resolution failure modes. Inspect the IdP token contents to narrow the cause:

• Verify the token claim value matches a Snowflake user attribute.

• Run DESC SECURITY INTEGRATION <integration_name>; to confirm the OIDC_TOKEN_USER_MAPPING_CLAIM and OIDC_SNOWFLAKE_USER_MAPPING_ATTRIBUTE settings.

• Verify the Snowflake user exists with the expected LOGIN_NAME or EMAIL_ADDRESS:

  Copy code

  SHOW USERS LIKE '<expected_value>';
  

• If the user typed a login name or email at the identifier-first prompt that doesn’t resolve to the same Snowflake user as the IdP-returned claim, the login fails with 390322 (IFF_USER_MISMATCH), a code shared with SAML.

• If ALLOWED_USER_DOMAINS or ALLOWED_EMAIL_PATTERNS is set, verify that the resolved claim value matches.

Authentication fails for a user with email-based mapping even though the user exists.

The user’s email might not be verified. Email-based mapping requires a verified email, and an unverified email fails as an unresolved user (the generic 390100 error) with no dedicated code to grep for. Verify the user’s email, or verify their email domain. See Verified email requirement.

Authentication fails when a token email matches multiple Snowflake users.

When more than one Snowflake user has a verified email matching the token’s email address, Snowflake can’t resolve a unique user and the login fails. The end user sees the generic sign-in error; check LOGIN_HISTORY to identify this cause. Ensure each email maps to a single user, or use LOGIN_NAME mapping. For the corresponding error code, see OIDC error codes.

Detail code OIDC_TOKEN_INVALID_ISSUER (390255). Custom providers only.

Ensure the OIDC_ISSUER value exactly matches the iss claim in the ID token issued by your IdP. For managed providers (OIDC_PROVIDER='GOOGLE'), Snowflake validates the issuer internally; contact Snowflake Support if this error persists.

Detail code OIDC_TOKEN_INVALID_AUDIENCE (390256). Custom providers only.

• Ensure the OIDC_CLIENT_ID matches the aud claim in the ID token issued by your IdP.
• If your IdP issues tokens with multiple audience values, the azp (authorized party) claim must match the OIDC_CLIENT_ID.

For managed providers (OIDC_PROVIDER='GOOGLE'), Snowflake validates audience internally; contact Snowflake Support if this error persists.

Detail code OIDC_TOKEN_INVALID_NONCE (390257).

This error indicates a possible token replay or session-state issue. The user should retry the login. If the error persists, verify that your IdP correctly echoes the nonce parameter back in the ID token.

Detail code OIDC_TOKEN_EXPIRED (390254).

The ID token has expired (the exp claim is in the past) or was issued too long ago (stale iat). The user should re-authenticate at the IdP and try again.

Endpoint discovery fails during integration creation.

• Verify the issuer URL is correct and accessible from Snowflake.
• Verify the IdP publishes a .well-known/openid-configuration document.
• Alternatively, provide all three required endpoints (OIDC_AUTHORIZATION_ENDPOINT, OIDC_TOKEN_ENDPOINT, OIDC_JWKS_URI) explicitly to skip discovery.

Domain or email pattern restrictions block valid users.

• Verify the ALLOWED_USER_DOMAINS or ALLOWED_EMAIL_PATTERNS values include the user’s email domain.
• The domain/email check uses the same token claim that resolved the user. If the configured claim doesn’t contain an email address, domain filtering may unexpectedly fail.
• Email patterns use Java Pattern.find() semantics. If you want full-string matching, anchor your regex with ^...$.