[S04] Invite User

Summary

The platform screen that gives a new person access to the Admin Portal. A wizard collects who the person is and what they may do, creates their sign-in account in Entra External ID when they do not have one yet, prepares their EMS user record, and sends them an onboarding email. The access itself is granted when the person accepts the invitation on the C12 welcome page, not when the invitation is sent.

The same wizard serves a person who already has an Entra account, whether from another EMS application or an earlier invitation. For them the Entra step is skipped and only the EMS side is prepared.

Actor & Context

Actor: platform administrator — a session carrying the super-admin grant (ROLE_SUPER_ADMIN).
Frequency: occasional; a handful of invitations a month.
Precondition: the session’s active organisation is the organisation that owns this Admin Portal instance (Myriad Events), and the session carries the super-admin grant.
Entry point: sidebar PLATFORM ▸ Users, then Invite user. The menu entry is shown only when both preconditions hold.

Why the invitee’s user record sits in the owning organisation

The Admin Portal signs every user in through one registration system, which belongs to the organisation that owns the portal instance. At sign-in, admin-service looks up the user record (OrgUser) by that organisation and the person’s Entra object id (oid). A user record created under any other organisation would not be found, and sign-in would create a second, empty one.

So the invitee’s OrgUser is always created in the owning organisation. Access to the organisation they will actually work in is granted through a linked-organisation grant (LinkedOrg, the data dimension) and an organisation role (OrgPermission, the capability dimension) on that organisation. See OIDC ⇄ admin-service JWT Token Exchange.

The owning organisation delegates; it does not grant itself. An invitee normally holds no role in the owning organisation, and the wizard defaults to none.

Main Flow

  1. The administrator opens Invite user. The wizard has four steps: Person, Owning organisation, Organisation access, Review.

  2. Person. The administrator enters an email address. The wizard looks it up in two places and shows what it found:

    • Entra External ID — whether a user with this email already exists in the tenant.

    • EMS — whether a person with this email already exists, and whether that person already has an Admin Portal user record and grants.

  3. The administrator confirms or enters the first name and last name. Where an EMS person matches, the wizard proposes linking to it instead of creating a new person.

  4. Owning organisation. The administrator chooses the invitee’s role in the owning organisation. The default is None.

  5. Organisation access. The administrator chooses one organisation, the data access level for it (Read or Read/write), and the role in it.

  6. Review. The wizard summarises what will happen: whether an Entra invitation will be sent, which person record will be used or created, and the grants that will apply on acceptance. The administrator sends the invitation.

  7. The system:

    1. sends the Entra invitation when the person has no Entra account, with the redirect URL set to this portal’s welcome page for this invitation, and reads the new oid from the response;

    2. creates or reuses the person and the OrgUser in the owning organisation, keyed on the oid;

    3. records the invitation, holding the requested grants;

    4. sends the EMS onboarding email (see Onboarding email).

  8. The wizard closes on a confirmation that says which emails the person should expect. The invitation appears in the list as Pending.

Onboarding email

admin-service sends one onboarding email for every invitation, whether or not Entra sent one:

  • New Entra account — says that a separate email from Microsoft will arrive to set up sign-in, and that the link in it leads to the welcome page.

  • Existing Entra account — says that the person can sign in with the account they already use, and links to the welcome page directly.

Both variants carry the welcome-page link for this invitation, the organisation and role being offered, who sent the invitation, and links to welcome and training material for this application.

Alternative Flows

  • AF-1 — Already has an Entra account. The Entra invitation is skipped and the existing oid is used. Everything else is unchanged.

  • AF-2 — Already an Admin Portal user. The person already has an OrgUser in the owning organisation. It is reused, and the invitation adds access to one more organisation. If the person already has access to the chosen organisation, the wizard says so and does not create a second invitation; changing an existing role is out of scope.

  • AF-3 — Several EMS people share the email. The wizard lists them with enough detail to tell them apart, and the administrator picks one or chooses Create a new person.

  • AF-4 — Entra call fails. Nothing is created on the EMS side and the wizard shows the error. Because the Entra step runs first, a retry is safe: if the earlier attempt did create the Entra user, the retry finds it through AF-1.

  • AF-5 — Onboarding email fails. The invitation still stands. It is listed as Pending — email not sent, and the administrator can resend it.

  • AF-6 — Revoke. The administrator revokes a pending invitation from the list. It can no longer be accepted, and no grant is created. The Entra account, if one was created, is left in place.

  • AF-7 — Wrong context. With any other organisation active, or without the super-admin grant, the menu entry is hidden and the API refuses the request.

Invitations list — /platform/users

A table of invitations, newest first: invitee, organisation, role, invited by, sent, status (Pending, Accepted, Revoked, Expired) and whether an Entra invitation was sent. Row actions: Resend email and Revoke, for pending invitations only.

Acceptance Criteria

  • The menu entry and every invitation endpoint require ROLE_SUPER_ADMIN with the owning organisation active. Other callers get a 403 response.

  • An email with no Entra account produces an Entra invitation whose redirect URL is this portal’s welcome page for the new invitation, and the OrgUser carries the oid that Entra returned.

  • An email with an existing Entra account produces no Entra invitation, and the OrgUser carries the existing oid.

  • The OrgUser is created in the owning organisation, never in the target organisation.

  • An existing OrgUser in the owning organisation is reused, not duplicated.

  • An existing EMS person with the email is offered for linking, and a new person is created only when the administrator chooses it.

  • Sending an invitation creates no LinkedOrg and no OrgPermission. Until acceptance, the invitee’s token carries ROLE_USER only.

  • The onboarding email is sent for every invitation, in the variant matching whether an Entra invitation was sent.

  • A failed Entra call leaves no EMS records, and a retry succeeds.

  • A revoked invitation cannot be accepted.

  • The invitation records who sent it and when.

API Surface

Planned shapes — not yet implemented.

Call Purpose

GET /api/invitations/lookup?email=

Entra and EMS matches for an email: Entra oid if any, matching people, existing OrgUser and grants

POST /api/invitations

Send an invitation: email, names, person to link (optional), owning-organisation role (optional), target organisation, access level, target role

GET /api/invitations

The invitations list

POST /api/invitations/{id}/resend

Resend the onboarding email

DELETE /api/invitations/{id}

Revoke a pending invitation

Out of Scope

  • Changing or removing an existing user’s roles or organisation access.

  • Invitations started by a tenant administrator from their own organisation. That is T01 AF-1, and waits for a user-management role in the security review.

  • Access to more than one target organisation in one invitation. A second invitation reuses the account (AF-2).

  • Other Entra tenants or identity providers. registration-portal still signs in through a separate Azure AD B2C tenant, so "already has an Entra account" means the External ID tenant only.

  • A per-application column on OrgPermission. This is deferred to the multi-provider identity discussion.

Design Anchors

Notes

  • The ALL TENANTS marker is not needed: the screen acts on the owning organisation’s users, and the target organisation is named explicitly in every step.

  • How Entra External ID treats an invited user (a guest account or a local account, and which sign-in methods follow) is to be confirmed by a spike before the wizard’s copy is final.

  • Invitation expiry: proposed 30 days, to be confirmed.