Skip to content

Commit 030656d

Browse files
levkklevkk
authored
Document more auth (#123)
1 parent 56d2918 commit 030656d

11 files changed

Lines changed: 796 additions & 297 deletions

File tree

‎docs/features/auth/.pages‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
nav:
2+
- 'index.md'
3+
- 'configuration.md'
4+
- 'password.md'
5+
- 'rds-iam.md'
6+
- 'mtls.md'
7+
- '...'
8+
title: Authentication

‎docs/features/auth/azure-workload.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
icon: material/microsoft-azure
3+
---
4+
5+
# Azure Workload Identity
6+
7+
PgDog supports using temporary credentials provided by Azure Workload Identity to connect to PostgreSQL running on Azure. This uses the [Azure SDK](https://github.com/Azure/azure-sdk-for-rust) and supports fetching credentials from the environment.
8+
9+
To use Workload Identity authentication, configure it on each user in [`users.toml`](../../configuration/users.toml/users.md):
10+
11+
=== "users.toml"
12+
13+
```toml
14+
[[users]]
15+
name = "pgdog"
16+
database = "prod"
17+
password = "hunter2"
18+
server_auth = "azure_workload_identity"
19+
```
20+
21+
=== "Helm chart"
22+
23+
```yaml
24+
users:
25+
- name: pgdog
26+
database: prod
27+
password: hunter2
28+
serverAuth: azure_workload_identity
29+
```

‎docs/features/auth/configuration.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
icon: material/account-cog
3+
---
4+
5+
# User configuration
6+
7+
By default, client connections will use password authentication encrypted with SCRAM-SHA-256. This method is secure and recommended for production usage.
8+
9+
PgDog supports using other methods, e.g., `md5`, `plain` and `trust`, which you can change with configuration:
10+
11+
=== "pgdog.toml"
12+
13+
```toml
14+
[general]
15+
auth_type = "scram" # or "md5", "plain", "trust"
16+
```
17+
18+
=== "Helm chart"
19+
20+
```yaml
21+
authType: scram # or "md5", "plain", "trust"
22+
```
23+
24+
## Configuring users
25+
26+
The [`users.toml`](../../configuration/users.toml/users.md) configuration file follows a TOML list structure. To allow a user to connect to PgDog, add a `[[users]]` section with the user name, password and a corresponding database name (located in [`pgdog.toml`](../../configuration/pgdog.toml/databases.md)) to `users.toml`, for example:
27+
28+
=== "users.toml"
29+
30+
```toml
31+
[[users]]
32+
name = "pgdog"
33+
database = "pgdog"
34+
password = "hunter2"
35+
```
36+
37+
=== "Helm chart"
38+
39+
```yaml
40+
users:
41+
- name: pgdog
42+
database: pgdog
43+
password: hunter2
44+
```
45+
46+
The `database` parameter must match the name of one of the databases configured in [`pgdog.toml`](../../configuration/pgdog.toml/databases.md). For example:
47+
48+
=== "users.toml"
49+
50+
```toml
51+
[[users]]
52+
name = "alice"
53+
database = "prod"
54+
password = "hunter2"
55+
```
56+
57+
=== "pgdog.toml"
58+
59+
```toml
60+
[[databases]]
61+
name = "prod"
62+
host = "10.0.0.1"
63+
```
64+
65+
In this example, the `database` parameter in the `[[users]]` **`prod`** entry matches the `[[databases]]` database **`prod`** entry.
66+
67+
!!! warning "User/database mismatch"
68+
69+
If you add a user with a `database` name not specified in `pgdog.toml`, that entry will be ignored by PgDog at runtime and that user will not be able to connect.
70+
71+
The same username, database name and password will also be used by PgDog to connect to PostgreSQL. This makes configuration simpler since the Postgres connection options used by applications don't have to change when PgDog is deployed for the first time.
72+
73+
Read more about configuring users with password authentication [here](password.md).
74+
75+
## Configuring user options
76+
77+
PgDog supports setting user-specific options in `users.toml`. Some settings are overrides of equivalent global defaults set in the `[general]` section of `pgdog.toml`, while others can be set on users exclusively, for example:
78+
79+
=== "pgdog.toml"
80+
81+
```toml
82+
[[users]]
83+
name = "pgdog"
84+
database = "prod"
85+
password = "hunter2"
86+
pool_size = 15
87+
min_pool_size = 5
88+
```
89+
90+
=== "Helm chart"
91+
92+
```yaml
93+
users:
94+
- name: pgdog
95+
database: prod
96+
password: hunter2
97+
poolSize: 15
98+
minPoolSize: 5
99+
```
100+
101+
!!! note "Helm chart"
102+
103+
Convert the setting name to `camelCase` if using our [Helm chart](../../installation.md#kubernetes).
104+
105+
The following settings are supported:
106+
107+
| User setting | Global setting | Description |
108+
| ------------------------ | ------------------------ | -------------------------------------------------------------------------------------- |
109+
| `pooler_mode` | `pooler_mode` | Transaction or session pooling mode. |
110+
| `pool_size` | `default_pool_size` | Size of the user's connection pool. |
111+
| `min_pool_size` | `min_pool_size` | Minimum number of idle connections in the user's pool. |
112+
| `two_phase_commit` | `two_phase_commit` | Enable/disable [two-phase commit](../sharding/2pc/index.md) for this user. |
113+
| `two_phase_commit_auto` | `two_phase_commit_auto` | Enable/disable [automatic](../sharding/2pc/index.md) two-phase-commit for this user. |
114+
| `server_lifetime` | `server_lifetime` | Maximum connection age for this user. |
115+
| `server_lifetime_jitter` | `server_lifetime_jitter` | Jitter added to `server_lifetime` for this user. |
116+
| `cross_shard_disabled` | `cross_shard_disabled` | Disable [cross-shard](../sharding/cross-shard-queries/index.md) queries for this user. |
117+
118+
### User-only settings
119+
120+
In addition to overriding `pgdog.toml` defaults, some settings can only be set on users:
121+
122+
| User setting | Description |
123+
| ------------------- | ---------------------------------------------------------------------------------------------- |
124+
| `statement_timeout` | Equivalent of executing `SET statement_timeout TO <value>` on connection pool creation. |
125+
| `lock_timeout` | Equivalent of executing `SET lock_timeout TO <value>` on connection pool creation. |
126+
| `idle_timeout` | Clients connected for longer than this (in ms) without executing queries will be disconnected. |
127+
128+
#### Example
129+
130+
=== "users.toml"
131+
132+
```toml
133+
[[users]]
134+
name = "alice"
135+
pool_size = 10
136+
statement_timeout = 15_000
137+
```
138+
139+
=== "Helm chart"
140+
141+
```yaml
142+
users:
143+
- name: alice
144+
poolSize: 10
145+
statementTimeout: 15000
146+
```
147+
148+
## Read more
149+
150+
{{ next_steps_links([
151+
("Password authentication", "/features/auth/password/", "Configure password authentication with SCRAM and other supported algorithms."),
152+
("RDS IAM", "/features/auth/rds-iam/", "Passwordless authentication to RDS PostgreSQL and Aurora databases."),
153+
("mTLS", "/features/auth/mtls/", "Passwordless authentication for client and server connections."),
154+
]) }}

‎docs/features/auth/hashicorp-vault.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/safe
3+
---
4+
5+
# HashiCorp Vault
6+
7+
PgDog supports using HashiCorp Vault for authentication to PostgreSQL. Documentation for this hasn't been written yet!

‎docs/features/auth/index.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
icon: material/login
3+
---
4+
5+
# Authentication
6+
7+
PostgreSQL servers support many authentication mechanisms. PgDog supports a subset of those, with the aim to support all of them over time.
8+
9+
Additionally, PgDog supports some non-standard algorithms commonly used in the industry, like RDS IAM, Azure Identity, and others. This makes it relatively easy to deploy to a cloud environment without affecting security.
10+
11+
## Supported methods
12+
13+
The following table summarizes the current level of support for client and server connection authentication methods:
14+
15+
| Authentication method | Client connections | Server connections |
16+
| -------------------------------------------- | ------------------------------- | ------------------------------- |
17+
| [Password](password.md) | :material-check-circle-outline: | :material-check-circle-outline: |
18+
| Trust (no password) | :material-check-circle-outline: | :material-check-circle-outline: |
19+
| [AWS RDS IAM](rds-iam.md) | No | :material-check-circle-outline: |
20+
| [Azure Workload Identity](azure-workload.md) | No | :material-check-circle-outline: |
21+
| [HashiCorp Vault](hashicorp-vault.md) | No | :material-check-circle-outline: |
22+
| [Mutual TLS (mTLS)](mtls.md) | :material-check-circle-outline: | :material-check-circle-outline: |
23+
24+
!!! note "Contributions"
25+
26+
PgDog is an open source project. If you'd like to add an authentication method we don't currently support,
27+
please [open an issue](https://github.com/pgdogdev/pgdog/issues) to discuss.
28+
29+
## Read more
30+
31+
{{ next_steps_links([
32+
("Configuring users", "/features/auth/configuration/", "Configure users with authentication options and other settings."),
33+
("Password authentication", "/features/auth/password/", "Configure password authentication with SCRAM and other supported algorithms."),
34+
("RDS IAM", "/features/auth/rds-iam/", "Passwordless authentication to RDS PostgreSQL and Aurora databases."),
35+
("mTLS", "/features/auth/mtls/", "Passwordless authentication for client and server connections."),
36+
]) }}

0 commit comments

Comments
 (0)