UC-015: Application User Provisioning

Version: 1.0.0
Status: Draft
Last Updated: 2025-01-13

Overview

Application Users (ApplicationUser) are permanent, non-expiring users who are manually provisioned by AdminUsers to access registered applications. Unlike TrialUsers who self-register with time-limited access, ApplicationUsers are created administratively with role-based access control (RBAC), password authentication, and no expiration date.

This use case focuses on the MVP scope: manual creation by AdminUsers with email-based credential delivery. Future enhancements will include synchronization with Identity Management (IdM) systems like Active Directory.

Actors

  • AdminUser: Platform administrator who creates and manages ApplicationUsers
  • ApplicationUser: The newly provisioned user who will access registered applications

Preconditions

  • AdminUser must be authenticated with Application Manager
  • AdminUser must have CreateUser permission
  • Target email address must be available (not already in use by another ApplicationUser)
  • At least one registered application exists in the system (optional for MVP)
  • At least one role is defined for assignment (optional for MVP)

Postconditions

Success:

  • New ApplicationUser entity created in database
  • User inherits from User base class with all common properties
  • Initial password generated and securely hashed (BCrypt)
  • User flagged with MustChangePassword = true
  • Welcome email sent with username and temporary password
  • User assigned to specified roles (if provided)
  • User granted access to specified applications (if provided)
  • Audit log entry created

Failure:

  • No user created
  • Error message displayed to AdminUser
  • No email sent

Data Requirements

ApplicationUser Entity (extends User)

Inherits all base User properties:

  • Id (Guid)
  • Email (string, 255)
  • FullName (string, 200)
  • TenantId (Guid, nullable)
  • IsActive (bool)
  • IsAdmin (bool)
  • CreatedAt (DateTimeOffset)
  • UpdatedAt (DateTimeOffset)
  • LastLoginAt (DateTimeOffset, nullable)

ApplicationUser-Specific Properties:

Property Type Constraints Description
Username string(100) Required, Unique Authentication identifier
AuthMethod enum Required Password or SSO (MVP uses Password)
PasswordHash string(255) Nullable BCrypt hash (set for Password auth)
MustChangePassword bool Required Force password change on first login
PasswordChangedAt DateTimeOffset Nullable Last password change timestamp
PasswordExpiresAt DateTimeOffset Nullable Password expiration date (policy-based)
PasswordChangeCount int Required Total password changes
FailedLoginAttempts int Required Consecutive failed login counter
LockedOutUntil DateTimeOffset Nullable Account lockout expiration
ExternalUserId string(255) Nullable SSO provider user ID (future)
IdentityProvider string(100) Nullable SSO provider name (future)

Navigation Properties:

  • ApplicationAccess: Collection of ApplicationAccess (apps user can access)
  • UserRoles: Collection of UserRole (assigned RBAC roles)
  • PasswordHistory: Collection of PasswordHistory (password reuse prevention)
  • Sessions: Collection of Session (active login sessions)

Authentication Methods:

public enum ApplicationUserAuthMethod
{
    Password = 1,  // Username/password with BCrypt
    SSO = 2        // External IdP (Azure Entra, etc.)
}

Main Flow

Step 1: AdminUser Initiates User Creation

  1. AdminUser navigates to User Management interface
  2. AdminUser selects "Create Application User"
  3. System displays provisioning form

Step 2: AdminUser Provides User Details

AdminUser enters required information:

  • Email Address (required, validated format, uniqueness check)
  • Full Name (required, 1-200 characters)
  • Username (required, unique, 3-100 characters, alphanumeric + underscore/hyphen)
  • Authentication Method (MVP: Password only)
  • Roles (optional, multi-select from available roles)
  • Application Access (optional, multi-select from registered applications)
  • Tenant Assignment (optional, for multi-tenant deployments)
  • Send Welcome Email (checkbox, default: true)

Step 3: System Validates Input

Validation checks:

  • Email format and uniqueness across all ApplicationUsers
  • Username format (alphanumeric, underscore, hyphen) and uniqueness
  • Full name not empty
  • At least one role selected (warning if none)
  • At least one application selected (warning if none)

If validation fails:

  • Display specific error messages
  • Highlight invalid fields
  • Allow AdminUser to correct and resubmit

Step 4: System Generates Initial Password

  1. Generate cryptographically secure random password:
    • Length: 16 characters
    • Character set: uppercase, lowercase, digits, special characters (!@#$%^&*)
    • Ensure at least one character from each set
  2. Hash password using BCrypt (work factor: 12)
  3. Store PasswordHash in database
  4. Set MustChangePassword = true

Step 5: System Creates ApplicationUser

Transaction begins:

  1. Create User Entity:

    var applicationUser = new ApplicationUser
{
    Id = Guid.NewGuid(),
    Email = input.Email,
    FullName = input.FullName,
    Username = input.Username,
    AuthMethod = ApplicationUserAuthMethod.Password,
    PasswordHash = bcryptHash,
    MustChangePassword = true,
    PasswordChangedAt = DateTimeOffset.UtcNow,
    PasswordChangeCount = 1,
    FailedLoginAttempts = 0,
    IsActive = true,
    IsAdmin = false,
    TenantId = input.TenantId,
    CreatedAt = DateTimeOffset.UtcNow,
    UpdatedAt = DateTimeOffset.UtcNow
};

  2. Assign Roles:

    foreach (var roleId in input.RoleIds)
{
    applicationUser.UserRoles.Add(new UserRole
    {
        UserId = applicationUser.Id,
        RoleId = roleId,
        AssignedAt = DateTimeOffset.UtcNow,
        AssignedBy = adminUserId
    });
}

  3. Grant Application Access:

    foreach (var appId in input.ApplicationIds)
{
    applicationUser.ApplicationAccess.Add(new ApplicationAccess
    {
        UserId = applicationUser.Id,
        ApplicationId = appId,
        GrantedAt = DateTimeOffset.UtcNow,
        GrantedBy = adminUserId
    });
}

  4. Create Audit Log Entry:

    auditLog.Log(new AuditEntry
{
    Action = "ApplicationUser.Created",
    ActorId = adminUserId,
    ActorType = "AdminUser",
    TargetId = applicationUser.Id,
    TargetType = "ApplicationUser",
    Timestamp = DateTimeOffset.UtcNow,
    Details = new {
        Username = applicationUser.Username,
        Email = applicationUser.Email,
        RoleIds = input.RoleIds,
        ApplicationIds = input.ApplicationIds
    }
});

Transaction commits or rolls back on failure.

Step 6: System Sends Welcome Email

If "Send Welcome Email" is enabled:

Email Template:

Subject: Your Application Manager Account

Hello {{FullName}},

Your account has been created for Application Manager.

**Login Credentials:**
- Username: {{Username}}
- Temporary Password: {{TemporaryPassword}}
- Login URL: {{ApplicationManagerURL}}/login

**Important Security Information:**
- You will be required to change your password on first login
- Your temporary password will expire in 24 hours
- After 5 failed login attempts, your account will be locked for 15 minutes

**Next Steps:**
1. Click the login URL above
2. Enter your username and temporary password
3. Create a new secure password

If you did not request this account or believe you received this email in error, 
please contact your administrator immediately.

Best regards,
Application Manager System

Email Details:

  • From: noreply@application-manager.domain
  • To: {{Email}}
  • Reply-To: Administrator contact email
  • Content-Type: HTML with plaintext fallback
  • Security: Temporary password in plaintext (user must change on first login)

Step 7: System Displays Confirmation

Success message shown to AdminUser:

✓ Application User created successfully

Username: johndoe
Email: john.doe@company.com
Status: Active (Password change required)
Roles: Developer, API Viewer
Applications: Finance API, HR Portal
Welcome email sent: Yes

Provide options:

  • Create Another User (return to Step 2)
  • View User Details (navigate to user profile)
  • Back to User List (return to management interface)

Alternative Flows

Alt-1: Email Address Already Exists

Trigger: Step 3 validation detects duplicate email

Flow:

  1. System queries database for existing ApplicationUser with same email
  2. Display error: "Email address already in use by another ApplicationUser"
  3. Suggest using "Find User" to locate existing account
  4. Allow AdminUser to modify email and retry

Alt-2: Username Already Exists

Trigger: Step 3 validation detects duplicate username

Flow:

  1. System queries database for existing ApplicationUser with same username
  2. Display error: "Username already taken"
  3. Suggest alternative usernames (e.g., johndoe2, john.doe)
  4. Allow AdminUser to modify username and retry

Alt-3: Skip Welcome Email

Trigger: AdminUser unchecks "Send Welcome Email" in Step 2

Flow:

  1. System creates ApplicationUser normally (Steps 3-5)
  2. Skip Step 6 (email sending)
  3. Display confirmation with warning: 
    ✓ Application User created successfully

⚠️ Welcome email was NOT sent

Temporary Password: Abc123!@#XyzDef

You must manually provide the username and password to the user.
This password will not be displayed again.
  4. Provide "Copy Credentials" button to copy username/password to clipboard

Alt-4: No Roles Assigned

Trigger: AdminUser leaves role selection empty in Step 2

Flow:

  1. System displays warning: "User will have no role assignments. They will not be able to perform any actions until roles are assigned."
  2. Prompt AdminUser to confirm: "Create user without roles?"
  3. If confirmed: Create user with empty UserRoles collection
  4. If canceled: Return to Step 2

Alt-5: No Application Access Granted

Trigger: AdminUser leaves application selection empty in Step 2

Flow:

  1. System displays warning: "User will not have access to any applications until explicitly granted."
  2. Prompt AdminUser to confirm: "Create user without application access?"
  3. If confirmed: Create user with empty ApplicationAccess collection
  4. If canceled: Return to Step 2

Alt-6: Email Delivery Fails

Trigger: SMTP error or email service unavailable during Step 6

Flow:

  1. ApplicationUser creation succeeds (transaction committed)
  2. Email sending fails (logged as warning)
  3. Display partial success message: 
    ✓ Application User created successfully

⚠️ Welcome email failed to send

Error: SMTP connection timeout
Temporary Password: Abc123!@#XyzDef

Please manually provide credentials to the user or use "Resend Welcome Email" option.
  4. Store temporary password in secure session storage for 5 minutes
  5. Provide "Resend Email" button

Exception Flows

Exc-1: Database Transaction Failure

Trigger: Database constraint violation or deadlock during Step 5

Flow:

  1. Transaction automatically rolls back
  2. No ApplicationUser created
  3. No email sent
  4. Display error: "Failed to create user due to database error. Please try again."
  5. Log technical details for troubleshooting
  6. Return to Step 2 with form data preserved

Exc-2: Invalid Role ID

Trigger: Selected role no longer exists during Step 5

Flow:

  1. System detects role ID not found in database
  2. Transaction rolls back
  3. Display error: "Selected role 'Developer' no longer exists. Please refresh and select valid roles."
  4. Return to Step 2

Exc-3: Invalid Application ID

Trigger: Selected application no longer exists during Step 5

Flow:

  1. System detects application ID not found in database
  2. Transaction rolls back
  3. Display error: "Selected application 'Finance API' no longer exists. Please refresh and select valid applications."
  4. Return to Step 2

Exc-4: Permission Denied

Trigger: AdminUser lacks CreateUser permission

Flow:

  1. System checks permissions before displaying form
  2. Display error: "You do not have permission to create application users. Contact your system administrator."
  3. Return to previous page

Business Rules

BR-1: Password Policy

  • Length: Minimum 12 characters (generated passwords use 16)
  • Complexity: Must contain uppercase, lowercase, digits, special characters
  • History: Cannot reuse last 5 passwords (enforced on password change)
  • Expiration: Optional policy-based expiration (configurable, default: disabled for MVP)
  • Lockout: 5 failed attempts = 15-minute lockout

BR-2: Username Requirements

  • Format: 3-100 characters, alphanumeric + underscore/hyphen
  • Uniqueness: Must be unique across all ApplicationUsers
  • Case Sensitivity: Case-insensitive for authentication (stored as provided)
  • Reserved Names: Cannot use system reserved names: admin, root, system, test

BR-3: Email Requirements

  • Format: RFC 5322 compliant
  • Uniqueness: Must be unique across all ApplicationUsers
  • Verification: No email verification required (admin-provisioned)
  • Changes: Email changes require AdminUser approval (future enhancement)

BR-4: Role Assignment

  • Minimum: Warning if no roles assigned (allowed but discouraged)
  • Default Roles: No default roles applied automatically
  • Role Conflicts: Multiple roles allowed (permissions are additive)
  • Assignment Audit: All role assignments logged with timestamp and assigning AdminUser

BR-5: Application Access

  • Minimum: Warning if no application access granted (allowed but discouraged)
  • Default Access: No default application access
  • Inheritance: No role-based application access inheritance (future enhancement)
  • Grant Audit: All access grants logged with timestamp and granting AdminUser

BR-6: Multi-Tenancy

  • Tenant Assignment: Optional for MVP (defaults to null = global user)
  • Tenant Isolation: If TenantId is set, user can only access applications within same tenant
  • Cross-Tenant Access: Not supported in MVP
  • Tenant Validation: If provided, TenantId must reference existing tenant

BR-7: User Lifecycle

  • Creation: Only by AdminUser (no self-registration)
  • Activation: Created as IsActive = true by default
  • Deactivation: AdminUser can deactivate without deleting (soft delete)
  • Deletion: Hard deletion requires separate permission and confirmation
  • Reactivation: Deactivated users can be reactivated by AdminUser

Security Considerations

Password Security

  • Hashing: BCrypt with work factor 12 (configurable)
  • Transmission: Never transmit plaintext password after initial email
  • Storage: Only hashed password stored (no plaintext or reversible encryption)
  • Display: Temporary password shown once to AdminUser if email skipped
  • Rotation: MustChangePassword flag enforced on first login

Email Security

  • Transport: Use TLS for SMTP connections
  • Content: Temporary password in email is acceptable (time-limited, must change)
  • Logging: Never log plaintext passwords (including temporary ones)
  • Retention: Clear temporary password from session after 5 minutes

Authentication Security

  • Lockout: 5 failed attempts = 15-minute lockout (prevents brute force)
  • Session Management: Sessions expire after inactivity (configurable)
  • Token Expiration: Login tokens expire after configured duration
  • Password Expiry: Optional policy-based password expiration

Authorization Security

  • RBAC: All actions permission-checked via role assignments
  • Least Privilege: Users created with minimal access (no roles/apps by default)
  • Audit Trail: All administrative actions logged with actor ID and timestamp

Non-Functional Requirements

Performance

  • User Creation Time: < 2 seconds (excluding email delivery)
  • Email Delivery: Asynchronous (non-blocking)
  • Concurrent Creation: Support 10+ AdminUsers creating users simultaneously

Usability

  • Form Validation: Real-time feedback on username/email availability
  • Autocomplete: Suggest usernames based on full name or email
  • Bulk Import: Out of scope for MVP (future enhancement)

Reliability

  • Email Retry: Automatically retry failed emails (3 attempts, exponential backoff)
  • Transaction Safety: All-or-nothing user creation (no partial states)
  • Error Recovery: Clear error messages with corrective action guidance

Auditability

  • Logging: All user creation events logged with full context
  • Traceability: Link each user to creating AdminUser and timestamp
  • Compliance: Support regulatory audit requirements (GDPR, SOC2, etc.)

Future Enhancements

Phase 2: Identity Management Integration

IdM Sync:

  • Synchronize users from Active Directory, Azure Entra, LDAP
  • Automatic role mapping based on IdM groups
  • Scheduled sync jobs with conflict resolution
  • SSO authentication flow (OAuth2, SAML)

Group-Based Access:

  • Create ApplicationUser groups
  • Assign roles and applications to groups
  • Inherit permissions from group membership

Phase 3: Advanced Features

Self-Service Options:

  • Allow ApplicationUsers to request access to additional applications
  • AdminUser approval workflow for access requests

Bulk Operations:

  • CSV import for bulk user creation
  • Bulk role assignment/revocation
  • Bulk application access grant/revoke

Delegated Administration:

  • Allow non-admin users to create/manage users within their tenant
  • Department-level user management
  • UC-001: Trial User Self-Registration - Self-service user creation for trials
  • UC-003: Application Access Validation - Session validation for ApplicationUsers
  • UC-005: Administrator User Management - Managing AdminUsers (Configuration DB)
  • UC-009: Password Reset Recovery - ApplicationUser password reset flow

Open Questions

  1. Should ApplicationUsers have a "probationary period" with enhanced monitoring?
  2. What is the default password expiration policy (if any)?
  3. Should we support temporary ApplicationUsers (e.g., contractors with end dates)?
  4. How should we handle ApplicationUser to TrialUser conversion?
  5. What analytics/reporting do AdminUsers need for user management?

Glossary

  • ApplicationUser: Permanent, admin-provisioned user with RBAC
  • TrialUser: Self-service, time-limited evaluation user
  • AdminUser: Platform administrator (stored in Configuration database)
  • RBAC: Role-Based Access Control
  • IdM: Identity Management system (Active Directory, Azure Entra, etc.)
  • BCrypt: Adaptive password hashing algorithm (default work factor: 12)
  • SSO: Single Sign-On via external identity provider