PHPackages azaharizaman/nexus-sso - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. azaharizaman/nexus-sso ActiveLibrary[Authentication & Authorization](/categories/authentication) azaharizaman/nexus-sso ====================== ⚠️ PENDING: Framework-agnostic Single Sign-On package for Nexus ERP v0.1.0-alpha1(1mo ago)02↓100%MITPHPPHP ^8.3 Since May 5Pushed 1mo agoCompare [ Source](https://github.com/azaharizaman/nexus-sso)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-sso)[ RSS](/packages/azaharizaman-nexus-sso/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (6)Versions (2)Used By (0) Nexus\\SSO - Single Sign-On Package =================================== [](#nexussso---single-sign-on-package) [![Tests](https://camo.githubusercontent.com/8c986adc318ef00fe87b496ad12420d95d4a9a10071cef8b68cfa5f392f89557/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d383125323070617373696e672d79656c6c6f77)](tests/)[![Status](https://camo.githubusercontent.com/2c61895b20172fcc210cba37698d64934a60acfe8326e4c16efa2596013114e2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d70656e64696e672d6f72616e6765)](PENDING_WORK.md)[![PHP Version](https://camo.githubusercontent.com/42df5991a968c0783a689ce697865ac6fbe316246743abc265ab342ae158dc7d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e332532422d626c7565)](composer.json)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE) **⚠️ PACKAGE PENDING - Phase 4 Incomplete** (See [`PENDING_WORK.md`](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 ---------- [](#-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 --------------------------------- [](#-installation--dependencies) ``` composer require azaharizaman/nexus-sso ``` ### Runtime Dependencies [](#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 --------------- [](#️-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 [](#the-separation-principle) PackageResponsibilityAnalogy**`Nexus\SSO`****Authentication Orchestration**"The bouncer" - verifies credentials with external IdP**`Nexus\Identity`****User Management**"The membership database" - stores users, roles, permissions🚀 Quick Start ------------- [](#-quick-start) ### 1. Install Package Dependencies [](#1-install-package-dependencies) ``` cd packages/SSO composer install ``` ### 2. Define Core Interfaces (Phase 1 - Completed) [](#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) [](#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) [](#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 [](#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 ---------------- [](#-usage-examples) ### Initiate SSO Login [](#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 [](#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 --------- [](#-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 -------------------- [](#️-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 ----------------------- [](#-implementation-status) ### ✅ Phase 1: Core Infrastructure (COMPLETED) [](#-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) [](#-phase-2-saml-20-provider-completed) - Saml2Provider implementation - SAML signature validation - SP metadata generation - SAML-specific tests ### ✅ Phase 3: OAuth2/OIDC Provider (COMPLETED) [](#-phase-3-oauth2oidc-provider-completed) - OAuth2Provider implementation - OidcProvider implementation - JWT ID token validation - OAuth-specific tests ### ⏳ Phase 4: Vendor-Specific Providers (PLANNED) [](#-phase-4-vendor-specific-providers-planned) - AzureAdProvider (Azure AD/Entra ID) - GoogleWorkspaceProvider - OktaProvider 🔗 Integration with Other Packages --------------------------------- [](#-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 --------------- [](#-documentation) - [Implementation Plan](../../docs/SSO_IMPLEMENTATION_PLAN.md) - [Requirements](../../docs/REQUIREMENTS_SSO.md) - [Executive Summary](../../docs/SSO_EXECUTIVE_SUMMARY.md) - [Architecture Diagrams](../../docs/SSO_ARCHITECTURE_DIAGRAMS.md) 📖 Documentation --------------- [](#-documentation-1) ### Package Documentation [](#package-documentation) - **[Getting Started Guide](docs/getting-started.md)** - Quick start guide with prerequisites, concepts, and first integration - **[API Reference](docs/api-reference.md)** - Complete documentation of all interfaces, value objects, and exceptions - **[Integration Guide](docs/integration-guide.md)** - Laravel and Symfony integration examples - **[Basic Usage Example](docs/examples/basic-usage.php)** - Simple usage patterns - **[Advanced Usage Example](docs/examples/advanced-usage.php)** - Advanced scenarios and patterns ### Additional Resources [](#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 -------------- [](#-contributing) This package follows strict architectural guidelines: 1. **Framework Agnostic**: No Laravel dependencies in package layer 2. **Contract-Driven**: Define interfaces first, implement later 3. **Immutability**: Use `readonly` properties for all value objects 4. **PHP 8.3+**: Native enums, constructor property promotion, strict types 5. **TDD**: Red-Green-Refactor methodology 📄 License --------- [](#-license) MIT License. See [LICENSE](LICENSE) for details. --- **Package Version**: 0.1.0 (Development) **PHP Version**: 8.3+ **Status**: 🟡 In Development (Phase 1 Complete) ### Health Score 36 — LowBetter than 79% of packages Maintenance93 Actively maintained with recent releases Popularity3 Limited adoption so far Community9 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 76.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 36d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman) --- Top Contributors [![azaharizaman](https://avatars.githubusercontent.com/u/117408?v=4)](https://github.com/azaharizaman "azaharizaman (461 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/azaharizaman-nexus-sso/health.svg) ``` [![Health](https://phpackages.com/badges/azaharizaman-nexus-sso/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-sso) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[simplesamlphp/saml2 SAML2 PHP library from SimpleSAMLphp 30417.8M41](/packages/simplesamlphp-saml2)[kimai/kimai Kimai - Time Tracking 4.7k8.7k1](/packages/kimai-kimai)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 744284.3k34](/packages/civicrm-civicrm-core)[web-auth/webauthn-lib FIDO2/Webauthn Support For PHP 1237.8M117](/packages/web-auth-webauthn-lib)[drenso/symfony-oidc-bundle OpenID connect bundle for Symfony 93714.0k3](/packages/drenso-symfony-oidc-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)