Custom

For a quick way to get started before implementing custom auth, Development Tokens can be used instead.

Any authentication provider can be supported by generating custom JWTs for PowerSync.

The process is as follows:

1. The client authenticates the user using the app's authentication provider and typically gets a session token - either a third-party authentication provider or a custom one.

2. The client makes a backend call (authenticated using the above session token), which generates and signs a JWT for PowerSync.

3. The client connects to the PowerSync service using the above JWT.

4. PowerSync verifies the JWT.

The requirements are:

1. An RSA key-pair (private + public key) is required to sign and verify JWTs.

2. The JWT must be signed using the RS256, RS384 or RS512 algorithm with the private key.

3. The public key must be available on a public URL in JWKS format.

4. The aud of the JWT must match the PowerSync instance URL.

   1. To get the instance URL of a PowerSync instance: In the project tree on the PowerSync dashboard, right-click on the instance, click "Edit Instance" and then see "Instance URL".

   2. Alternatively, specify a custom audience in the instance settings.

5. The JWT must have a kid matching one of the keys in the JWKS URL.

6. The JWT must expire in 60 minutes or less. Specifically, both iat and exp fields must be present, with a difference of 3600 or less between the two.

7. The user id must be used as the sub of the JWT.

8. Additional fields can be added in parameters: {} which can be used as token_parameters in sync rules.

Refer to this example for creating and verifying JWTs for PowerSync authentication.

Since there is no way to revoke a JWT once issued without rotating the key, we recommend using short expiration periods (e.g. 5 minutes). JWTs older than 60 minutes are not accepted by PowerSync.

Rotating Keys

If a private key is compromised, rotate they key on the JWKS endpoint.

PowerSync refreshes the keys from the endpoint every couple of minutes, after which old tokens will not be accepted anymore.

There is a possibility of false authentication errors for a couple until PowerSync refreshes the keys. These errors are typically retried by the client and will have little impact. However, to periodically rotate keys without any authentication failures, follow this process:

1. Add a new key to the JWKS endpoint.

2. Wait an hour (or more) to make sure PowerSync has the new key.

3. Start signing new JWT tokens using the new key.

4. Wait until all existing tokens have expired.

5. Remove the old key from the JWKS endpoint.