The provider form

The provider form#

Every field the Identity providers control panel shows when you add or edit a provider, arranged as the form arranges it.

The form is generated from the driver's published schema, so a site that installs a third-party driver gets that driver's form with no frontend change. Which tabs appear depends on which driver you picked.

Which tabs each driver shows#

The form is composed from three sources, which is why the tab list is longer than the driver's own fieldsets:

the fields every provider has, from IProviderRecords—the first tab, titled Identity, plus Style;
the driver's own fieldsets, the first titled Settings and the rest keeping their own names;
a Mapping tab composed in the frontend, holding the property map and the group map.

Driver	Tabs
`email`	Identity, Style, Settings, Mapping
`github`	Identity, Style, Settings, Accounts, Mapping
`google`	Identity, Style, Settings, Accounts, Mapping
`oidc-generic`	Identity, Style, Settings, Accounts, Groups, Profile, Mapping
`plone-identity`	Identity, Style, Settings, Accounts, Groups, Profile, Mapping

A driver that declares no fieldsets gets a single Settings tab, which is what email gets and what a third-party driver that never declares one gets.

Driver tab ids are namespaced under settings-, because the backend serves a default fieldset on both halves of this form and two tabs with one id renders only one of them.

A provider's edit form, showing the Identity, Style, Settings, Accounts and Mapping tabs

Identity tab#

Shown for every driver. The first thing asked, and when adding a provider it also carries the driver and the provider id.

Field	Registry key	Type	Default
Title	`title`	`TextLine`	`''`
Enabled	`enabled`	`Bool`	`True`
Show on the login screen	`show_in_login`	`Bool`	`True`
Order	`order`	`Int`	`0`

order is stored rather than derived: records live in a BTree and read back alphabetically, and this is the order the login buttons appear in.

Style tab#

Field	Registry key	Type	Default
Icon	`icon`	`Bytes`	`None`
Background colour	`background_color`	`TextLine`	`''`
Foreground colour	`foreground_color`	`TextLine`	`''`

None of it changes what the provider does. The icon is sanitized on save—see Threat model.

Mapping tab#

Field	Registry key	Type	Default
Property map	`propertymap`	`Dict`	`{}`
Group map	`groupmap`	`Dict`	`{}`

Composed in the frontend rather than served as a fieldset. The group map appears only for a driver that has a group claim.

Settings tab#

The fieldset a driver does not name. How to reach the provider.

Field	Registry key	Type	Drivers
Client ID	`config.client_id`	`TextLine`, required	all but `email`
Client secret	`config.client_secret`	`Password`, required	all but `email`
Scope	`config.scope`	`Tuple`	all but `email`
Issuer	`config.issuer`	`TextLine`, required	`oidc-generic`, `plone-identity`
Token lifetime	`config.token_ttl`	`Int`, default `900`	`email`
Rate limit per hour	`config.rate_limit_per_hour`	`Int`, default `5`	`email`

Leave Scope empty to use the driver's own default. github has no Issuer, because it is not an OpenID Connect provider.

Accounts tab#

Who the provider's answer makes the person standing here.

Field	Registry key	Type	Default
User id source	`config.userid_source`	`Choice`	`uuid`
Let this provider create accounts	`config.create_user`	`Bool`	on
Attach to an existing account with the same verified email	`config.auto_link_by_email`	`Bool`	off
This provider's email verification counts	`config.trust_email_verification`	`Bool`	off, except `github` and `google`
This provider sends verification flags as text	`config.accept_string_booleans`	`Bool`	off

Shown for every driver except email.

See How to link accounts by email and How to control account creation.

Groups tab#

Field	Registry key	Type	Default
Groups arrive in the claim	`config.group_claim`	`TextLine`	`groups` for OIDC drivers, empty otherwise
Only these groups may sign in	`config.allowed_groups`	`Tuple`	empty
Let this provider set group membership	`config.sync_groups`	`Bool`	on

Shown only for oidc-generic and plone-identity, the two drivers whose settings schema is IOIDCSettings. github, google and email carry no groups this package can read, so none of them gets this tab.

See How to map provider groups.

Profile tab#

Field	Registry key	Type	Default
Fetch the picture over HTTP	`config.picture_over_http`	`Bool`	off

One field, and it still gets a tab rather than trailing after group settings it has nothing to do with.

Actions#

Test connection: Fetches the provider's discovery document, or validates the static configuration for drivers that have no discovery, and reports what it found. It clears the discovery cache first. It does not sign anybody in, so it says nothing about the client secret, the redirect URI, or the trust switches.
Delete: Removes the provider's configuration. It does not delete the identities linked through it—those are account data.

The client secret is write-only#

The control panel serializes a stored secret as a mask, never as its value.

To keep the stored secret, save the form with the mask unchanged.
To replace it, type the new one over the mask.

Warning

Do not clear the field to keep the existing secret. Blanking it sends an empty string, which is a different instruction, and it destroys the stored secret.