Shipped drivers

Shipped drivers#

A driver is registered as a named ZCA utility providing IDriver, and the utility name is the driver id. Five ship with the package.

Driver id	Title	Provider
`oidc-generic`	OpenID Connect	Any conforming OpenID Connect provider.
`plone-identity`	Plone site	Another Plone site running the `[server]` layer. Built on `oidc-generic`.
`google`	Google	Google, through discovery at an issuer the driver fixes.
`github`	GitHub	GitHub OAuth2. Not an OpenID Connect provider.
`email`	Email	No external provider: this site emails a single-use signed token.

Attributes#

Every column is a class attribute on the driver, and every one of them is only a default. What a given deployment trusts a given provider with is a fact about the deployment, so the operator can override each one per provider.

	`oidc-generic`	`plone-identity`	`google`	`github`	`email`
Settings schema	`IOIDCSettings`	`IPloneIdentitySettings`	`IOAuth2Settings`	`IGitHubSettings`	`IEmailSettings`
Endpoints from	discovery, at an issuer you type	discovery, at an issuer you type	discovery, at `https://accounts.google.com`	fixed, built in	none
Default scope	`openid email profile`	`openid email profile address`	`openid email profile`	`read:user user:email`	—
Subject read from	`sub`	`sub`	`sub`	`id`, then `node_id`	`email`
Default userid source	`uuid`	`username`	`uuid`	`username`	`uuid`
Trusts `email_verified` by default	no	no	yes	yes	—
Default group claim	`groups`	`groups`	none	none	none
Can be linked from a form	yes	yes	yes	yes	no

email is the only driver a user cannot start a link against from a form: its subject is an address the user would type, and a free-text box there is a box for claiming any address at all. Its addresses come from the profile instead.

Which settings each schema carries#

This is what decides which fields a provider's form shows. A driver on IOAuth2Settings has no issuer field and no group fields at all.

Schema	Extends	Adds
`IDriverSettings`	`Interface`	nothing
`IOAuth2Settings`	`IDriverSettings`	`client_id`, `client_secret`, `scope`, `userid_source`, `trust_email_verification`, `create_user`, `accept_string_booleans`, `auto_link_by_email`
`IOIDCSettings`	`IOAuth2Settings`	`issuer`, `group_claim`, `allowed_groups`, `sync_groups`, `picture_over_http`
`IGitHubSettings`	`IOAuth2Settings`	nothing
`IPloneIdentitySettings`	`IOIDCSettings`	nothing but a different `issuer` description
`IEmailSettings`	`IDriverSettings`	`token_ttl`, `rate_limit_per_hour`

Two consequences worth reading off that table:

google and github have no group settings. Not a group claim you can name, not an allowed-groups list, not a sync switch. Neither provider sends groups this package can read.
email has no account settings. No create_user, no auto_link_by_email, no trust_email_verification. A missing create_user reads as True, so an email provider always creates accounts.

See Settings for each field's type and default, and The provider form for how they are arranged in the control panel.

Default property maps#

Seeded into a new provider's attribute mapping, written against the normalized claim names rather than any one provider's.

Driver	Map
`oidc-generic`, `google`, `github`	`email` → `email`, `fullname` → `fullname`
`plone-identity`	those two, plus `website` → `home_page`, `description` → `description`, `address.formatted` → `location`, `picture_url` → `portrait`
`email`	`email` → `email`

No driver maps username. Providers publish it; Plone has no property for it.

Driver notes#

github: GET /user omits the address of anybody who marked it private and carries no email_verified at all, so the driver names GET /user/emails as an enrichment endpoint and the flow fetches it after userinfo. That call is best-effort: a narrowed scope answers 403, and a login is not the moment to fail over an address. Every address on the account goes onto the person's profile, the account's own primary first.
google: Its issuer is fixed at https://accounts.google.com rather than typed. There is nothing to configure and nothing to get wrong.
plone-identity: A peer is a conforming OIDC provider and gets no special path through the flow. What the driver carries is the configuration a peer can be known in advance to want: the address scope, a map for every claim the peer actually releases, and the peer's preferred_username as the local userid, so one person is recognisable by the same name across the federation.
email: See below.

To add a driver for a provider not listed here, see How to write a driver.

Group claims#

A driver declares whether its providers assert group membership, and that declaration is what offers the group map in the control panel. A driver with no group claim offers no field to name one, and a group map stored against such a provider grants nothing rather than guessing at a claim name.

groups is not a registered OIDC claim. It is the name Keycloak, Okta and Entra all use, and the one this package's own [server] layer releases. Set a dotted path for a provider that nests them, such as realm_access.roles.

Mapping and revocation are covered in How to map provider groups.

The `email` driver#

Property	Value
Token lifetime	At most fifteen minutes, whatever `token_ttl` says.
Reuse	Single use. The token is burned server side.
Rate limit	Per address and per IP.
Response to an unknown address	Identical to the response for a known address.

The rate limit applies per IP as well as per address because limiting per address alone misses the enumeration attack, which uses a fresh address every time. The send endpoint answers identically whether or not the address belongs to an account: a different answer would be an account-existence oracle.

A magic-link sign-in is the only email verification this package trusts for linking decisions. See About email verification.

Two kinds of link#

Link	Asked for from	Effect	Redeemed at
Sign-in	The login page	Signs its holder in	`@magic-link-confirm`
Confirmation	Sign-in methods	Adds the address to the account that asked for it, and signs nobody in	its own endpoint

Each endpoint accepts only the purpose it handles, so neither link can be redeemed as the other.

A confirmation link has to be opened while the account that asked for it is still signed in. Opening it as somebody else, or as nobody, is refused—and the link is spent either way.