Skip to main content

Configure authentication for Aiven for PostgreSQL® Data API Limited availability

Data API authenticates every request with a bearer token in the Authorization header. The token is a JWT issued by your own identity provider (IdP) and verified against your JWKS URL. The token carries a role, and your Aiven for PostgreSQL® database enforces that role's privileges.

note

Data API is a Limited availability feature.

Authenticate with your identity provider​

End users authenticate with the JWTs issued by your IdP. You provide your JWKS URL when you enable Data API, and Data API verifies each token against the public keys at that URL.

note

Data API uses one identity provider per database, set by a single JWKS URL. You can update the JWKS URL or audience later from the Data API page in the Aiven Console.

Configure the JWKS URL​

The JSON Web Key Set (JWKS) URL is the endpoint where your IdP publishes the public keys used to verify token signatures. The URL is required and must use HTTPS.

The URL format depends on your IdP. The following are common patterns:

  • Auth0: https://TENANT_NAME.us.auth0.com/.well-known/jwks.json
  • Okta: https://OKTA_DOMAIN/oauth2/default/v1/keys
  • Microsoft Entra ID: https://login.microsoftonline.com/TENANT_ID/discovery/v2.0/keys

Replace TENANT_NAME, OKTA_DOMAIN, and TENANT_ID with the values from your IdP. For the exact URL, see your IdP's documentation.

When you enable Data API or update the JWKS URL, the Aiven Console fetches the URL and checks that it returns a valid JWKS document: an HTTP 200 response with a JSON body that contains a non-empty keys array, where each key has a kty field. If the check fails, the console rejects the value and shows the reason, for example that the endpoint is unreachable or returned an error.

note

This check confirms that the URL is reachable and returns a well-formed JWKS document when you save it. It doesn't detect a JWKS URL that becomes unreachable later, or one that's reachable but serves the wrong IdP's keys; either causes requests to fail at runtime.

Because Data API reads the keys from the JWKS URL, key rotation is automatic. When your IdP rotates its signing keys, Data API picks up the new keys from the same URL. You don't need to update any configuration in the Aiven Console. Data API refreshes the keys periodically, about every 12 hours, so allow time for new keys to take effect and keep the previous keys valid during the overlap.

Configure the audience​

The audience identifies the intended recipient of a token, such as a specific API or tenant. The audience is optional. If you set it, use the same value in your IdP and in the Audience field when you enable Data API; Data API then rejects any token whose aud claim doesn't match. If you leave it blank, Data API doesn't check the aud claim.

Authorize requests with PostgreSQL roles​

Data API uses standard PostgreSQL roles and table privileges for authorization. The token carries a role claim that names the role to use, and PostgreSQL enforces that role's privileges.

Roles Data API creates automatically​

When you enable Data API for a database, Aiven creates two PostgreSQL roles for it. You don't need to create either role yourself:

  • postgrest_authenticator: The role Data API uses to connect to your database, instead of your service's admin user. It can only assume roles that you explicitly grant to it, so a request can never access more than what you've granted.
  • web_anon: The default role for requests whose token doesn't include a role claim. It has no privileges.
note

If a token doesn't include a role claim, the request runs as web_anon. Include a role claim in every token that needs to access data.

Create a role and grant privileges​

Connect to your database and create a role with the privileges to expose, then grant it to postgrest_authenticator so Data API can assume it:

-- Create the role
CREATE ROLE api_worker NOLOGIN;

-- Grant schema access
GRANT USAGE ON SCHEMA public TO api_worker;

-- Grant table and sequence privileges
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO api_worker;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO api_worker;

-- Link the role to the PostgREST authenticator
GRANT api_worker TO postgrest_authenticator;

Adjust the granted privileges to match what each role should be able to do. A role with SELECT only can read data, while a leaked token for that role can't modify it.

Add the role to your IdP tokens​

Configure your IdP to include a role claim in its tokens, set to the PostgreSQL role name, such as api_worker. The following example adds the claim in Auth0.

This example assumes you already have an API and a Machine-to-Machine application authorized for it in Auth0. If you just created the API, Auth0 automatically creates a companion Test Application that's already authorized for it, so you can use that instead of creating your own. If you create your own application, authorize it explicitly: open the API's Application Access tab, select your application, go to its Client Access tab, and click Grant Access.

  1. In Auth0, go to Actions > Library, then click Create Action > Create Custom Action.

  2. Name the action and set the trigger to M2M / Client-Credentials. Leave Runtime at its recommended default.

  3. Auth0 creates an empty onExecuteCredentialsExchange function. Add this line inside its body:

    // Replace 'api_worker' with the name of your PostgreSQL role
    api.accessToken.setCustomClaim('role', 'api_worker');

  4. Click Save Draft, then Deploy.

  5. Go to Actions > Triggers, click the credentials-exchange trigger under Machine to Machine, and drag your action from the Custom tab into the flow between Start and Complete.

  6. Click Apply.

When requesting a token, include the audience parameter so the IdP issues a token valid for Data API.

tip

Grant each role only the privileges it needs. The token controls which role runs the query, and PostgreSQL enforces the privileges of that role.