How to install the backend

How to install the backend#

Install pas.plugins.identity in a Plone site and confirm it works.

This guide covers the backend only. The frontend is a separate package and a separate guide: How to install the frontend.

Note

There are no GenericSetup upgrade steps in this release. See How to upgrade before taking a new alpha, and Stability for what that implies.

Requirements#

Plone

6.2

Python

3.12, 3.13, or 3.14

Frontend

Volto, for sign-in. Classic UI is not supported yet—see Stability

Install the backend#

These steps are for a project generated by cookieplone, which is the layout a Plone 6 project has. Paths are relative to backend/, and <yourpackage> is the package under src/.

  1. Declare the dependency in pyproject.toml:

    dependencies = [
    "Products.CMFPlone",
    "plone.api",
    "plone.restapi",
    "plone.volto",
    "pas.plugins.identity",
]

    Two extras exist, and neither is needed for ordinary sign-in:

    Extra

    Adds

    Also needs

    server

    The authorization server layer, with a GenericSetup profile of its own.

    its profile, in step 3

    sql

    An audit sink writing a row per event to a relational database.

    IDENTITY_AUDIT_DSN, and sql named in audit_sinks

    Ask for one by naming it in the requirement, "pas.plugins.identity[server]". See The audit log for the sql sink.

  2. Load its ZCML, in src/<yourpackage>/dependencies.zcml:

    <configure xmlns="http://namespaces.zope.org/zope">

  <include package="pas.plugins.identity" />

</configure>

    Your package's configure.zcml already pulls that file in with <include file="dependencies.zcml" />. Installing the distribution is not enough on its own: without the include, nothing registers and the add-on does not appear in the control panel.

  3. Install it with your own package, in src/<yourpackage>/profiles/default/metadata.xml:

    <?xml version="1.0" encoding="utf-8"?>
<metadata>
  <version>1000</version>
  <dependencies>
    <dependency>profile-pas.plugins.identity:default</dependency>
  </dependencies>
</metadata>

    Naming it here is what makes a fresh site arrive configured, rather than waiting for somebody to remember the add-ons control panel.

    For the authorization server, name both profiles, in this order:

    <dependencies>
  <dependency>profile-pas.plugins.identity:default</dependency>
  <dependency>profile-pas.plugins.identity.server:default</dependency>
</dependencies>

    pas.plugins.identity:default installs everything the core layer needs: the control panel, both PAS plugins, the UserProfile and UserGroup content types with their workflows, and the catalog they are filed in. It also sets the registry records described in Users and groups as content and points them at this package's own types.

  4. Ship your settings as configuration, in src/<yourpackage>/profiles/default/registry/pas.plugins.identity.xml:

    <?xml version="1.0" encoding="utf-8"?>
<registry>
  <records interface="pas.plugins.identity.core.controlpanel.interfaces.IIdentitySettings"
           prefix="pas.plugins.identity"
  >
    <value key="callback_url">/login-identity</value>
    <value key="audit_record_pii">False</value>
  </records>
</registry>

    Every record in Settings can be set this way, so a deployment's configuration lives in the repository and arrives with the profile instead of being typed into a control panel on each environment.

    Provider secrets are the exception. They are write-only and a GenericSetup export omits them, so keep them out of these files and set them per environment. See About secrets.

  5. Restart the Plone instance, then apply your own package's profile.

    This is a ZCML change, so the site does not see the add-on until it restarts.

Note

To install into a site that already exists, without touching your package, use the add-ons control panel or apply pas.plugins.identity:default from portal_setup. The server layer is its own entry there, with its own install and uninstall button; the panel shows no version beside it, because the entry is named after a package rather than a distribution.

Set the login callback URL#

Nothing signs in until this matches what your providers have registered.

  1. Open the Identity providers control panel.

  2. Set Callback URL to the frontend route that providers redirect back to.

    The default is /login-identity, which is the route the Volto add-on registers. Most sites never change it.

The value is a path, and the full redirect URI you give a provider is your frontend's base URL plus that path:

https://www.example.com/login-identity

It is a route in the Volto frontend rather than a backend view, so the package cannot derive it from the portal URL. That is why it is a setting.

Verify#

A working install has all four of these:

  • the identity plugin in acl_users, active for extraction, authentication, and credentials reset

  • the identity_profile plugin beside it, at the top of IPropertiesPlugin

  • at least one provider in the control panel, with a title and a driver

  • a callback URL that matches what the provider has registered

Uninstalling#

Every profile has a matching uninstall profile, and uninstalling is tested: the test installs, uninstalls, and asserts that the site still works with no plugin, registry key, or tool left behind.

Note

Uninstalling removes the catalog, the content types, and the workflows. It leaves every UserProfile object and its data exactly where it is. Uninstalling an add-on is a configuration change, not an instruction to delete everyone's account data.

Next steps#

  1. How to install the frontend—the Volto add-on, without which nobody can sign in.

  2. Provider recipes—pick the provider you are adding and follow its recipe.

  3. How to troubleshoot sign-in—if sign-in fails, start here rather than in the source.

Contents