PHPackages glueful/entrada - 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. glueful/entrada ActiveGlueful-extension[Authentication & Authorization](/categories/authentication) glueful/entrada =============== Entrada: Social Login & SSO for Glueful (OAuth/OIDC) v1.11.0(2mo ago)149MITPHPPHP ^8.3 Since Sep 14Pushed 2mo agoCompare [ Source](https://github.com/glueful/entrada)[ Packagist](https://packagist.org/packages/glueful/entrada)[ Docs](https://github.com/glueful/entrada)[ RSS](/packages/glueful-entrada/feed)WikiDiscussions main Synced 1w ago READMEChangelog (10)Dependencies (10)Versions (27)Used By (0) Entrada (Social Login & SSO) for Glueful ============================================ [](#entrada-social-login--sso-for-glueful) Overview -------- [](#overview) Entrada provides enterprise-grade OAuth/OIDC social authentication for the Glueful Framework, enabling seamless integration with major providers. It supports both web-based OAuth flows and native mobile app authentication, with automatic user registration, account linking, and comprehensive security features. Features -------- [](#features) - ✅ **Multi-Platform Support** - Google, Facebook, GitHub, and Apple Sign In - ✅ **Dual Authentication Flows** - Web OAuth redirects and native mobile token verification - ✅ **Security** - OAuth `state` CSRF protection, cryptographic Apple ID-token verification (JWKS / RS256), and verified-email-gated account linking - ✅ **Automatic User Management** - Registration, verified-email account linking, and profile synchronization - ✅ **Sign in with Apple** - JWKS-based ID-token signature verification and ES256 client-secret generation - ✅ **Database Integration** - Social account associations via an indexed `user_uuid` reference (no cross-package FK) - ✅ **Comprehensive API** - RESTful endpoints with OpenAPI documentation - ✅ **Health Monitoring** - Built-in diagnostics and configuration validation - ✅ **Flexible Configuration** - Environment variables and runtime configuration Requirements ------------ [](#requirements) - PHP 8.3 or higher - Glueful Framework 1.50.2 or higher - cURL PHP extension - OpenSSL PHP extension (for Apple Sign In) Installation ------------ [](#installation) ### Composer (Recommended) [](#composer-recommended) ``` composer require glueful/entrada # Enable it — installing does not auto-load an extension; this adds the provider to # config/extensions.php's `enabled` list and recompiles the cache. php glueful extensions:enable entrada # Run migrations (if not auto-run) php glueful migrate run ``` In production, manage the `enabled` list in config and run `php glueful extensions:cache` in your deploy step. Verify status and details: ``` php glueful extensions:list php glueful extensions:info entrada ``` ### Local Development Installation [](#local-development-installation) To develop the extension locally, register it as a Composer **path repository** in your app's `composer.json`, then require and enable it: ``` // composer.json "repositories": [ { "type": "path", "url": "extensions/entrada", "options": { "symlink": true } } ] ``` ``` composer require glueful/entrada:@dev php glueful extensions:enable entrada ``` Entries in `config/extensions.php` are plain string FQCNs (no `::class`) — prefer `extensions:enable` over editing by hand. Run the migrations to create the necessary database tables: ``` php glueful migrate run ``` Generate API documentation (optional, if your tooling supports it): ``` php glueful generate:json doc ``` Restart your web server to apply the changes. ### Verify Installation [](#verify-installation) Check status and details: ``` php glueful extensions:list php glueful extensions:info entrada php glueful extensions:diagnose ``` Post-install checklist: - Run migrations (if not auto-run): `php glueful migrate run` - Hit an endpoint to verify: `GET /auth/social/google` (should redirect to Google OAuth) - Rebuild cache after Composer operations: `php glueful extensions:cache` - Check logs for initialization messages or errors Configuration ------------- [](#configuration) ### Provider Credentials Setup [](#provider-credentials-setup) Obtain OAuth credentials from each provider you want to support: #### Google OAuth Setup [](#google-oauth-setup) 1. Visit [Google Cloud Console](https://console.cloud.google.com/) 2. Create or select a project 3. Navigate to "APIs & Services" > "Credentials" 4. Create OAuth 2.0 Client ID 5. Add authorized redirect URI: `https://yourdomain.com/auth/social/google/callback` 6. Enable Google+ API and Google People API #### Facebook OAuth Setup [](#facebook-oauth-setup) 1. Go to [Facebook Developers](https://developers.facebook.com/) 2. Create a new app or select existing 3. Add Facebook Login product 4. Configure Valid OAuth Redirect URIs: `https://yourdomain.com/auth/social/facebook/callback` 5. Set required permissions: `email`, `public_profile` #### GitHub OAuth Setup [](#github-oauth-setup) 1. Go to [GitHub Developer Settings](https://github.com/settings/developers) 2. Create new OAuth App 3. Set Authorization callback URL: `https://yourdomain.com/auth/social/github/callback` 4. Configure required scopes: `user:email`, `read:user` #### Apple Sign In Setup [](#apple-sign-in-setup) 1. Visit [Apple Developer Account](https://developer.apple.com/) 2. Navigate to "Certificates, Identifiers & Profiles" 3. Create Services ID under Identifiers 4. Enable "Sign in with Apple" capability 5. Configure domain and return URLs 6. Create or reuse a private key (`.p8` file). `APPLE_CLIENT_SECRET` accepts the `.p8` file path, an inline PEM, or a pre-built ES256 client-secret JWT (all auto-detected). 7. Set redirect URI: `https://yourdomain.com/auth/social/apple/callback` ### Environment Variables [](#environment-variables) Configure OAuth credentials in your `.env` file: ``` # Google OAuth Configuration GOOGLE_CLIENT_ID=your-google-client-id.googleusercontent.com GOOGLE_CLIENT_SECRET=your-google-client-secret GOOGLE_REDIRECT_URI=https://yourdomain.com/auth/social/google/callback # Facebook OAuth Configuration FACEBOOK_APP_ID=your-facebook-app-id FACEBOOK_APP_SECRET=your-facebook-app-secret FACEBOOK_REDIRECT_URI=https://yourdomain.com/auth/social/facebook/callback # GitHub OAuth Configuration GITHUB_CLIENT_ID=your-github-client-id GITHUB_CLIENT_SECRET=your-github-client-secret GITHUB_REDIRECT_URI=https://yourdomain.com/auth/social/github/callback # Facebook Graph API version (optional; default v21.0) FACEBOOK_API_VERSION=v21.0 # Apple Sign In Configuration APPLE_CLIENT_ID=com.yourdomain.services.id # APPLE_CLIENT_SECRET accepts THREE forms (auto-detected): a .p8 key file path (shown), # an inline PEM private key, or a pre-built ES256 client-secret JWT. APPLE_CLIENT_SECRET=/path/to/AuthKey_XXXXXXXXXX.p8 APPLE_TEAM_ID=XXXXXXXXXX APPLE_KEY_ID=XXXXXXXXXX APPLE_REDIRECT_URI=https://yourdomain.com/auth/social/apple/callback ``` > **`app.url` is required.** When a provider has no explicit `*_REDIRECT_URI` set, Entrada derives the default callback URI from the framework's `app.url` config (`APP_URL` in `.env`) — there is **no**`HTTP_HOST` fallback (host-header injection hardening, 1.9.0). If `app.url` is unset and you rely on the default, the generated `redirect_uri` is a relative path and will fail the provider's registered redirect-URI match. Either set `APP_URL` or provide an explicit per-provider redirect URI. > **Note:** `auto_register` and `sync_profile` are configured in `config/sauth.php` (see below); they are not read from environment variables. ### Extension Configuration [](#extension-configuration) Customize behavior in `config/sauth.php`: ``` return [ 'enabled_providers' => ['google', 'facebook', 'github', 'apple'], 'auto_register' => true, // auto-create user accounts for new social logins 'sync_profile' => true, // sync profile data from social providers // Account linking is governed by the verified-email gate (see "Account Linking" below), // not a config flag — a social identity is auto-linked to an existing local account only // when the provider asserts the email is verified. // Provider configurations 'google' => [ 'client_id' => env('GOOGLE_CLIENT_ID'), 'client_secret' => env('GOOGLE_CLIENT_SECRET'), 'redirect_uri' => env('GOOGLE_REDIRECT_URI'), ], 'facebook' => [ 'app_id' => env('FACEBOOK_APP_ID'), 'app_secret' => env('FACEBOOK_APP_SECRET'), 'redirect_uri' => env('FACEBOOK_REDIRECT_URI'), 'api_version' => env('FACEBOOK_API_VERSION', 'v21.0'), // Graph API version ], 'github' => [ 'client_id' => env('GITHUB_CLIENT_ID'), 'client_secret' => env('GITHUB_CLIENT_SECRET'), 'redirect_uri' => env('GITHUB_REDIRECT_URI'), ], 'apple' => [ 'client_id' => env('APPLE_CLIENT_ID'), 'client_secret' => env('APPLE_CLIENT_SECRET'), 'team_id' => env('APPLE_TEAM_ID'), 'key_id' => env('APPLE_KEY_ID'), 'redirect_uri' => env('APPLE_REDIRECT_URI'), ], ]; ``` ### Advanced User Provisioning [](#advanced-user-provisioning) Entrada now supports configurable social-field mapping, storage-column mapping, and an optional post-registration hook. #### 1) Field and storage mapping [](#1-field-and-storage-mapping) Use this when your app schema differs from Glueful defaults (for example, custom username/photo columns). ``` return [ 'field_mapping' => [ 'social' => [ 'uuid' => ['id'], 'email' => ['email'], 'username' => ['username', 'login'], 'first_name' => ['first_name', 'given_name'], 'last_name' => ['last_name', 'family_name'], 'photo_url' => ['photo_url', 'picture', 'avatar_url'], 'email_verified' => ['verified_email', 'email_verified'], ], ], 'storage' => [ 'users' => [ 'table' => 'users', 'columns' => [ 'uuid' => 'uuid', 'username' => 'username', 'email' => 'email', 'password' => 'password', 'status' => 'status', 'created_at' => 'created_at', 'email_verified_at' => 'email_verified_at', ], ], 'profiles' => [ 'table' => 'profiles', 'columns' => [ 'uuid' => 'uuid', 'user_uuid' => 'user_uuid', 'first_name' => 'first_name', 'last_name' => 'last_name', 'photo_url' => 'photo_url', ], ], ], ]; ``` #### 2) Optional post-registration hook (disabled by default) [](#2-optional-post-registration-hook-disabled-by-default) Use this to run app-specific bootstrap logic after social signup (for example: assign a default role). ``` return [ 'post_registration' => [ 'enabled' => false, // opt-in // Invokable class-string (recommended) or callable // Signature: (string $userUuid, array $socialData, ApplicationContext $context): void 'handler' => App\Auth\SocialRegistrationHandler::class, ], ]; ``` Recommended handler pattern: - Keep Entrada generic. - Put business logic (roles, app profiles, tenant defaults) in your app handler. - Throw on critical failures when strict behavior is desired. #### 3) Transaction behavior for social registration [](#3-transaction-behavior-for-social-registration) For new social users, Entrada runs the core creation sequence in a DB transaction, then executes app provisioning after commit: 1. Insert user 2. Link social account 3. Commit 4. Run post-registration handler (if enabled) If step 1 or 2 fails, the transaction is rolled back and signup fails with a generic API error. If step 4 fails, signup fails with a generic API error, but committed core records remain. Note: profile synchronization remains best-effort and runs after core creation. Usage ----- [](#usage) ### PHP Usage Examples [](#php-usage-examples) #### Using Social Login in Controllers [](#using-social-login-in-controllers) ```