Skip to main content

Troubleshooting PingFederate OAuth

When you query a Snowflake connection that uses PingFederate as the OAuth identity provider, several failure modes can prevent the query from running. Each section below covers one error, its root cause, and how to resolve it.

Audience mismatch​

Error

SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN: Audience mismatch

Cause​

The aud claim in the JWT that PingFederate issued doesn't appear in Snowflake's EXTERNAL_OAUTH_AUDIENCE_LIST on the security integration.

Solution​

  1. In PingFederate, open the Access Token Manager and note the Audience Claim Value.

  2. In Snowflake, run DESC SECURITY INTEGRATION <name>; and check EXTERNAL_OAUTH_AUDIENCE_LIST.

  3. If the audience isn't in the list, add it:

    ALTER SECURITY INTEGRATION <name>
      SET EXTERNAL_OAUTH_AUDIENCE_LIST = ('<existing_audience>', '<new_audience>');

  4. In Atlan, confirm the Audience URI field on the connection's SSO config matches the audience configured in PingFederate.

Invalid OAuth access token​

Error

Invalid OAuth access token

Cause​

Snowflake rejected the JWT Atlan sent. This is an umbrella error—the underlying reason is one of audience mismatch, invalid signature, or user not found.

Solution​

  1. Capture the JWT from the failing request or from Atlan's vault.

  2. In Snowflake, run:

    USE ROLE ACCOUNTADMIN;
    SELECT SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN('<paste-jwt-here>');

  3. Read the specific failure from the output and follow the matching section in this guide.

Token signature invalid​

Error

SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN: Token signature invalid

Cause​

Snowflake can't verify the JWT's signature. The JWKS URL is unreachable from Snowflake, or the kid in the JWT header isn't in the published JWKS.

Solution​

  1. Confirm EXTERNAL_OAUTH_JWS_KEYS_URL in the security integration points to PingFederate's JWKS endpoint (typically /pf/JWKS).

  2. From a machine that can reach Snowflake's network, run:

    curl -s https://<pf-host>/pf/JWKS | jq '.keys[] | {kid, alg, use}'

  3. Decode the JWT header at jwt.io and confirm its kid matches a key in the JWKS output.

  4. If the signing certificate was rotated recently, the new key may not yet be published—wait for the rotation to complete or restart PingFederate to force a refresh.

User not found​

Error

SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN: User <login> not found

Cause​

The JWT's mapping claim value (typically sub) doesn't match any Snowflake user's LOGIN_NAME or EMAIL_ADDRESS, depending on EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE.

Solution​

  1. Decode the JWT at jwt.io and note the value of the mapping claim.

  2. In Snowflake, search for a user that matches:

    SHOW USERS LIKE '<value-prefix>%';

  3. If no user exists, create one whose LOGIN_NAME (or EMAIL) equals the claim value:

    CREATE USER "<USERNAME>"
      LOGIN_NAME = '<claim-value>'
      EMAIL      = '<claim-value>'
      DEFAULT_ROLE = '<role>'
      DEFAULT_WAREHOUSE = '<warehouse>';

  4. If a user exists but with a different LOGIN_NAME format (for example, JDOE instead of [email protected]), choose one of these options:

    • Switch the security integration to match on email:

      ALTER SECURITY INTEGRATION <name>
        SET EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'EMAIL_ADDRESS';

    • Configure PingFederate to populate the mapping claim with the existing LOGIN_NAME value instead of the email.

See also​

Need help​

If you remain blocked after trying these steps, contact Atlan support: Submit a request.