Skip to content

Feature 06: Admin User Invitation and Management

Version Date Author Change Description Approval Status
1.0 2025-09-04 Senior Business Analyst Initial Draft (Local User Creation) Superseded
2.0 2025-09-11 Senior Systems Analyst Complete rewrite for Google SSO; replaced direct creation with an invitation model. Pending Review

1.0 Introduction

1.1 Purpose

This document defines the business requirements for the administrative feature of inviting and pre-provisioning users. With the adoption of Google Directory for authentication (as described in Feature 01), administrators no longer create user accounts with passwords. Instead, this feature provides a mechanism for administrators to create a placeholder record for a new user by "inviting" them. This allows for the proactive assignment of specific roles and permissions before the user's first login, overriding the default Just-In-Time (JIT) provisioning rules detailed in ADR-0005.

2.0 Business Requirements

2.1 User Invitation

Authorized administrators must have an interface to invite new users to the application, which creates a pre-provisioned account record.

  • 2.1.1 Invitation Interface: From the "User Management" page, an administrator shall be able to access an "Invite User" form.
  • 2.1.2 Required Information: The form must require the administrator to provide the user's full corporate email address.
  • 2.1.3 Initial Configuration: The administrator must be able to assign one or more roles and/or add the user to one or more groups as part of the invitation process. This allows for tailored access from the moment the user first logs in.

2.2 Pre-provisioned State

When an administrator invites a user, the system creates a user record in a non-active, pre-provisioned state.

  • 2.2.1 "Invited" Status: Upon submission of the invitation form, a new user record is created in the database with a distinct status of Invited.
  • 2.2.2 Stored Configuration: The roles and groups selected by the administrator are saved and associated with this Invited user record.
  • 2.2.3 Behavior of "Invited" Accounts: A user account in the Invited state is a placeholder. It is not considered fully active and does not permit the user to log in until they complete the SSO flow.

2.3 Account Activation on First Login

The pre-provisioned record is activated and converted to a standard user account when the invited user completes their first SSO login.

  • 2.3.1 Activation Trigger: When a user successfully authenticates via Google SSO, the system checks if a user record with an Invited status exists for that email address.
  • 2.3.2 Applying Pre-configured Permissions: If an Invited record is found, the system applies the pre-configured roles and groups from that record to the user. This overrides the default permission set that would normally be assigned during JIT provisioning.
  • 2.3.3 Status Transition: Upon successful activation, the user's status is changed from Invited to Active.

3.0 Business Rules

  • Rule 6.1: An administrator must possess the admin:user:invite permission to access the "Invite User" functionality.
  • Rule 6.2: The email address provided in the invitation form must be validated to ensure it belongs to the authorized corporate domain (e.g., @our-company.com).
  • Rule 6.3: The system must prevent an administrator from inviting an email address that already exists in the system with an Active or Invited status. A clear error message must be shown.
  • Rule 6.4: The "invitation" is a purely internal, pre-provisioning process. The system is not required to send a notification email to the invited user. Communication with the new user is handled outside of the application.

4.0 Scope

4.1 In Scope

  • Administrative UI for inviting a user by email.
  • Pre-assigning roles and groups to an invited user.
  • Backend logic to create and manage the Invited user state.
  • Logic to apply pre-configured permissions upon the user's first SSO login.

4.2 Out of Scope

  • The Google SSO authentication flow itself (covered in Feature 01).
  • Sending notification or invitation emails to users.
  • Batch import or synchronization of users from Google Directory.

5.0 Assumptions and Dependencies

  • 5.1: The administrator performing the invitation is authenticated and has the necessary permissions.
  • 5.2: The backend provides a list of all available roles and groups that can be assigned during the invitation.
  • 5.3: The Just-In-Time provisioning flow (Feature 01) is capable of checking for pre-provisioned accounts.