pg_session_jwt

pg_session_jwt is a PostgreSQL extension designed to handle authenticated sessions through a JWT. This JWT is then verified against a JWK (JSON Web Key) to ensure its authenticity.

JWK can only be set at postmaster startup, from the configuration file, or by client request in the connection startup packet (e.g., from libpq's PGOPTIONS variable), whereas the JWT can be set anytime at runtime. The extension then stores the JWT in the database for later retrieval, and exposes functions to retrieve the user ID (the sub subject field) and other parts of the payload.

The goal of this extension is to provide a secure and efficient way to manage authenticated sessions in a PostgreSQL database. The JWTs can be generated by third-party auth providers, and then developers can leverage the JWT for Row Level Security (RLS) policies, or to retrieve the user ID for other purposes (column defaults, filters, etc.).

This extension powers Neon Authorize, but it is portable to any Postgres provider or self-managed Postgres deployments.

Warning

This extension is under active development. The API is subject to change.

Features

• Initialize JWT sessions using a JWK (JSON Web Key).

• Retrieve the user ID or other session-related information directly from the database.

• Simple JSONB-based storage and retrieval of session information.

Usage

Before calling functions make sure that pg_session_jwt.jwk parameter is properly initialized. libpq connect options can be used for that.

For example:

MY_JWK=...
export PGOPTIONS="-c pg_session_jwt.jwk=$MY_JWK"

pg_session_jwt exposes four main functions:

1. auth.init() → void

Initializes a session using JWK stored in pg_session_jwt.jwk run-time parameter. Please remember that this parameter is fixed for a given connection once it's started (but it can vary across different connections)

2. auth.jwt_session_init(jwt text) → void

Initializes the JWT session with the provided jwt as a string. JWT must be signed by the JWK that was initialized with auth.init()

3. auth.session() → jsonb

Retrieves JWT session data.

4. auth.user_id() → text

Returns the user ID associated with the current session. This is retrieved from the "sub" ("subject") field of the JWT.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Contact

For issues, questions, or support, please open an issue on the GitHub repository.

Security

Neon adheres to the securitytxt.org standard for transparent and efficient security reporting. For details on how to report potential vulnerabilities, please visit our Security reporting page or refer to our security.txt file.

If you have any questions about our security protocols or would like a deeper dive into any aspect, our team is here to help. You can reach us at [email protected].