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.7.2(2mo ago)037MITPHPPHP ^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 1mo ago

READMEChangelog (10)Dependencies (5)Versions (22)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
- ✅ **Enterprise Security** - CSRF protection, JWT validation, and secure token management
- ✅ **Automatic User Management** - Registration, account linking, and profile synchronization
- ✅ **Advanced Apple Integration** - Custom ASN.1 JWT parser and Sign In with Apple support
- ✅ **Database Integration** - Social account associations with foreign key relationships
- ✅ **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.22.0 or higher
- cURL PHP extension
- OpenSSL PHP extension (for Apple Sign In)

Installation
------------

[](#installation)

### Composer (Recommended)

[](#composer-recommended)

```
composer require glueful/entrada

# Build the extensions cache after adding packages
php glueful extensions:cache

# Enable in development (writes to config/extensions.php)
php glueful extensions:enable Entrada

# Run migrations (if not auto-run)
php glueful migrate run
```

Verify status and details:

```
php glueful extensions:list
php glueful extensions:info Entrada
php glueful extensions:why Glueful\\Extensions\\Entrada\\Services\\EntradaServiceProvider
```

### Local Development Installation

[](#local-development-installation)

If you're working locally (without Composer), place the extension in `extensions/Entrada`, ensure `config/extensions.php` has `local_path` pointing to `extensions` (non‑prod).

Enable the provider for development (choose one):

- CLI (recommended):

    ```
    php glueful extensions:enable Entrada
    ```
- Manual `config/extensions.php` edit:

    ```
    return [
        'enabled' => [
            // ... other providers
            Glueful\\Extensions\\Entrada\\Services\\EntradaServiceProvider::class,
        ],
        'dev_only' => [
            // Optionally keep Entrada dev-only
        ],
        'local_path' => env('APP_ENV') === 'production' ? null : 'extensions',
        'scan_composer' => true,
    ];
    ```

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:why Glueful\\Extensions\\Entrada\\Services\\EntradaServiceProvider
```

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)
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

# Apple Sign In Configuration
APPLE_CLIENT_ID=com.yourdomain.services.id
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

# Entrada Configuration (sauth)
SAUTH_AUTO_REGISTER=true
SAUTH_LINK_ACCOUNTS=true
SAUTH_SYNC_PROFILE=true
```

### Extension Configuration

[](#extension-configuration)

Customize behavior in `config/sauth.php`:

```
return [
    'enabled_providers' => ['google', 'facebook', 'github', 'apple'],
    'auto_register' => env('SAUTH_AUTO_REGISTER', true),
    'link_accounts' => env('SAUTH_LINK_ACCOUNTS', true),
    'sync_profile' => env('SAUTH_SYNC_PROFILE', true),

    // Provider configurations
    'google' => [
        'client_id' => env('GOOGLE_CLIENT_ID'),
        'client_secret' => env('GOOGLE_CLIENT_SECRET'),
        'redirect_uri' => env('GOOGLE_REDIRECT_URI'),
        'scopes' => ['openid', 'profile', 'email'],
    ],
    'facebook' => [
        'app_id' => env('FACEBOOK_APP_ID'),
        'app_secret' => env('FACEBOOK_APP_SECRET'),
        'redirect_uri' => env('FACEBOOK_REDIRECT_URI'),
        'scopes' => ['email', 'public_profile'],
    ],
    'github' => [
        'client_id' => env('GITHUB_CLIENT_ID'),
        'client_secret' => env('GITHUB_CLIENT_SECRET'),
        'redirect_uri' => env('GITHUB_REDIRECT_URI'),
        'scopes' => ['user:email', 'read:user'],
    ],
    '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)

```