README

Orchestrator for user lifecycle management

Coordinates Identity, Tenant, and AuditLogger packages for user lifecycle management.

Overview

The IdentityOperations orchestrator is a non-business operational orchestrator that manages user lifecycle operations within the Nexus ERP system. It provides comprehensive user management workflows including onboarding, authentication, permissions, and MFA management.

Key Capabilities

User Onboarding - Create users, assign to tenants, setup permissions, send welcome notifications
User Lifecycle - Activate, suspend, deactivate users with proper audit trails
MFA Management - Enable, verify, disable MFA for users
Permission Management - Assign, revoke, check permissions

Value to Other Orchestrators

Orchestrator	Value Provided
TenantOperations	Validates tenant has active users
FinanceOperations	Validates user has proper financial permissions
HumanResourceOperations	Manages employee user accounts
SalesOperations	Manages sales user permissions
ProcurementOperations	Manages procurement user permissions
SupplyChainOperations	Manages warehouse user permissions
CRMOperations	Manages CRM user permissions

Quick Start

Example: User Onboarding

use Nexus\IdentityOperations\Coordinators\UserOnboardingCoordinator;
use Nexus\IdentityOperations\DTOs\UserCreateRequest;

$coordinator = $container->get(UserOnboardingCoordinator::class);

$request = new UserCreateRequest(
    email: 'john.doe@example.com',
    password: 'secure-password',
    firstName: 'John',
    lastName: 'Doe',
    tenantId: 'tenant-123',
    roles: ['user'],
    sendWelcomeEmail: true,
);

$result = $coordinator->createUser($request);

if ($result->success) {
    echo "User created: {$result->userId}";
    echo "Tenant assignment: {$result->tenantUserId}";
} else {
    echo "Onboarding failed: {$result->message}";
}

Example: User Lifecycle (Suspend)

use Nexus\IdentityOperations\Coordinators\UserLifecycleCoordinator;
use Nexus\IdentityOperations\DTOs\UserSuspendRequest;

$coordinator = $container->get(UserLifecycleCoordinator::class);

$request = new UserSuspendRequest(
    userId: 'user-456',
    suspendedBy: 'admin-789',
    reason: 'Policy violation',
);

$result = $coordinator->suspend($request);

if ($result->success) {
    echo "User suspended: {$result->suspendedAt}";
} else {
    echo "Suspend failed: {$result->message}";
}

Example: MFA Enable

use Nexus\IdentityOperations\Coordinators\MfaCoordinator;
use Nexus\IdentityOperations\DTOs\MfaEnableRequest;

$coordinator = $container->get(MfaCoordinator::class);

$request = new MfaEnableRequest(
    userId: 'user-456',
    method: MfaMethod::TOTP,
);

$result = $coordinator->enable($request);

if ($result->success) {
    echo "MFA enabled, secret: {$result->secret}";
    echo "QR code: {$result->qrCodeUrl}";
}

Example: Permission Assignment

use Nexus\IdentityOperations\Coordinators\UserPermissionCoordinator;
use Nexus\IdentityOperations\DTOs\PermissionAssignRequest;

$coordinator = $container->get(UserPermissionCoordinator::class);

$request = new PermissionAssignRequest(
    userId: 'user-456',
    permission: 'finance.reports.view',
    tenantId: 'tenant-123',
    assignedBy: 'admin-789',
);

$result = $coordinator->assign($request);

if ($result->success) {
    echo "Permission assigned: {$result->permissionId}";
}

Architecture

This orchestrator follows the Advanced Orchestrator Pattern with these principles:

Coordinators are Traffic Cops - Direct flow, don't do work
DataProviders Aggregate - Cross-package data aggregation
Rules are Composable - Individual, testable validation classes
Services do Heavy Lifting - Complex business logic
Strict Contracts - Always use DTOs

Directory Structure

src/
├── Coordinators/           # Entry points for operations
├── DataProviders/         # Cross-package data aggregation
├── Rules/                 # Validation constraints
├── Services/              # Complex business logic
├── DTOs/                 # Request/Response objects
├── Contracts/             # Interfaces
└── Exceptions/            # Domain errors

Available Coordinators

Coordinator	Purpose	Key Operations
`UserOnboardingCoordinator`	Create new users	`createUser()`, `setupInitialPermissions()`
`UserLifecycleCoordinator`	Manage user states	`activate()`, `suspend()`, `deactivate()`
`UserAuthenticationCoordinator`	Authenticate users	`authenticate()`, `refreshToken()`, `logout()`
`UserPermissionCoordinator`	Manage permissions	`assign()`, `revoke()`, `check()`
`MfaCoordinator`	Manage MFA	`enable()`, `verify()`, `disable()`

Installation

composer require azaharizaman/nexus-identity-operations

Dependencies

azaharizaman/nexus-identity - Core user management
azaharizaman/nexus-tenant - Tenant context
azaharizaman/nexus-audit-logger - Audit trail logging
azaharizaman/nexus-common - Common utilities

Architecture Layers

┌─────────────────────────────────────────────────────────┐
│                    Adapters (L3)                        │
│   Implements orchestrator interfaces                    │
└─────────────────────────────────────────────────────────┘
                            ▲ implements
┌─────────────────────────────────────────────────────────┐
│              IdentityOperations (L2)                     │
│   - Defines own interfaces in Contracts/                │
│   - Depends only on PSR interfaces                      │
│   - Coordinates multi-package workflows                 │
└─────────────────────────────────────────────────────────┘
                            ▲ uses via interfaces
┌─────────────────────────────────────────────────────────┐
│                Atomic Packages (L1)                      │
│   - Identity, Tenant, AuditLogger                       │
└─────────────────────────────────────────────────────────┘

Testing

# Unit tests (Rules, Services)
vendor/bin/phpunit tests/Unit

# Integration tests (Coordinators)
vendor/bin/phpunit tests/Integration

License

MIT License

azaharizaman / nexus-identity-operations

Maintainers

Package info

Statistics

Security