splent_feature_identities

The identities feature of a SPLENT product line.

The accounts on sign-in providers (ORCID, GitHub...) that people link to their account. It keeps one row per linked provider account, lists them at /account/identities, lets the owner disconnect one, and holds the product's one OAuth registry, which every provider feature registers its client on. It shows nothing on its own. A provider feature (orcid, github) brings the buttons and the rows. It needs auth, which owns the accounts, and profile, whose edit page is where the linked accounts are managed.

A SPLENT feature is a Python package that a product composes with others. Its models, routes, services, templates and hooks are registered when the product starts. What this feature provides and requires is listed in the [tool.splent.contract] section of pyproject.toml, which splent feature:contract --write keeps in sync with the source.

The rules every provider follows

IdentitiesService holds them, so ORCID and GitHub behave the same way.

After a disconnect it sends identity-disconnected with user, provider and provider_id, so the provider feature drops what it keeps of its own.

Closed products

A product that does not install splent_feature_signup, the optional feature that opens registration, is closed, and an administrator opens its accounts. A provider must not be a way around that. Before it creates an account it asks registration_is_open(), which is true only when signup's blueprint is registered, and in a closed product it refuses with closed_registration_message(provider) instead.

The message names no account and no address, so in a closed product the refusal tells a stranger nothing about who has an account. It is translated, and it reads "New accounts are opened by an administrator, so signing in with ORCID cannot create one. Ask an administrator for access. If you already have an account, sign in as usual and connect ORCID from your profile."

from splent_io.splent_feature_identities.services import IdentitiesService

identities = IdentitiesService()
if not identities.registration_is_open():
    return None, identities.closed_registration_message("MyProvider")

Settings

An account opened through a provider has no password its owner knows, so a wrong password is the expected outcome there. With the hint on, auth's "Invalid credentials" is followed by "This account signs in with ORCID. Continue with it below." It is off by default because it tells whoever types an address that an account exists for it and how it signs in. A product whose accounts are public anyway (a repository that lists its authors) turns it on.

[tool.splent.config]
EXTERNAL_LOGIN_PASSWORD_HINT = true

Only a wrong email or password gets the hint. auth renders its auth.login.error_hint slot for that case alone, never for a throttled attempt or an account that is not active yet.

Adding a provider

A provider feature registers its OAuth client on the shared registry and draws itself in the slots auth, signup and profile open. Each callback takes no arguments and returns HTML, or an empty string to add nothing.

# services.py of a provider feature
from splent_io.splent_feature_identities.oauth import oauth_for


def register_myprovider_client(app):
    oauth_for(app).register(name="myprovider", client_id=..., client_secret=...)

# hooks.py of the same feature
from splent_framework.hooks.template_hooks import register_template_hook

register_template_hook("auth.login.providers", sign_in_button, order=30)
register_template_hook("signup.providers", sign_in_button, order=30)
register_template_hook("profile.edit.sections", linked_account_row, order=30)

The disconnect button of a row opens this feature's modal, which is drawn once on the edit-profile page and posts to /account/disconnect/<provider>/<provider_id>.

<button type="button" data-bs-toggle="modal" data-bs-target="#disconnectModal"
        data-provider="myprovider" data-provider-id="{{ identity.provider_id }}">

GitHub takes order 10 and ORCID 20 in all three slots.

Translations

The login hint and the closed registration message ship with a Spanish catalog.

Use it in a product

splent feature:add splent_feature_identities

Develop

splent feature:test splent_feature_identities
splent feature:contract splent_feature_identities

Release

splent feature:release splent_feature_identities --dry-run --bump patch
splent feature:release splent_feature_identities

The first command rehearses the release and changes nothing. The second publishes it to the git forge and to PyPI, and a PyPI version is permanent.