franciscodlxdev / nativephp-social-login
Social login for NativePHP Mobile: OAuth 2.0 + PKCE in the system browser (ASWebAuthenticationSession, Custom Tabs) with LinkedIn, X, Mercado Libre, Twitch, GitHub, Discord, Slack, Strava, Telegram and TikTok. No client secret in the app.
Package info
github.com/franciscodlx/nativephp-social-login-plugin
Type:nativephp-plugin
pkg:composer/franciscodlxdev/nativephp-social-login
Requires
- php: ^8.3
- illuminate/cache: ^11.0|^12.0|^13.0
- illuminate/console: ^11.0|^12.0|^13.0
- illuminate/http: ^11.0|^12.0|^13.0
- illuminate/support: ^11.0|^12.0|^13.0
- nativephp/mobile: ^3.0|^4.0
Requires (Dev)
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Login social para NativePHP Mobile (iOS, Android) con OAuth 2.0 + PKCE en el navegador del sistema: ASWebAuthenticationSession en iOS y Custom Tabs en Android. Sin WebView y sin client_secret en la app. Incluye LinkedIn, X, Mercado Libre, Twitch, GitHub, Discord, Slack, Strava, Telegram y TikTok.
Es la versión para NativePHP de la familia de React Native, Flutter, Capacitor y NativeScript: mismo flujo, mismos códigos de error.
Compatibilidad
| Paquete | NativePHP Mobile | PHP | Laravel | iOS | Android |
|---|---|---|---|---|---|
| 0.1.x | 4.8 (probado), 3 | ≥ 8.3 | 11, 12, 13 | ≥ 15.0 | ≥ 7.0 (API 24) |
Instalación
composer require franciscodlxdev/nativephp-social-login php artisan native:plugin:register franciscodlxdev/nativephp-social-login
En .env, los esquemas de tus redirects (separados por coma):
SOCIAL_LOGIN_REDIRECT_SCHEMES=miapp
- iOS: nada más.
ASWebAuthenticationSessionrecibemiapp://…sin registrar el esquema. - Android: un hook
post_compileagrega esos esquemas alintent-filterde la actividad de redirect del plugin, más las<queries>para encontrar navegadores en Android 11+. Vuelve a compilar (php artisan native:run) cuando cambies la lista. Si falta un esquema,signInfalla conINVALID_CONFIGen lugar de dejar el navegador abierto sin regreso.
Usa un esquema propio de tu app, distinto de NATIVEPHP_DEEPLINK_SCHEME: ese lo atiende NativePHP para navegar entre pantallas.
Cómo funciona
El navegador abre y cierra fuera de PHP, así que el inicio de sesión tiene dos pasos:
SocialLogin::signIn($provider, $options)generastate, PKCE ynonce, guarda la solicitud pendiente en la caché del dispositivo y abre el navegador. Regresa enseguida.- Lo nativo responde con un evento.
AuthSessionCompletedtrae la URL del redirect, que pasas aSocialLogin::complete($url).AuthSessionFailedtrae el código de error, que pasas aSocialLogin::fail($code, $message).
complete() solo acepta un redirect con el state de un inicio de sesión que la app abrió, y lo consume: un evento falsificado o repetido no puede inyectar un código.
Uso
En una pantalla nativa (NativeComponent, NativePHP 4):
use Franciscodlxdev\SocialLogin\AuthException; use Franciscodlxdev\SocialLogin\Events\AuthSessionCompleted; use Franciscodlxdev\SocialLogin\Events\AuthSessionFailed; use Franciscodlxdev\SocialLogin\Facades\SocialLogin; use Illuminate\Support\Facades\Http; use Native\Mobile\Attributes\On; use Native\Mobile\Edge\NativeComponent; class Login extends NativeComponent { public string $error = ''; public function signInWithLinkedIn(): void { SocialLogin::signIn(SocialLogin::linkedin(), [ 'clientId' => 'TU_CLIENT_ID', 'redirectUri' => 'https://api.miapp.com/auth/linkedin/callback', // lo ve LinkedIn 'callbackUri' => 'miapp://callback', // donde vuelve la app ]); } #[On(AuthSessionCompleted::class)] public function completed(string $url): void { try { $result = SocialLogin::complete($url); // El código no le sirve a la app: tu backend lo cambia por el perfil. $profile = Http::post('https://api.miapp.com/auth/linkedin/exchange', $result->forBackend()) ->json('profile'); } catch (AuthException $e) { $this->error = "{$e->authCode}: {$e->getMessage()}"; } } #[On(AuthSessionFailed::class)] public function failed(string $code, string $message = ''): void { $error = SocialLogin::fail($code, $message); // CANCELLED si el usuario cerró el navegador $this->error = "{$error->authCode}: {$error->getMessage()}"; } }
Con Livewire (vistas web) es igual, con #[OnNative(AuthSessionCompleted::class)].
Proveedores
| Proveedor | Configuración | Canje del código |
|---|---|---|
SocialLogin::linkedin() |
Backend (secret) | |
| X | SocialLogin::x() |
En el dispositivo: 'exchangeCode' => true (PKCE) |
| Mercado Libre | SocialLogin::mercadolibre('MX') |
Backend (secret + PKCE) |
| Twitch | SocialLogin::twitch() |
Backend (secret, verifica nonce) |
| GitHub, Discord | SocialLogin::preset('github') |
Backend (secret + PKCE) |
| Slack | SocialLogin::preset('slack') |
Backend (secret, verifica nonce) |
| Strava | SocialLogin::preset('strava') |
Backend (secret) |
| Telegram | SocialLogin::telegram() |
Backend (secret + PKCE) |
| TikTok | SocialLogin::tiktok() |
Backend (client key + secret) |
Cada uno acepta overrides: SocialLogin::linkedin(['extraAuthParams' => ['prompt' => 'login']]), o los endpoints de un servidor de pruebas. Las constantes de cada clase en Franciscodlxdev\SocialLogin\Providers (LinkedIn::TOKEN_ENDPOINT, Twitch::JWKS_URI, …) sirven para tu backend, y los mapProfile normalizan el perfil.
Para otro proveedor, crea un ProviderConfig:
use Franciscodlxdev\SocialLogin\ProviderConfig; $provider = new ProviderConfig( id: 'mi-idp', authorizationEndpoint: 'https://idp.example.com/authorize', defaultScopes: ['openid', 'profile', 'email'], tokenEndpoint: 'https://idp.example.com/token', // solo si admite clientes públicos userInfoEndpoint: 'https://idp.example.com/userinfo', issuer: 'https://idp.example.com', useNonce: true, );
Opciones de signIn
| Opción | Para qué |
|---|---|
clientId, redirectUri |
Obligatorias |
callbackUri |
URL de la app cuando redirectUri es una página de tu backend que reenvía (proveedores que solo aceptan https) |
scopes, extraParams |
Sustituyen los scopes por defecto / agregan parámetros |
prefersEphemeralSession |
No comparte cookies con el navegador; en iOS además evita el aviso de confirmación |
exchangeCode |
Canje en el dispositivo como cliente público: complete() trae tokens y profile |
SignInResult trae code, codeVerifier, nonce, redirectUri, params y, con exchangeCode, accessToken, refreshToken, idToken, idTokenClaims y profile. forBackend() arma el cuerpo para tu backend.
Desde JavaScript (Inertia, vistas web) solo abres y cierras el navegador con resources/js/socialLogin.js. El estado, PKCE y nonce viven en PHP, así que el flujo completo se hace con la facade.
Errores normalizados
AuthException con $e->authCode en CANCELLED | NETWORK | INVALID_CONFIG | PROVIDER_ERROR | NOT_SUPPORTED, y providerError, providerErrorDescription y status cuando el proveedor respondió.
Seguridad
- No hay
client_secreten la app. PKCE (S256),stateynoncesalen derandom_bytes()en el dispositivo. - Las solicitudes pendientes se guardan como JSON, nunca serializadas, y expiran en 10 minutos (
SOCIAL_LOGIN_PENDING_TTL). - En Android solo se acepta el redirect del inicio de sesión en curso (mismo esquema, host y ruta).
- El
id_tokense decodifica sin verificar la firma; verifícala en tu backend. - La librería no guarda tokens. Usa
Native\Mobile\Facades\SecureStorage.
Probar sin credenciales
examples/demo corre todos los proveedores contra tools/mock-idp y los backends de tools/. Ver CONTRIBUTING.md.
Licencia
MIT