Skip to content

[People · Phase 1] Link records to accounts by email invite or manually #102

Description

@toto04

Goal

Link a People record to a login account in exactly two ways. Builds on #101; the roadmap is PoliNetworkOrg/admin#146.

  1. Email invite: the person links themselves.
  2. Manual link: someone with high clearance (people:link) links them.

We don't do automatic matching by email, name or Telegram, "Is this you?", review queues or merging. The account a person signs in with often isn't the one we know about: Entra ID if they're a socio, any Google account otherwise.

1. Email invite

  • Someone with people:write (or the Lead, for their team's members) sends an invite to the record's contact email.
  • The email contains a single-use token link. The token expires after 14 days, is stored hashed, and a new invite revokes the previous one.
  • Whoever opens the link signs in with any account, sees "Link this account to ?", and confirms.
  • Don't require the account's email to equal the contact email. Today acceptInvite refuses unless they match. The token is the proof.
  • Any signed-in account must be able to accept, including one without dashboard permissions. Today people.me.acceptInvite needs people:self, which a new person only gets once their roles are applied. Accepting needs its own policy: signed in + a valid token.
  • Refuse if the account is already linked to another record.
  • Update the invite email. The current Italian text tells people to sign in with the account that uses the invited address, which is no longer required.

2. Manual link

  • Someone with admin:access + people:link searches the IdP directory for an account and links it.

What linking does

  • Sets account_sub, then sends role commands for every pending assignment.
  • The actor in each command:
    • manual link: the person linking;
    • invite: each assignment's assigned_by. Auth refuses self-grants, so the invitee can't be the actor.
    • Send one command per actor, with IDs derived from the link, so retries are idempotent.
  • If Auth refuses an assignment (e.g. the assigner has lost clearance since), it stays on the record as refused, with Auth's reason, until someone with clearance assigns it again.
  • History records the method (invite or manual), who did it and which account.

Unlink

  • Needs admin:access + people:link.
  • Revokes the record's bound roles in Auth with a role command, then detaches the account. Its assignments go back to pending.
  • people.linking.recent lists links from the last 30 days, so a mistake (or a forwarded invite link, the main risk of not checking the email) is easy to spot and undo.

Done when

Activity

  1. added theissue type on Oct 29, 2026
  2. added
    peoplePeople: Group Admins, Capo Admins, Teams, Soci and census (see the People roadmap)
    on Oct 29, 2026
  3. added 2 commits that reference this issue on Oct 30, 2026
    7ba53b4
    cd05fb2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    peoplePeople: Group Admins, Capo Admins, Teams, Soci and census (see the People roadmap)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions