## Troubleshooting PingFederate OAuth

URL: https://docs.atlan.com/product/integrations/identity-management/sso/troubleshooting/troubleshooting-pingfederate-oauth

> Troubleshoot PingFederate OAuth errors when querying Snowflake from Atlan Data Exploration, with error, cause, and solution guidance.

When you query a Snowflake connection that uses [PingFederate as the OAuth identity provider](https://docs.atlan.com/llms/connectors/snowflake/enable-snowflake-oauth-with-pingfederate/llms.txt), 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

::::danger 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:

 ```sql
 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

::::danger 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:

 ```sql
 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

::::danger 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:

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

3. Decode the JWT header at [jwt.io](https://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

::::danger 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](https://jwt.io) and note the value of the mapping claim.
2. In Snowflake, search for a user that matches:

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

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

 ```sql
 CREATE USER ""
 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 `jane.doe@example.com`), choose one of these options:

 * Switch the security integration to match on email:

 ```sql
 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

* [Enable Snowflake OAuth with PingFederate](https://docs.atlan.com/llms/connectors/snowflake/enable-snowflake-oauth-with-pingfederate/llms.txt): Full setup guide across Snowflake, PingFederate, and Atlan.
* [SSO integration with PingFederate using OAuth](https://docs.atlan.com/llms/governance/access-control/integration-with-pingfederate-using-oauth/llms.txt): Reference for field mappings across the three systems.

## Need help

If you remain blocked after trying these steps, contact Atlan support: [Submit a request](https://docs.atlan.com/support/submit-request).

---