diff --git a/README.md b/README.md index 1237528..4d438d6 100644 --- a/README.md +++ b/README.md @@ -297,7 +297,7 @@ snapshot for the future backend integration; no current caller uses it yet. The production issuer is `https://auth.polinetwork.org/api/auth`. Discovery is available at `https://auth.polinetwork.org/api/auth/.well-known/openid-configuration`. -Supported scopes are `openid`, `profile`, `polinetwork:identity`, and `offline_access`. The custom scope adds the identity endpoint URL from `BETTER_AUTH_URL` to ID tokens, access tokens, and UserInfo. It also adds top-level string claims for consumers that cannot read arrays. With the default public origin, the claims are: +Supported scopes are `openid`, `profile`, `polinetwork:identity`, and `offline_access`. The custom scope adds the identity endpoint URL from `BETTER_AUTH_URL` to ID tokens, access tokens, and UserInfo. It also adds top-level claims for consumers that cannot read the URL-named object. Access tokens carry them only when they are JWTs, which happens when the request names a resource (audience); without one the access token is opaque and clients cannot read it, so read the claims from the ID token (request `openid`) or from UserInfo instead. With the default public origin, the claims are: ```json { @@ -310,6 +310,7 @@ Supported scopes are `openid`, `profile`, `polinetwork:identity`, and `offline_a "polinetwork_states": "socio student", "polinetwork_roles": "socio student", "polinetwork_permissions": "membership:read student:verified", + "polinetwork_permission_list": ["membership:read", "student:verified"], "polinetwork_telegram_id": "123456789", "groups": ["socio", "student"] } @@ -324,6 +325,10 @@ spaces between values and are empty strings when no values apply, as is `polinetwork_telegram_id` when no Telegram account is linked. The `/api/identity` response keeps the object format shown inside the URL-named claim. +`polinetwork_permission_list` repeats `permissions` as a top-level array for consumers +that can match only a flat list claim, such as oauth2-proxy (`--oidc-groups-claim`), which +can neither split a string nor reach into the URL-named claim. + `groups` repeats `roles` as an array under the claim name that apps such as Cloudflare Access read for group-based policies. It holds role keys, not display names. Built-in role keys cannot change; renaming a custom role's key breaks policies that match the old key. diff --git a/docs/service-integration-guide.md b/docs/service-integration-guide.md index f09af77..82dd3b9 100644 --- a/docs/service-integration-guide.md +++ b/docs/service-integration-guide.md @@ -28,6 +28,7 @@ Most new services are level 1, or level 1 + 2. Level 3 needs changes to the IdP' 3. **Validate every token:** signature, `iss`, `aud`, `exp`. Use an OIDC library, not hand-written checks. 4. **Authorize with permissions.** `polinetwork:identity` adds: - **`polinetwork_permissions`:** space-separated, empty when the person has none. + - **`polinetwork_permission_list`:** the same permissions as an array, for tools that match a list claim (oauth2-proxy). - **`polinetwork_telegram_id`:** empty when no Telegram account is linked. - **The URL-named object claim**, described in the [README](../README.md#oidc-clients). diff --git a/src/auth/policy.test.ts b/src/auth/policy.test.ts index 9a2fed4..8ba69c4 100644 --- a/src/auth/policy.test.ts +++ b/src/auth/policy.test.ts @@ -68,6 +68,7 @@ describe("identity states", () => { polinetwork_states: "socio student", polinetwork_roles: "socio student", polinetwork_permissions: "membership:read student:verified", + polinetwork_permission_list: ["membership:read", "student:verified"], polinetwork_telegram_id: "123456789", groups: ["socio", "student"], }); @@ -83,6 +84,7 @@ describe("identity states", () => { polinetwork_states: "", polinetwork_roles: "", polinetwork_permissions: "", + polinetwork_permission_list: [], polinetwork_telegram_id: "", groups: [], }); diff --git a/src/auth/policy.ts b/src/auth/policy.ts index 760de1b..5e8fc86 100644 --- a/src/auth/policy.ts +++ b/src/auth/policy.ts @@ -39,6 +39,9 @@ export function oidcIdentityClaims(claimName: string, claims: IdentityClaims) { polinetwork_states: claims.states.join(" "), polinetwork_roles: claims.roles.join(" "), polinetwork_permissions: claims.permissions.join(" "), + // The same permissions as an array, for consumers that match a list claim, such as + // oauth2-proxy's groups claim. Unlike `groups`, these are permissions, not roles. + polinetwork_permission_list: claims.permissions, polinetwork_telegram_id: claims.telegramId ?? "", // The conventional claim for apps that map groups to policies, such as Cloudflare Access. groups: claims.roles,