README

⚠️ PACKAGE PENDING - Phase 4 Incomplete (See PENDING_WORK.md)

Framework-agnostic Single Sign-On (SSO) package for Nexus ERP monorepo. Supports SAML 2.0, OAuth2/OIDC, Azure AD, Google Workspace, and custom identity providers.

🎯 Features

Multi-Protocol Support: SAML 2.0, OAuth2, OpenID Connect (OIDC)
Vendor Integrations: Azure AD (Entra ID), Google Workspace, Okta (planned)
Just-In-Time Provisioning: Auto-create users from SSO profiles
Attribute Mapping: Flexible mapping from IdP attributes to local user fields
Multi-Tenant Ready: Per-tenant SSO configuration
CSRF Protection: Secure state validation for callbacks
Framework Agnostic: Pure PHP 8.3+ with minimal dependencies

📦 Installation & Dependencies

composer require azaharizaman/nexus-sso

Runtime Dependencies

onelogin/php-saml ^4.3 - SAML 2.0 protocol implementation
league/oauth2-client ^2.8 - OAuth2/OIDC client library
psr/log ^3.0 - Logging interface (framework-agnostic)

🏗️ Architecture

The Nexus\SSO package is designed to be completely decoupled from Nexus\Identity. It defines contracts (interfaces) that your application implements using the Identity package.

The Separation Principle

Package	Responsibility	Analogy
`Nexus\SSO`	Authentication Orchestration	"The bouncer" - verifies credentials with external IdP
`Nexus\Identity`	User Management	"The membership database" - stores users, roles, permissions

🚀 Quick Start

1. Install Package Dependencies

cd packages/SSO
composer install

2. Define Core Interfaces (Phase 1 - Completed)

The package provides these core contracts:

SsoManagerInterface - Main SSO orchestration
SsoProviderInterface - Base provider contract
SamlProviderInterface - SAML 2.0 specific operations
OAuthProviderInterface - OAuth2/OIDC specific operations
UserProvisioningInterface - Bridge to Identity (you implement this)
AttributeMapperInterface - Attribute mapping service
SsoConfigRepositoryInterface - Configuration storage
CallbackStateValidatorInterface - CSRF protection
StateStorageInterface - Temporary state storage
SsoSessionRepositoryInterface - Session management

3. Available Providers (Phases 2-3 - Completed)

SAML 2.0 Provider (Saml2Provider):

Full SAML 2.0 authentication flow
SP metadata XML generation
SAML assertion parsing and validation
Single Logout (SLO) support
Signature validation (configurable)

OAuth 2.0 Provider (OAuth2Provider):

Generic OAuth 2.0 flow
Authorization code exchange
Userinfo endpoint integration
Token refresh support
Flexible attribute mapping

4. Implement User Provisioning (Your Application)

In your consuming application, implement the UserProvisioningInterface:

namespace App\Services\SSO;

use Nexus\SSO\Contracts\UserProvisioningInterface;
use Nexus\SSO\ValueObjects\UserProfile;
use Nexus\Identity\Contracts\UserManagerInterface;

final readonly class IdentityUserProvisioner implements UserProvisioningInterface
{
    public function __construct(
        private UserManagerInterface $userManager
    ) {}

    public function findOrCreateUser(
        UserProfile $profile,
        string $providerName,
        string $tenantId
    ): string {
        // Check if user exists by SSO ID or email
        $existingUser = $this->findBySsoId($profile->ssoUserId, $providerName);
        
        if ($existingUser) {
            return $existingUser->id;
        }

        // JIT provisioning - create new user
        return $this->userManager->createUser([
            'email' => $profile->email,
            'first_name' => $profile->firstName,
            'last_name' => $profile->lastName,
            'display_name' => $profile->displayName,
        ]);
    }
    
    // ... implement other methods
}

4. Configure SSO Provider

use Nexus\SSO\ValueObjects\SsoProviderConfig;
use Nexus\SSO\ValueObjects\SsoProtocol;
use Nexus\SSO\ValueObjects\AttributeMap;

$azureConfig = new SsoProviderConfig(
    providerName: 'azure',
    protocol: SsoProtocol::OIDC,
    clientId: 'your-azure-client-id',
    clientSecret: 'your-azure-client-secret',
    discoveryUrl: 'https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration',
    redirectUri: 'https://your-app.com/sso/callback/azure',
    attributeMap: new AttributeMap(
        mappings: [
            'sso_user_id' => 'oid',
            'email' => 'email',
            'first_name' => 'given_name',
            'last_name' => 'family_name',
        ],
        requiredFields: ['email', 'sso_user_id']
    ),
    enabled: true
);

📚 Usage Examples

Initiate SSO Login

use Nexus\SSO\Contracts\SsoManagerInterface;

class LoginController
{
    public function __construct(
        private readonly SsoManagerInterface $ssoManager
    ) {}

    public function redirectToAzure()
    {
        $result = $this->ssoManager->initiateLogin(
            providerName: 'azure',
            tenantId: 'tenant-123',
            parameters: ['returnUrl' => '/dashboard']
        );

        return redirect($result['authUrl']);
    }
}

Handle SSO Callback

public function handleCallback(Request $request)
{
    $session = $this->ssoManager->handleCallback(
        providerName: 'azure',
        callbackData: [
            'code' => $request->get('code'),
        ],
        state: $request->get('state')
    );

    // Session contains authenticated user profile
    $userProfile = $session->userProfile;

    // Log user in locally
    auth()->loginUsingId($userProfile->ssoUserId);

    return redirect('/dashboard');
}

🧪 Testing

Run tests:

./vendor/bin/phpunit

Run tests with coverage:

./vendor/bin/phpunit --coverage-html coverage

Current test coverage: 81 tests, 202 assertions, 100% passing

🏗️ Package Structure

packages/SSO/
├── composer.json
├── phpunit.xml
├── README.md
├── src/
│   ├── Contracts/              # Interfaces (framework agnostic)
│   │   ├── SsoManagerInterface.php
│   │   ├── SsoProviderInterface.php
│   │   ├── UserProvisioningInterface.php
│   │   ├── AttributeMapperInterface.php
│   │   ├── SsoConfigRepositoryInterface.php
│   │   ├── CallbackStateValidatorInterface.php
│   │   ├── StateStorageInterface.php
│   │   └── SsoSessionRepositoryInterface.php
│   ├── Services/               # Core services
│   │   ├── AttributeMapper.php
│   │   └── CallbackStateValidator.php
│   ├── ValueObjects/           # Immutable domain data
│   │   ├── SsoProtocol.php (enum)
│   │   ├── UserProfile.php
│   │   ├── CallbackState.php
│   │   ├── AttributeMap.php
│   │   ├── SsoProviderConfig.php
│   │   └── SsoSession.php
│   └── Exceptions/             # Domain exceptions
│       ├── SsoException.php
│       ├── SsoProviderNotFoundException.php
│       ├── InvalidCallbackStateException.php
│       ├── AttributeMappingException.php
│       ├── SsoAuthenticationException.php
│       ├── SsoConfigurationException.php
│       ├── SsoProviderException.php
│       ├── SsoSessionExpiredException.php
│       ├── TokenRefreshException.php
│       └── UserProvisioningException.php
└── tests/
    └── Unit/
        ├── Services/
        ├── ValueObjects/
        └── Exceptions/

📋 Implementation Status

✅ Phase 1: Core Infrastructure (COMPLETED)

Package structure
Core contracts (8 interfaces)
Value objects (6 classes)
Exceptions (10 classes)
AttributeMapper service
CallbackStateValidator service
Unit tests (81 tests passing)

✅ Phase 2: SAML 2.0 Provider (COMPLETED)

Saml2Provider implementation
SAML signature validation
SP metadata generation
SAML-specific tests

✅ Phase 3: OAuth2/OIDC Provider (COMPLETED)

OAuth2Provider implementation
OidcProvider implementation
JWT ID token validation
OAuth-specific tests

⏳ Phase 4: Vendor-Specific Providers (PLANNED)

AzureAdProvider (Azure AD/Entra ID)
GoogleWorkspaceProvider
OktaProvider

🔗 Integration with Other Packages

Nexus\Identity: User management, roles, permissions (via UserProvisioningInterface)
Nexus\Tenant: Multi-tenancy support (SSO configs scoped by tenant)
Nexus\AuditLogger: Audit trail for SSO events
Nexus\Telemetry: Telemetry for SSO metrics

📖 Documentation

Package Documentation

Getting Started Guide - Quick start guide with prerequisites, concepts, and first integration
API Reference - Complete documentation of all interfaces, value objects, and exceptions
Integration Guide - Laravel and Symfony integration examples
Basic Usage Example - Simple usage patterns
Advanced Usage Example - Advanced scenarios and patterns

Additional Resources

IMPLEMENTATION_SUMMARY.md - Implementation progress and metrics
REQUIREMENTS.md - Detailed requirements
TEST_SUITE_SUMMARY.md - Test coverage and results
VALUATION_MATRIX.md - Package valuation metrics
See root ARCHITECTURE.md for overall system architecture

🤝 Contributing

This package follows strict architectural guidelines:

Framework Agnostic: No Laravel dependencies in package layer
Contract-Driven: Define interfaces first, implement later
Immutability: Use readonly properties for all value objects
PHP 8.3+: Native enums, constructor property promotion, strict types
TDD: Red-Green-Refactor methodology

📄 License

MIT License. See LICENSE for details.

Package Version: 0.1.0 (Development)
PHP Version: 8.3+
Status: 🟡 In Development (Phase 1 Complete)

azaharizaman / nexus-sso

Maintainers

Package info

Statistics

Security

README

🎯 Features

📦 Installation & Dependencies

Runtime Dependencies

🏗️ Architecture

The Separation Principle

🚀 Quick Start

1. Install Package Dependencies

2. Define Core Interfaces (Phase 1 - Completed)

3. Available Providers (Phases 2-3 - Completed)

4. Implement User Provisioning (Your Application)

4. Configure SSO Provider

📚 Usage Examples

Initiate SSO Login

Handle SSO Callback

🧪 Testing

🏗️ Package Structure

📋 Implementation Status

✅ Phase 1: Core Infrastructure (COMPLETED)

✅ Phase 2: SAML 2.0 Provider (COMPLETED)

✅ Phase 3: OAuth2/OIDC Provider (COMPLETED)

⏳ Phase 4: Vendor-Specific Providers (PLANNED)

🔗 Integration with Other Packages

📖 Documentation

📖 Documentation

Package Documentation

Additional Resources

🤝 Contributing

📄 License