@@ -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
6263control database delete at the shortest horizon among them and count only their own audit
6364webhook, 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
67115Sign in with [ ` sqb login ` ] ( login.md ) , then inspect one exact node in the current
0 commit comments