Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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"]
}
Expand All @@ -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.
Expand Down
1 change: 1 addition & 0 deletions docs/service-integration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
2 changes: 2 additions & 0 deletions src/auth/policy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
});
Expand All @@ -83,6 +84,7 @@ describe("identity states", () => {
polinetwork_states: "",
polinetwork_roles: "",
polinetwork_permissions: "",
polinetwork_permission_list: [],
polinetwork_telegram_id: "",
groups: [],
});
Expand Down
3 changes: 3 additions & 0 deletions src/auth/policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading