Download the PHP package glueful/entrada without Composer

Entrada (Social Login & SSO) for Glueful

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

• ✅ 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

• PHP 8.3 or higher
• Glueful Framework 1.50.2 or higher
• cURL PHP extension
• OpenSSL PHP extension (for Apple Sign In)

Installation

Composer (Recommended)

In production, manage the enabled list in config and run php glueful extensions:cache in your deploy step.

Verify status and details:

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:

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:

Generate API documentation (optional, if your tooling supports it):

Restart your web server to apply the changes.

Verify Installation

Check status and details:

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

Provider Credentials Setup

Obtain OAuth credentials from each provider you want to support:

Google OAuth Setup

1. Visit Google Cloud Console
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

1. Go to Facebook Developers
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

1. Go to GitHub Developer Settings
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

1. Visit Apple Developer Account
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

Configure OAuth credentials in your .env file:

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

Customize behavior in config/sauth.php:

Advanced User Provisioning

Entrada now supports configurable social-field mapping, storage-column mapping, and an optional post-registration hook.

1) Field and storage mapping

Use this when your app schema differs from Glueful defaults (for example, custom username/photo columns).

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

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

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

PHP Usage Examples

Using Social Login in Controllers

Direct Provider Usage

Managing Social Accounts

Custom Integration in Services

Middleware for Social Authentication

Event Listeners for Social Login

Web-Based OAuth Flow

For traditional web applications, use redirect-based OAuth:

Native Mobile App Flow

For mobile applications, use direct token verification:

Backend Token Verification

API Endpoints

The extension provides comprehensive REST API endpoints:

Authentication Endpoints

All public endpoints above are rate limited per-IP (native POSTs 10/min; init + callbacks 20/min). POST /auth/social/apple additionally accepts an optional nonce field for native replay protection (see Native nonce binding).

Account Management Endpoints

Example API Usage

Advanced Features

Automatic User Registration

When auto_register is enabled, the extension automatically creates user accounts:

Account Linking

When a social login matches an existing local account by email, Entrada auto-links the social identity only if the provider asserts the email is verified (the verified-email gate — there is no link_accounts config flag; the gate is the control). If the email is unverified, the login is refused with a 409 and the user must sign in and link the provider explicitly from their account settings. This prevents account takeover via an attacker-controlled unverified email at the provider.

Provider verified-email matrix

Each provider asserts email verification differently; the matrix below is what drives the auto-link gate (and whether new users get email_verified_at stamped):

Profile Synchronization

Automatically sync user profiles from social providers:

Apple Sign In Specifics

The extension includes advanced Apple Sign In support:

ID-token signature verification

Apple ID tokens are verified cryptographically before any claim is trusted: the RSA public key is reconstructed from Apple's JWKS (https://appleid.apple.com/auth/keys), the RS256 signature over the token is checked with openssl_verify, the algorithm is pinned to RS256 (rejecting alg: none and RS/HS confusion), and iss/aud/exp are asserted. This happens automatically inside verifyNativeToken() and the web callback — both share one verified-claims path; callers never decode an unverified token themselves.

The bundled ASN1Parser is only a DER reader used when generating the Apple client-secret JWT — it performs the DER→JOSE conversion of the ES256 signature during client-secret signing. It is not part of ID-token validation: incoming ID tokens are verified RS256 against Apple's JWKS (above).

JWKS caching: Apple's JWKS (/auth/keys) is cached automatically in the framework cache store (1-hour TTL) so it stays out of the critical path of every login. On a kid miss (key rotation) it does a single bypass-refetch; failed/malformed responses are never cached, and it degrades gracefully to a direct fetch when no cache is available.

Client-secret forms: APPLE_CLIENT_SECRET accepts three forms, auto-detected structurally — a .p8 key-file path, an inline PEM private key, or a pre-built ES256 client-secret JWT (used verbatim).

Native nonce binding (replay protection)

POST /auth/social/apple accepts an optional nonce field. When a native client supplies the raw nonce it bound to its Sign in with Apple SDK request, Entrada requires the verified ID token's nonce claim to match (sha256(rawNonce) per the Apple SDK convention, or the raw value), closing the captured-token replay window. Clients that send no nonce are unaffected. Native clients are recommended to supply a nonce.

Apple-Specific Considerations

• First-Time Data: Apple only provides name and email on first authentication
• Privacy: Users can choose to hide their email (Apple provides a proxy email)
• JWT Validation: Requires complex signature verification with Apple's rotating keys

Database Schema

The extension creates a social_accounts table:

Security Features

CSRF Protection

Every OAuth flow is protected by a state parameter. A per-provider token is generated and stored in the session when the flow is initiated, then validated on the callback: it is compared with hash_equals(), is single-use (cleared on every callback), and a missing or mismatched value rejects the callback with a 401 before any authorization code is exchanged. This is automatic — no caller action is required.

Rate Limiting

All public social-auth endpoints are rate limited per-IP (sliding window):

• Native token POSTs (POST /auth/social/{provider}) — 10 requests/min (token-grinding surface).
• OAuth callbacks and init redirects (GET /auth/social/{provider}, .../callback) — 20 requests/min.
• Unlink (DELETE /user/social-accounts/{uuid}) — 10 requests/min.

Implementation note: route rate limiting in Glueful requires the ->rateLimit(n, minutes) builder plus ->middleware(['rate_limit']). The middleware-string form (rate_limit:10,60) is a silent no-op — the framework's limiter ignores string params and reads only the builder config. If you add your own rate-limited routes, use the builder form.

Verified-email session claims

The provider's verified-email status flows end to end: a verified email stamps email_verified_at on the user row, and that drives email_verified: true in the session / OIDC claims reported back to the client (previously always false). See the provider verified-email matrix above for which providers assert verification.

profile_data privacy

The social_accounts.profile_data column stores only a minimal identity allowlist (id, email, name, first_name, last_name, username, picture, email_verified) — never the full raw provider payload. Nothing in the extension reads the column back, so this is pure exposure reduction.

JWT Token Management

Secure token generation and validation:

Secure Configuration

• Environment variable configuration
• Encrypted client secrets storage
• Secure OAuth redirect validation
• Provider token verification

Provider-Specific Implementation

Google Provider

Facebook Provider

Graph API version: configurable via FACEBOOK_API_VERSION / sauth.facebook.api_version (default v21.0). Facebook emails are treated as unverified (the Graph API exposes no per-email verified flag), so email-match account linking always requires a manual link.

GitHub Provider

PKCE: GitHub OAuth Apps do not support PKCE, so the GitHub code flow relies on the OAuth state parameter for request binding (rather than a code_verifier).

Apple Provider

Monitoring and Troubleshooting

Health Monitoring

Monitor extension health:

Common Issues

1. OAuth Redirect Mismatch

   • Ensure redirect URIs match exactly in provider settings
   • Use HTTPS for production environments

2. Invalid Client Credentials

   • Verify client ID and secret are correct
   • Check environment variable names

3. Apple Sign In Issues

   • Ensure private key file is readable
   • Verify Team ID and Key ID are correct
   • Check domain registration with Apple
4. Token Validation Failures
   • Verify system time is synchronized
   • Check internet connectivity for provider APIs
   • Ensure required PHP extensions are installed

Debug Mode

Enable detailed logging:

Health Checks

Migration and Integration

Existing User Migration

Migrate existing users to social login:

Custom Provider Implementation

Extend the system with custom providers:

Performance Considerations

• Connection Pooling: HTTP clients use connection pooling for provider APIs
• JWKS Caching: Apple's JWKS is cached in the framework cache store (1-hour TTL) so it stays out of the per-login critical path; a kid miss triggers a single refetch for key rotation
• Database Optimization: Indexed social accounts table for fast lookups

License

This extension is licensed under the MIT License.

Support

For issues, feature requests, or questions about the SocialLogin extension:

• Create an issue in the repository
• Consult the Glueful documentation
• Check provider-specific documentation for OAuth setup
• Use the built-in health monitoring for diagnostics