Settings

Settings#

Every registry record the package reads.

All keys are under the pas.plugins.identity. prefix. Configuration lives in the registry, one record per setting, so a GenericSetup export describes a site field by field and one setting can be changed without rewriting the rest.

Site-wide#

Set by the pas.plugins.identity:default profile. Edited in the Identity providers control panel.

Key	Type	Default	What it does
`callback_url`	`TextLine`	`/login-identity`	The frontend route providers redirect back to. Matches the route the Volto add-on registers.
`user_content_type`	`TextLine`	`''`	Content type used for user profiles.
`user_container_path`	`TextLine`	`''`	Where profiles are filed.
`group_content_type`	`TextLine`	`''`	Content type used for groups.
`group_container_path`	`TextLine`	`''`	Where groups are filed.
`sync_portraits`	`Bool`	`False`	Fetch a portrait from the provider at sign-in.
`portrait_timeout`	`Int`	`5`	Seconds to wait for one.
`portrait_max_bytes`	`Int`	`2097152`	Refuse a portrait larger than this.
`discovery_timeout`	`Int`	`10`	Seconds to wait for a discovery document.
`audit_max_entries`	`Int`	`500`	Entries the built-in log keeps.
`audit_max_days`	`Int`	`180`	Days the built-in log keeps.
`audit_record_pii`	`Bool`	`False`	Record personally identifying detail in audit entries.
`audit_sinks`	`Tuple`	`('plugin',)`	Which audit sinks to write to, in order. See The audit log.

The four content-type and container records are empty by default and filled in by the install profile, which points them at this package's own types. See Users and groups as content.

user_container_path and group_container_path are derived from the container records in the next section and kept in step with them. Set the container records; do not set these two by hand.

Profiles and groups#

Where principals are filed, which of their workflow states count, and what a profile must carry before its owner is let past the gate.

Where principals are filed#

Key	Type	Default	What it does
`profile_container_parent`	`TextLine`	`''`	Path of the folder the profile container lives in, relative to the site root. Empty means the site root.
`profile_container_id`	`TextLine`	`identity-profiles`	Id of the folder holding user profiles.
`profile_container_title`	`TextLine`	`Identity Profiles`	Title used when this package creates the folder. Changing it later does not rename an existing one.
`profile_container_type`	`TextLine`	`Folder`	Portal type used when this package creates the folder.
`group_container_parent`	`TextLine`	`''`	Same, for groups. Read only when `group_container_id` is set.
`group_container_id`	`TextLine`	`''`	Id of the folder holding groups. Empty means groups are filed with the profiles.
`group_container_title`	`TextLine`	`Groups`	Title used when this package creates the group folder.
`group_container_type`	`TextLine`	`Folder`	Portal type used when this package creates the group folder.

The group records default to the profile container's, so a site that files principals together sets none of them.

Which states count#

Key	Type	Default	What it does
`profile_enumeration_states`	`Tuple`	`('incomplete', 'complete')`	Profile workflow states visible to user enumeration and to the properties plugin.
`group_enumeration_states`	`Tuple`	`('active',)`	Group workflow states visible to group enumeration and granting membership.

The profile gate#

Key	Type	Default	What it does
`enforce_required_profile_fields`	`Bool`	`True`	Redirect a user to their own edit form while their profile is incomplete.
`required_profile_fields`	`Tuple`	`()`	Fields a profile must carry to count as complete. Empty means the fields the type itself marks required.
`gate_exempt_paths`	`Tuple`	`()`	Extra view names the gate never redirects, matched on the last path segment.

See Profiles and groups for what each state means and which routes are exempt already.

Server layer#

Present only where pas.plugins.identity.server:default has been applied.

Key	Type	Default	What it does
`server_issuer`	`TextLine`	`''`	The URL identifying this authorization server. Never derived from the portal URL.
`server_consent_url`	`TextLine`	`''`	Where the browser is sent to approve a request.
`server_access_token_ttl`	`Int`	`900`	Access token lifetime, in seconds.
`server_refresh_token_ttl`	`Int`	`1209600`	Refresh token lifetime, in seconds—14 days.
`server_clients`	`Text`	`''`	The client registry. Managed through `@identity-clients`, not by hand.
`server_signing_keys`	`Text`	`''`	The signing key ring. Managed through `@identity-keys`, not by hand.

Only the two lifetimes are written by the install profile. server_clients and server_issuer are deliberately left out, because an empty <value> imports as None while omitting the key takes the empty string the schema field declares. A site with no clients and no issuer is the correct initial state: the server signs nothing until it is told what it is called.

Set server_issuer yourself. See About federation for why it is configured rather than derived.

The two defaults are chosen, not arbitrary:

900 seconds for an access token. There is no denylist, so this doubles as the worst case between revoking a client and the last token minted for it expiring.
14 days for a refresh token. They rotate on every use, so this is how long a client may stay away before a person has to sign in again—long enough that a daily integration never sees a login page, short enough that an abandoned one stops working inside a sprint.

Per provider#

Pattern:

pas.plugins.identity.providers.<provider_id>.<field>

<field> is a field of that provider's driver settings schema. Which fields exist, and what type each one is, comes from the driver at runtime.

Provider records belong to no interface—each carries its own field type. That is why a GenericSetup profile writing them needs a field element per record unless it names an interface that declares them.

Fields every provider has#

Key	Type	Default	What it does
`driver`	`TextLine`	`''`	Which driver this provider uses.
`title`	`TextLine`	`''`	What the login button says.
`enabled`	`Bool`	`True`	Whether the provider works at all.
`show_in_login`	`Bool`	`True`	Whether the login page offers a button for it.
`icon`	`Bytes`	`None`	An SVG document, sanitized on save.
`background_color`	`TextLine`	`''`	Button background, such as `#24292f`.
`foreground_color`	`TextLine`	`''`	Button text colour.
`order`	`Int`	`0`	Position among the buttons.
`propertymap`	`Dict`	`{}`	Claim path → Plone property.
`groupmap`	`Dict`	`{}`	Provider group name → local group id.

Both default to True, so a provider added through the API without saying otherwise is enabled and shown.

enabled and show_in_login are different questions. An enabled provider that is not shown still signs people in and is still linkable from a user's own sign-in methods page; it has no button.

Fields from the driver#

Under pas.plugins.identity.providers.<id>.config.<field>.

Every OAuth2 driver—`IOAuth2Settings`#

Field	Type	Required	Default	Tab
`client_id`	`TextLine`	yes	—	Settings
`client_secret`	`Password`	yes	—	Settings
`scope`	`Tuple`	no	`()`	Settings
`userid_source`	`Choice`	no	`'uuid'`	Accounts
`create_user`	`Bool`	no	`True`	Accounts
`auto_link_by_email`	`Bool`	no	`False`	Accounts
`trust_email_verification`	`Bool`	no	`False`	Accounts
`accept_string_booleans`	`Bool`	no	`False`	Accounts

An empty scope means the driver's own default is used. See Shipped drivers.

OpenID Connect drivers add—`IOIDCSettings`#

Field	Type	Required	Default	Tab
`issuer`	`TextLine`	yes	—	Settings
`group_claim`	`TextLine`	no	`''`	Groups
`allowed_groups`	`Tuple`	no	`()`	Groups
`sync_groups`	`Bool`	no	`True`	Groups
`picture_over_http`	`Bool`	no	`False`	Profile

Applies to oidc-generic and plone-identity.

The magic-link driver—`IEmailSettings`#

Field	Type	Required	Default	Tab
`token_ttl`	`Int`	no	`900`	Settings
`rate_limit_per_hour`	`Int`	no	`5`	Settings

token_ttl is a ceiling below 15 minutes, not above it: a larger value does not extend the token's life past 15 minutes.

GitHub—`IGitHubSettings`#

Inherits IOAuth2Settings and adds no fields. There is no issuer: GitHub is not an OpenID Connect provider and the endpoints are built into the driver.

Secrets are not exported#

A GenericSetup export omits client secrets, so an export of your provider configuration is not enough to rebuild a working site. Secrets travel separately.

See About secrets.