# Source: https://neon.com/llms/data-api-custom-authentication-providers.txt

# Custom Authentication Providers

> The "Custom Authentication Providers" documentation outlines how Neon users can integrate custom authentication mechanisms with the Neon Data API, detailing configuration steps and supported authentication flows.

## Source

- [Custom Authentication Providers HTML](https://neon.com/docs/data-api/custom-authentication-providers): The original HTML version of this documentation

Related docs:
- [Getting started with Data API](https://neon.com/docs/data-api/get-started)

The Data API works with any authentication provider that issues [JSON Web Tokens (JWTs)](https://jwt.io/introduction). While [Neon Auth](https://neon.com/docs/guides/neon-auth) provides the simplest setup, you can use existing authentication infrastructure with providers like Auth0, Clerk, AWS Cognito, and others.

## How it works

When you bring your own authentication provider, the JWT validation flow works as follows:

```
┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│   Client    │         │   Your Auth      │         │  Neon Data  │
│ Application │         │    Provider      │         │     API     │
└──────┬──────┘         └────────┬─────────┘         └──────┬──────┘
       │                         │                          │
       │ 1. Authenticate         │                          │
       │────────────────────────>│                          │
       │                         │                          │
       │ 2. Return JWT token     │                          │
       │<────────────────────────│                          │
       │                         │                          │
       │ 3. API request with     │                          │
       │    Authorization header │                          │
       │────────────────────────────────────────────────────>│
       │                         │                          │
       │                         │ 4. Fetch JWKS keys       │
       │                         │<─────────────────────────│
       │                         │                          │
       │                         │ 5. Return public keys    │
       │                         │──────────────────────────>│
       │                         │                          │
       │                         │    6. Validate JWT       │
       │                         │    7. Extract user_id    │
       │                         │    8. Apply RLS policies │
       │                         │                          │
       │ 9. Return filtered data │                          │
       │<────────────────────────────────────────────────────│
       │                         │                          │
```

The key steps:

1. Your auth provider issues [JSON Web Tokens (JWTs)](https://jwt.io/introduction) to authenticated users.
2. Your application passes these JWTs to the Data API in the `Authorization` header.
3. Neon validates the tokens using your provider's [JWKS (JSON Web Key Set)](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) URL.
4. The Data API enforces [Row-Level Security policies](https://neon.com/docs/guides/neon-rls) based on the user identity in the JWT.

## Add your authentication provider

You can configure your authentication provider when you first enable the Data API, or add it later from the **Configuration** tab. Select **Other Provider** from the dropdown and enter:

- Your provider's **JWKS URL** (see provider-specific instructions below).
- Your **JWT Audience** value, if required by your provider.

## Find your JWKS URL

| Provider                            | JWKS URL Format                                                                             |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| [Auth0](https://neon.com/docs/data-api/custom-authentication-providers#auth0)                     | `https://{YOUR_AUTH0_DOMAIN}/.well-known/jwks.json`                                         |
| [Clerk](https://neon.com/docs/data-api/custom-authentication-providers#clerk)                     | `https://{YOUR_CLERK_DOMAIN}/.well-known/jwks.json`                                         |
| [AWS Cognito](https://neon.com/docs/data-api/custom-authentication-providers#aws-cognito)         | `https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json`           |
| [Azure AD](https://neon.com/docs/data-api/custom-authentication-providers#azure-ad)               | `https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys`                         |
| [Descope](https://neon.com/docs/data-api/custom-authentication-providers#descope)                 | `https://api.descope.com/{PROJECT_ID}/.well-known/jwks.json`                                |
| [Firebase/GCP](https://neon.com/docs/data-api/custom-authentication-providers#firebasegcp)        | `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com` |
| [Google Identity](https://neon.com/docs/data-api/custom-authentication-providers#google-identity) | `https://www.googleapis.com/oauth2/v3/certs`                                                |
| [Keycloak](https://neon.com/docs/data-api/custom-authentication-providers#keycloak)               | `https://{DOMAIN}/auth/realms/{REALM}/protocol/openid-connect/certs`                        |
| [PropelAuth](https://neon.com/docs/data-api/custom-authentication-providers#propelauth)           | `https://{YOUR_PROPEL_AUTH_URL}/.well-known/jwks.json`                                      |
| [Stack Auth](https://neon.com/docs/data-api/custom-authentication-providers#stack-auth)           | `https://api.stack-auth.com/api/v1/projects/{PROJECT_ID}/.well-known/jwks.json`             |
| [Stytch](https://neon.com/docs/data-api/custom-authentication-providers#stytch)                   | `https://test.stytch.com/v1/sessions/jwks/{PROJECT_ID}`                                     |
| [SuperTokens](https://neon.com/docs/data-api/custom-authentication-providers#supertokens)         | `{CORE_CONNECTION_URI}/.well-known/jwks.json`                                               |
| [WorkOS](https://neon.com/docs/data-api/custom-authentication-providers#workos)                   | `https://api.workos.com/sso/jwks/{CLIENT_ID}`                                               |

### Auth0

Your Auth0 JWKS URL follows this format:

```bash
https://{YOUR_AUTH0_DOMAIN}/.well-known/jwks.json
```

To find your domain:

1. Open the **Settings** for your application in the Auth0 dashboard
2. Copy your **Domain** value
3. Use it to form your JWKS URL



For example, if your domain is `dev-abc123.us.auth0.com`, your JWKS URL would be:

```bash
https://dev-abc123.us.auth0.com/.well-known/jwks.json
```

### Clerk

Your Clerk JWKS URL follows this format:

```bash
https://{YOUR_CLERK_DOMAIN}/.well-known/jwks.json
```

To find your JWKS URL:

1. Go to the Clerk Dashboard
2. Navigate to **Configure → Developers → API Keys**
3. Click **Show JWT Public Key**
4. Copy the JWKS URL

For advanced JWT configuration (custom claims, token lifespans), you can use the dedicated Neon template in Clerk under **Configure > JWT Templates**.

### AWS Cognito

Your AWS Cognito JWKS URL follows this format:

```bash
https://cognito-idp.{YOUR_AWS_COGNITO_REGION}.amazonaws.com/{YOUR_AWS_COGNITO_USER_POOL_ID}/.well-known/jwks.json
```

To find your JWKS URL:

1. Open the AWS Cognito console
2. Navigate to **User pools**
3. Select your user pool
4. Find the **Token signing key URL** (this is your JWKS URL)



For example, if your region is `us-east-1` and your user pool ID is `us-east-1_XXXXXXXXX`, your JWKS URL would be:

```bash
https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX/.well-known/jwks.json
```

### Azure AD

Your Azure Active Directory JWKS URL follows this format:

```bash
https://login.microsoftonline.com/{YOUR_TENANT_ID}/discovery/v2.0/keys
```

Replace `{YOUR_TENANT_ID}` with your Azure Active Directory tenant ID.

For example, if your tenant ID is `12345678-1234-1234-1234-1234567890ab`, your JWKS URL would be:

```bash
https://login.microsoftonline.com/12345678-1234-1234-1234-1234567890ab/discovery/v2.0/keys
```

   **Note**: Depending on your Azure AD configuration, you may need to provide a JWT Audience value.

### Descope

Your Descope JWKS URL follows this format:

```bash
https://api.descope.com/{YOUR_DESCOPE_PROJECT_ID}/.well-known/jwks.json
```

To find your Project ID:

1. Go to the Descope Dashboard
2. Navigate to **Project Settings**
3. Copy your **Project ID**



For example, if your Project ID is `P1234`, your JWKS URL would be:

```bash
https://api.descope.com/P1234/.well-known/jwks.json
```

### Firebase/GCP

Firebase and Google Cloud Identity Platform share the same authentication infrastructure and use a common JWKS URL for all projects:

```bash
https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com
```

You must also provide your Firebase/GCP Project ID as the JWT Audience value.

To find your Project ID:

1. Go to the [Firebase Console](https://console.firebase.google.com)
2. Navigate to **Settings** > **General**
3. Copy your **Project ID**



Enter your Project ID in the **JWT Audience** field when configuring the Data API.

   **Note**: Every GCP Identity Platform project automatically creates a corresponding Firebase project, which is why we use the Firebase Console to get the Project ID.

### Google Identity

Your Google Identity JWKS URL is:

```bash
https://www.googleapis.com/oauth2/v3/certs
```

You must also provide your OAuth 2.0 Client ID as the JWT Audience value. You can find your Client ID in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) under **APIs & Services > Credentials**.

### Keycloak

Your Keycloak JWKS URL follows this format:

```bash
https://{YOUR_KEYCLOAK_DOMAIN}/auth/realms/{YOUR_REALM}/protocol/openid-connect/certs
```

Replace:

- `{YOUR_KEYCLOAK_DOMAIN}` with your Keycloak domain
- `{YOUR_REALM}` with your Keycloak realm name

   **Note**: To ensure compatibility with the Data API, configure Keycloak to use only one signing algorithm (RS256 or ES256). You can verify this by opening the JWKS URL and checking the keys manually. Depending on your Keycloak configuration, you may also need to provide a JWT Audience value.

### PropelAuth

Your PropelAuth JWKS URL follows this format:

```bash
https://{YOUR_PROPEL_AUTH_URL}/.well-known/jwks.json
```

To find your PropelAuth URL:

1. Go to your PropelAuth dashboard
2. Navigate to **Backend Integration** in your project settings
3. Copy your Auth URL



For example, if your PropelAuth URL is `https://3211758.propelauthtest.com`, your JWKS URL would be:

```bash
https://3211758.propelauthtest.com/.well-known/jwks.json
```

### Stack Auth

Your Stack Auth JWKS URL follows this format:

```bash
https://api.stack-auth.com/api/v1/projects/{YOUR_PROJECT_ID}/.well-known/jwks.json
```

Replace `{YOUR_PROJECT_ID}` with your Stack Auth project ID.

For example, if your project ID is `my-awesome-project`, your JWKS URL would be:

```bash
https://api.stack-auth.com/api/v1/projects/my-awesome-project/.well-known/jwks.json
```

### Stytch

Your Stytch JWKS URL follows this format:

```bash
https://test.stytch.com/v1/sessions/jwks/{YOUR_PROJECT_ID}
```

Replace `{YOUR_PROJECT_ID}` with your Stytch project ID.

For example, if your project ID is `my-awesome-project`, your JWKS URL would be:

```bash
https://test.stytch.com/v1/sessions/jwks/my-awesome-project
```

   **Note**: For production environments, replace `test.stytch.com` with `live.stytch.com`.

### SuperTokens

Your SuperTokens JWKS URL follows this format:

```bash
{YOUR_SUPER_TOKENS_CORE_CONNECTION_URI}/.well-known/jwks.json
```

To find your Core connection URI:

1. Go to the SuperTokens Dashboard
2. Navigate to **Core Management**
3. Copy your Core connection URI



For example, if your connection URI is `https://try.supertokens.io`, your JWKS URL would be:

```bash
https://try.supertokens.io/.well-known/jwks.json
```

### WorkOS

Your WorkOS JWKS URL follows this format:

```bash
https://api.workos.com/sso/jwks/{YOUR_CLIENT_ID}
```

To find your Client ID:

1. Go to the WorkOS Dashboard
2. Navigate to the **Overview** page
3. Copy your **Client ID**



For example, if your Client ID is `client_12345`, your JWKS URL would be:

```bash
https://api.workos.com/sso/jwks/client_12345
```

## Next steps

After configuring your authentication provider, include the JWT in your Data API requests:

```http
GET https://your-project.data.neon.tech/v1/posts
Authorization: Bearer {your_jwt_token}
```

Then set up [Row-Level Security policies](https://neon.com/docs/data-api/get-started#create-a-table-with-rls) to control data access using the `auth.user_id()` function, which extracts the user ID from your JWT.