Skip to content

Commit

Permalink
Updated and clarified JWT documentation (#1146)
Browse files Browse the repository at this point in the history 
- Added a note that AUTH_JWT_NAMESPACE does not affect the validation of
the standard claims, like the `aud` check you enable with AUTH_JWT_AUD.
- Updated a reference to `user_id` that did not use the newer `sub`.
- Fixed some spelling errors

---------

Co-authored-by: Oleksii Sholik <accounts+github@alco.dev>
  • Loading branch information
@fooware @alco
fooware and alco committed May 19, 2024
1 parent 2d231bc commit f06bebf
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 9 deletions.
4 changes: 2 additions & 2 deletions clients/typescript/src/cli/config-options.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ export const configOptions: Record<string, any> = {
valueType: String,
valueTypeName: 'iss',
doc: dedent`
This optional setting allows you to specificy the "issuer" that will be matched
This optional setting allows you to specify the "issuer" that will be matched
against the iss claim extracted from auth tokens.
`,
groups: ['electric'],
Expand All @@ -290,7 +290,7 @@ export const configOptions: Record<string, any> = {
valueType: String,
valueTypeName: 'aud',
doc: dedent`
This optional setting allows you to specificy the "audience" that will be matched
This optional setting allows you to specify the "audience" that will be matched
against the aud claim extracted from auth tokens.
`,
groups: ['electric'],
Expand Down
10 changes: 5 additions & 5 deletions components/electric/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,15 +91,15 @@ The Electric application is configured using environment variables. Everything t
| `ELECTRIC_WRITE_TO_PG_MODE` | `logical_replication` | <p>The mode to use when syncing client updates to Postgres.</p><p>Allowed values: `logical_replication`, `direct_writes`.</p> |
| `HTTP_PORT` | `5133` | Port for HTTP connections. Includes client websocket connections on `/ws`, and other functions on `/api`. |
| | | |
| `PG_PROXY_PORT` | `65432` | <p>Port number for connections to the [Postgres migrations proxy][1].</p><p>If you have Electric deployed behind a restrictive firewall that only allows HTTP/HTTPS connections, you can add the `http:` prefix to the port number. This will enable the tunelling mode in which the migrations proxy will accept WebSocket connections from the proxy tunnel (`npx electric-sql proxy-tunnel`).</p> |
| `PG_PROXY_PORT` | `65432` | <p>Port number for connections to the [Postgres migrations proxy][1].</p><p>If you have Electric deployed behind a restrictive firewall that only allows HTTP/HTTPS connections, you can add the `http:` prefix to the port number. This will enable the tunnelling mode in which the migrations proxy will accept WebSocket connections from the proxy tunnel (`npx electric-sql proxy-tunnel`).</p> |
| `PG_PROXY_PASSWORD` | | Password to use when connecting to the Postgres proxy via `psql` or any other Postgres client. |
| | | |
| `AUTH_MODE` | `"secure"` | Authentication mode to use to authenticate Satellite clients. See below. |
| `AUTH_JWT_ALG` | | <p>The algorithm to use for JWT verification. Electric supports the following algorithms:</p><ul><li>`HS256`, `HS384`, `HS512`: HMAC-based cryptographic signature that relies on the SHA-2 family of hash functions.</li><li>`RS256`, `RS384`, `RS512`: RSA-based algorithms for digital signature.</li><li>`ES256`, `ES384`, `ES512`: ECC-based algorithms for digital signature.</li></ul> |
| `AUTH_JWT_KEY` | | The key to use for JWT verification. Must be appropriate for the chosen signature algorithm. For `RS*` and `ES*` algorithms, the key must be in PEM format. |
| `AUTH_JWT_NAMESPACE` | | <p>This is an optional setting that specifies the location inside the token of custom claims that are specific to Electric.</p><p>Currently, only the `user_id` custom claim is required.</p |
| `AUTH_JWT_ISS` | | <p>This optional setting allows you to specificy the "issuer" that will be matched against the `iss` claim extracted from auth tokens.</p><p>This can be used to ensure that only tokens created by the expected party are used to authenticate your Satellite client.</p> |
| `AUTH_JWT_AUD` | | <p>This optional setting allows you to specificy the "audience" that will be matched against the aud claim extracted from auth tokens.</p><p>This can be used to ensure that only tokens for a specific application are used to authenticate your Satellite client.</p> |
| `AUTH_JWT_NAMESPACE` | | <p>This is an optional setting that specifies the location inside the token of custom claims that are specific to Electric.</p><p>Currently, only the `sub` (formerly `user_id`) custom claim is required.</p |
| `AUTH_JWT_ISS` | | <p>This optional setting allows you to specify the "issuer" that will be matched against the `iss` claim extracted from auth tokens.</p><p>This can be used to ensure that only tokens created by the expected party are used to authenticate your Satellite client.</p> |
| `AUTH_JWT_AUD` | | <p>This optional setting allows you to specify the "audience" that will be matched against the `aud` claim extracted from auth tokens.</p><p>This can be used to ensure that only tokens for a specific application are used to authenticate your Satellite client.</p> |
| | | |
| `ELECTRIC_INSTANCE_ID` | `electric` | Unique identifier of this Electric instance when running in a cluster (not yet supported). When running locally, you can use any string |

Expand Down Expand Up @@ -140,7 +140,7 @@ In order to run migrations (both in production and in development) you need to c

The proxy will detect any modifications to electrified tables and ensure they are propagated to all satellite clients. It also allows the use of our [extended DDLX syntax](https://electric-sql.com/docs/api/ddlx).

We use various heuristics to recognise the migration framework in use in order to keep the migration version applied to the satellite clients in sync with the version applied by the framework. If your framework isn't currently supported or you would like to override the assigned version then use the `electric.migration_version` procedure:
We use various heuristics to recognize the migration framework in use in order to keep the migration version applied to the satellite clients in sync with the version applied by the framework. If your framework isn't currently supported or you would like to override the assigned version then use the `electric.migration_version` procedure:

```sql
BEGIN;
Expand Down
6 changes: 4 additions & 2 deletions docs/usage/auth/secure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,15 +148,17 @@ By default, if this setting is omitted or is set to an empty string, the `sub` /
}
```

Note that standard claims are not affected by this setting and are always looked up at the top level.

### `AUTH_JWT_ISS`

This setting allows you to specificy the "issuer" that will be matched against the `iss` claim extracted from auth tokens. This can be used to ensure that only tokens created by the expected party are used to authenticate your client.
This setting allows you to specify the "issuer" that will be matched against the `iss` claim extracted from auth tokens. This can be used to ensure that only tokens created by the expected party are used to authenticate your client.

Leaving this variable empty makes the `iss` claim optional and doesn't verify its value even if it's included in token claims.

### `AUTH_JWT_AUD`

This setting allows you to specificy the "audience" that will be matched against the `aud` claim extracted from auth tokens. This can be used to ensure that only tokens for a specific application are used to authenticate your client.
This setting allows you to specify the "audience" that will be matched against the `aud` claim extracted from auth tokens. This can be used to ensure that only tokens for a specific application are used to authenticate your client.

Leaving this variable empty makes the `aud` claim optional and doesn't verify its value even if it's included in token claims.

Expand Down

0 comments on commit f06bebf

Please sign in to comment.