Endpoints

Endpoints#

Every endpoint the package publishes, by layer.

Important

Every REST service is registered with zope2.View, and authorization happens inside the service class. Reading the registration alone understates what a caller needs. The "Requires" column below is what the code actually enforces.

Core layer#

Present in every installation.

Method	Path	Requires	Purpose
GET	`@login-providers`	anonymous	Providers to offer on the login page. Enabled and shown only. Also available as a `plone.restapi` expander.
POST	`@identity-callback`	anonymous	The provider redirects here; completes a sign-in.
POST	`@magic-link`	anonymous	Send a single-use sign-in link. Answers identically whether or not the address is known.
POST	`@magic-link-confirm`	anonymous	Redeem a link. Burns the token.
GET	`@my-profile`	authenticated	The caller's own profile.
GET	`@identities`	authenticated	The caller's own sign-in methods.
POST	`@identities`	authenticated	Link a new sign-in method.
DELETE	`@identities/<provider>/<subject>`	authenticated	Unlink one. Refused for the last remaining method.
GET	`@types`	authenticated	The profile content types.
PATCH	`@users`	see source	Update profile fields.
GET	`@portrait`	see source	A profile portrait.
GET	`@group-members/<group id>`	`Manage users`, or membership of the group	Members of a group.
GET	`@user-account/<userid>`	`Manage users`	One user's sign-in methods, for administrators.
GET	`@identity-drivers`	`Manage portal`	Drivers available to configure.
GET	`@identity-providers`	`Manage portal`	Configured providers, or one with `/<id>`. Secrets are masked. A bare `GET` also carries the form schema.
POST	`@identity-providers`	`Manage portal`	Add a provider.
POST	`@identity-providers/<id>/test-connection`	`Manage portal`	Fetch the provider's discovery document, cache cleared first, and report what came back.
PATCH	`@identity-providers/<id>`	`Manage portal`	Change one.
DELETE	`@identity-providers/<id>`	`Manage portal`	Remove one. Linked identities are kept.
GET	`@audit-log`	`Manage portal`	Authentication events.

@group-members is the one with a compound rule: Manage users, or membership of the group being asked about.

Three answers worth knowing#

Endpoint	Answers
`@my-profile`	Where the caller's `UserProfile` is, what workflow state it is in, and the addresses it carries. Each `emails` entry has `verified` and `preferred`, the second marking the one `email` resolves to—so a page can show it without repeating the rule that picks it. The frontend uses this to send a new user to their profile once and never ask again.
`@group-members`	The people in one group, named rather than only listed as userids, plus the nesting around it and a search within it. `@groups/<id>` already carries member userids through PlonePAS; what it cannot do is name each person or search inside the group.
`@user-account`	Which providers a person has configured—named, dated, and flagged when the provider has since been disabled or removed—and when they last authenticated. One user at a time: the audit log is bounded per user, so folding this into the `@users` listing would read one bounded log per row.

@user-account allows a caller asking about themselves without Manage users.

Server layer#

Published only where the pas.plugins.identity.server:default profile has been applied. These are bound to IIdentityServerLayer, so a site without that profile does not publish them at all.

Method	Path	Requires	Purpose
GET	`@identity-clients`	`Manage portal`	Registered OAuth clients, or one with `/<id>`.
POST	`@identity-clients`	`Manage portal`	Register one. The secret is in this response and nowhere else.
POST	`@identity-clients/<id>/rotate-secret`	`Manage portal`	Mint a fresh secret. Same warning applies.
PATCH	`@identity-clients/<id>`	`Manage portal`	Change title, redirect URIs, grants, scope, service user, and enabled. `client_id` and `auth_method` are not editable, and an unknown field is refused rather than ignored.
DELETE	`@identity-clients/<id>`	`Manage portal`	Remove one.
GET	`@identity-keys`	`Manage portal`	Describe the signing ring.
POST	`@identity-keys/rotate`	`Manage portal`	Rotate the signing key. Older keys stay in the ring so tokens already issued keep verifying.
GET	`@oauth-consent`	authenticated	What a client is asking for, for the consent screen.
GET	`@oauth-grants`	authenticated	Applications the caller has granted access to.
DELETE	`@oauth-grants/<client id>`	authenticated	Withdraw one.

Browser views#

Path	Layer	Purpose
`@@identity-controlpanel`	core	The control panel view.
`@@backchannel-logout`	core	Receives a logout token from a provider. See How to enable back-channel logout.
`@@oauth-authorize`	server	The authorization endpoint. Public: the browser reaching it may be anonymous, and the view refuses an unauthenticated end user itself with the error code the specification names.
`@@oauth-token`	server	The token endpoint. Public: the caller is a server holding client credentials, authenticated inside against the client registry.
`@@oauth-jwks`	server	The signing keys, as JWKS.
`@@oauth-userinfo`	server	The userinfo endpoint.
`/.well-known/openid-configuration`	server	The discovery document.

Back-channel logout#

POST @@backchannel-logout

One endpoint serves every configured provider. The logout token names its issuer, and that is how the package chooses the provider, and therefore the key to verify the signature with.

The endpoint follows OpenID Connect Back-Channel Logout 1.0. A token must satisfy all of the following:

Check	Refused when
Signature	Not valid against the issuer's published key.
Issuer and audience	Either does not match.
`iat`	Outside the acceptable window.
`jti`	Already acted on. A repeat is a replay.
Event	No back-channel logout event declared.
Subject	Neither a `sub` nor a `sid` present.
`nonce`	Present. A nonce means somebody is passing an `id_token` off as a logout instruction.

Note

Only sub-based logout is supported. This package does not track provider session identifiers, so a token carrying only a sid is refused.

A logout for an identity this site has never seen answers 200, not an error. There is nothing to end, and answering differently would tell an unauthenticated caller which of a provider's subjects have accounts here.

To enable it, see How to enable back-channel logout.

Why `.well-known` is registered oddly#

The path segment contains a dot, which a Zope view name cannot carry through traversal in the usual way. So .well-known is registered as the view, and the document name is traversed into it. A bare /.well-known/ is refused.

The published path is what a client expects:

https://id.example.com/.well-known/openid-configuration

Endpoints

Contents