Skip to content

Commit e05d676

Browse files
committed
Merge OIDC group docs and timestamp fix from the scheduler base
2 parents 011d9ab + 2c90584 commit e05d676

4 files changed

Lines changed: 101 additions & 2 deletions

File tree

‎src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Online: https://sqlbuild.com/docs/cli/server/
99
## Contents
1010

1111
- Set retention
12+
- Grant roles to OIDC groups (beta)
1213
- Inspect published SQL
1314
- Define project roles
1415

@@ -62,6 +63,53 @@ An invalid value stops the server before it opens the control database. Servers
6263
control database delete at the shortest horizon among them and count only their own audit
6364
webhook, so give them the same values and webhook.
6465

66+
## Grant roles to OIDC groups (beta)
67+
68+
With OIDC sign-in, members of an identity-provider group can get a role without a per-person
69+
assignment. Add `groups_claim` and `group_roles` to the JSON file passed to `--oidc-config`:
70+
71+
```json
72+
{
73+
"origin": "https://control.example.com",
74+
"issuer": "https://login.example.com",
75+
"client_id": "orders-control",
76+
"identities": {"orders-person": "0190c3c1-5a4e-7b8e-9f00-2a7d1c9e4b11"},
77+
"groups_claim": "groups",
78+
"group_roles": [
79+
{"group": "orders-operators", "role": "operator", "location_id": "0190c3c1-6b2f-7c3d-8e44-5f1a2b3c4d5e", "target": null},
80+
{"group": "orders-readers", "role": "viewer", "location_id": null, "target": null}
81+
]
82+
}
83+
```
84+
85+
| Key | Meaning |
86+
| --- | --- |
87+
| `groups_claim` | ID-token claim that lists the person's groups. Required when `group_roles` is set. |
88+
| `group_roles[].group` | Group name exactly as the claim lists it. |
89+
| `group_roles[].role` | `viewer`, `operator`, `developer` or a project role the location publishes. Not `admin`. |
90+
| `group_roles[].location_id` | Limits the role to one location. Required for a project role or a target. |
91+
| `group_roles[].target` | Limits the role to one target in that location. |
92+
93+
Groups grant roles only to people who already have an entry in `identities`; a group never
94+
creates an account. Group roles add to the person's own role assignments.
95+
96+
The server reads groups only from the signed ID token, at sign-in. Each sign-in replaces the
97+
person's groups with the ones in that token:
98+
99+
- Removing someone from a group in the identity provider stops the grant at their next sign-in.
100+
Until then, all of their sessions use the groups from their most recent sign-in.
101+
- Removing or changing a `group_roles` entry and restarting the server changes access at once,
102+
without a new sign-in.
103+
- A claim that is missing, is not a list of non-empty names, or is replaced by an overage pointer
104+
gives no groups.
105+
106+
The server refuses to start when a mapping grants `admin`, scopes a project role or target without
107+
a location, has a blank group, or when `group_roles` is set without `groups_claim`.
108+
109+
Servers that share one control database must use identical OIDC and `group_roles` configuration.
110+
Different configurations on one database are unsupported: the last server to start decides the
111+
group mapping for all of them.
112+
65113
## Inspect published SQL
66114

67115
Sign in with [`sqb login`](login.md), then inspect one exact node in the current

‎tests/integration/src/sqlbuild/compiler/compiled_project/publication/test_reload.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import subprocess
77
import sys
88
import time
9+
from datetime import datetime
910
from pathlib import Path
1011
from typing import Any
1112

@@ -199,7 +200,9 @@ def test_given_a_served_location_when_inputs_change_or_restart_then_generations_
199200
assert (
200201
restarted_health["report"]["session_id"] != initial_health["report"]["session_id"]
201202
)
202-
assert restarted_health["received_at"] >= initial_health["received_at"]
203+
assert datetime.fromisoformat(
204+
restarted_health["received_at"]
205+
) >= datetime.fromisoformat(initial_health["received_at"])
203206
# Redirected output and compiler cache writes must not feed the input watcher.
204207
time.sleep(1)
205208
assert current_snapshot(api, test_case.target)["record"] == restarted["record"]

‎tests/integration/src/sqlbuild/compiler/compiled_project/publication/test_worker.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import sqlite3
77
import time
88
from dataclasses import replace
9+
from datetime import datetime
910
from pathlib import Path
1011
from typing import Any
1112
from urllib.request import Request, urlopen
@@ -159,7 +160,7 @@ def test_given_a_scheduled_group_when_workers_execute_then_dependencies_and_fail
159160
for name, statuses in test_case.expected_child_statuses.items()
160161
)
161162
assert (runs["marts"]["started_at"] is not None) == test_case.expected_marts_started
162-
assert runs["staging"]["ended_at"] <= (
163+
assert datetime.fromisoformat(runs["staging"]["ended_at"]) <= datetime.fromisoformat(
163164
runs["marts"]["started_at"] or runs["staging"]["ended_at"]
164165
)
165166
with sqlite3.connect(worker.control_store) as control:

‎website/src/content/docs/docs/cli/server.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,53 @@ An invalid value stops the server before it opens the control database. Servers
5555
control database delete at the shortest horizon among them and count only their own audit
5656
webhook, so give them the same values and webhook.
5757

58+
## Grant roles to OIDC groups (beta)
59+
60+
With OIDC sign-in, members of an identity-provider group can get a role without a per-person
61+
assignment. Add `groups_claim` and `group_roles` to the JSON file passed to `--oidc-config`:
62+
63+
```json
64+
{
65+
"origin": "https://control.example.com",
66+
"issuer": "https://login.example.com",
67+
"client_id": "orders-control",
68+
"identities": {"orders-person": "0190c3c1-5a4e-7b8e-9f00-2a7d1c9e4b11"},
69+
"groups_claim": "groups",
70+
"group_roles": [
71+
{"group": "orders-operators", "role": "operator", "location_id": "0190c3c1-6b2f-7c3d-8e44-5f1a2b3c4d5e", "target": null},
72+
{"group": "orders-readers", "role": "viewer", "location_id": null, "target": null}
73+
]
74+
}
75+
```
76+
77+
| Key | Meaning |
78+
| --- | --- |
79+
| `groups_claim` | ID-token claim that lists the person's groups. Required when `group_roles` is set. |
80+
| `group_roles[].group` | Group name exactly as the claim lists it. |
81+
| `group_roles[].role` | `viewer`, `operator`, `developer` or a project role the location publishes. Not `admin`. |
82+
| `group_roles[].location_id` | Limits the role to one location. Required for a project role or a target. |
83+
| `group_roles[].target` | Limits the role to one target in that location. |
84+
85+
Groups grant roles only to people who already have an entry in `identities`; a group never
86+
creates an account. Group roles add to the person's own role assignments.
87+
88+
The server reads groups only from the signed ID token, at sign-in. Each sign-in replaces the
89+
person's groups with the ones in that token:
90+
91+
- Removing someone from a group in the identity provider stops the grant at their next sign-in.
92+
Until then, all of their sessions use the groups from their most recent sign-in.
93+
- Removing or changing a `group_roles` entry and restarting the server changes access at once,
94+
without a new sign-in.
95+
- A claim that is missing, is not a list of non-empty names, or is replaced by an overage pointer
96+
gives no groups.
97+
98+
The server refuses to start when a mapping grants `admin`, scopes a project role or target without
99+
a location, has a blank group, or when `group_roles` is set without `groups_claim`.
100+
101+
Servers that share one control database must use identical OIDC and `group_roles` configuration.
102+
Different configurations on one database are unsupported: the last server to start decides the
103+
group mapping for all of them.
104+
58105
## Inspect published SQL
59106

60107
Sign in with [`sqb login`](/docs/cli/login/), then inspect one exact node in the current

0 commit comments

Comments
 (0)