Integración de Autenticación Mejorada

Resumen

Mejor Autenticación funciona bien con @capgo/capacitor-social-login cuando deseas inicio de sesión nativo en el dispositivo pero todavía quieres que Mejor Autenticación cree y gestione la sesión en tu backend.

Esta página se centra en los dos patrones de integración que se ajustan mejor:

• Entrega de token nativa para Google, Apple y Facebook
• Mejor Autenticación OAuth genérica para proveedores como Auth0, Okta, Keycloak y servidores OIDC personalizados

¿Qué patrón utilizar

Usar token de native handoff

Usar SocialLogin.login() Primero, luego envíe el token devuelto a Better Auth con authClient.signIn.social() cuando utilice:

• Google
• Apple
• Facebook

Usar OAuth genérico de Better Auth

Usa:

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• Cualquier proveedor de OAuth2 o OIDC personalizado

Que mantiene el intercambio de sesión en el lado de Better Auth y evita duplicar la lógica de redirección entre dos sistemas.

Configuración del servidor de Better Auth

Comienza configurando Better Auth con los proveedores sociales que deseas soportar:

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL,
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID as string,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
    },
    apple: {
      clientId: process.env.APPLE_CLIENT_ID as string,
      clientSecret: process.env.APPLE_CLIENT_SECRET as string,
      appBundleIdentifier: process.env.APPLE_APP_BUNDLE_IDENTIFIER as string,
    },
    facebook: {
      clientId: process.env.FACEBOOK_CLIENT_ID as string,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET as string,
    },
  },
  trustedOrigins: ['https://appleid.apple.com'],
});

Nota

Para iOS nativo de Apple, Better Auth documenta que debe proporcionar appBundleIdentifier para que el token de ID de Apple coincida con el identificador de paquete utilizado por iOS.

Configuración del cliente Better Auth

import { createAuthClient } from 'better-auth/client';

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
});

Si utiliza React, utilice el paquete de cliente Better Auth de React que ya utiliza su aplicación. El patrón de transferencia de tokens sigue siendo el mismo.

Ejemplo de Google

Este es el camino de integración más limpio para el inicio de sesión de Google nativo móvil:

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const googleResult = await SocialLogin.login({
  provider: 'google',
  options: {
    scopes: ['profile', 'email'],
  },
});

if (googleResult.result.responseType !== 'online' || !googleResult.result.idToken) {
  throw new Error('Google online mode with idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'google',
  idToken: {
    token: googleResult.result.idToken,
    accessToken: googleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

Ejemplo de Apple

Para Apple, pase el mismo nonce a ambos solicitudes de inicio de sesión nativo y Better Auth:

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const nonce = crypto.randomUUID();

const appleResult = await SocialLogin.login({
  provider: 'apple',
  options: {
    scopes: ['email', 'name'],
    nonce,
  },
});

if (!appleResult.result.idToken) {
  throw new Error('Apple idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'apple',
  idToken: {
    token: appleResult.result.idToken,
    nonce,
    accessToken: appleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

Ejemplo de Facebook

Los documentos de Better Auth documentan dos modos de transición de Facebook:

• iOS Limited Login: pase el idToken
• Flujo de acceso-token: pase el token de acceso como ambos token y accessToken

Esto funciona con la forma de respuesta desde @capgo/capacitor-social-login:

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const facebookResult = await SocialLogin.login({
  provider: 'facebook',
  options: {
    permissions: ['email', 'public_profile'],
  },
});

const betterAuthToken = facebookResult.result.idToken
  ? {
      token: facebookResult.result.idToken,
    }
  : facebookResult.result.accessToken?.token
    ? {
        token: facebookResult.result.accessToken.token,
        accessToken: facebookResult.result.accessToken.token,
      }
    : null;

if (!betterAuthToken) {
  throw new Error('Facebook idToken or access token is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'facebook',
  idToken: betterAuthToken,
  callbackURL: '/dashboard',
});

Proveedores de OAuth genéricos con Mejor Autenticación

Para Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID y proveedores similares, el plugin de OAuth genérico de Mejor Autenticación es usualmente la mejor opción en lugar de pasar tokens desde SocialLogin.login({ provider: 'oauth2' }).

Servidor de Mejor Autenticación

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'keycloak',
          discoveryUrl: 'https://sso.example.com/realms/mobile/.well-known/openid-configuration',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
        },
      ],
    }),
  ],
});

Cliente de Mejor Autenticación

import { createAuthClient } from 'better-auth/client';
import { genericOAuthClient } from 'better-auth/client/plugins';

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
  plugins: [genericOAuthClient()],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

Ejemplos de proveedores para Mejor Autenticación OAuth genérico

Mejor Autenticación envía ayudantes preconfigurados para varios proveedores. Estos son la mejor opción para los ejemplos de proveedores adicionales que ve en los documentos de la plugin de inicio de sesión social.

Auth0

import { betterAuth } from 'better-auth';
import { auth0, genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        auth0({
          providerId: 'auth0',
          domain: 'dev-example.eu.auth0.com',
          clientId: process.env.AUTH0_CLIENT_ID as string,
          clientSecret: process.env.AUTH0_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'auth0',
  callbackURL: '/dashboard',
});

Microsoft Entra ID

import { betterAuth } from 'better-auth';
import { genericOAuth, microsoftEntraId } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        microsoftEntraId({
          providerId: 'entra',
          tenantId: 'common',
          clientId: process.env.AZURE_CLIENT_ID as string,
          clientSecret: process.env.AZURE_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'User.Read'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'entra',
  callbackURL: '/dashboard',
});

Okta

import { betterAuth } from 'better-auth';
import { genericOAuth, okta } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        okta({
          providerId: 'okta',
          issuer: 'https://dev-12345.okta.com/oauth2/default',
          clientId: process.env.OKTA_CLIENT_ID as string,
          clientSecret: process.env.OKTA_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'okta',
  callbackURL: '/dashboard',
});

Keycloak

import { betterAuth } from 'better-auth';
import { genericOAuth, keycloak } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        keycloak({
          providerId: 'keycloak',
          issuer: 'https://sso.example.com/realms/mobile',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

GitHub con configuración de OAuth genérica manual

GitHub no tiene un asistente de autenticación mejorada en la página de OAuth genérica, por lo que utilice una configuración manual:

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'github',
          clientId: process.env.GITHUB_CLIENT_ID as string,
          clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
          authorizationUrl: 'https://github.com/login/oauth/authorize',
          tokenUrl: 'https://github.com/login/oauth/access_token',
          userInfoUrl: 'https://api.github.com/user',
          scopes: ['read:user', 'user:email'],
          pkce: true,
        },
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'github',
  callbackURL: '/dashboard',
});

Notas y advertencias

1. Utilice el modo en línea de Google Necesita Better Auth los idTokenpor lo tanto google.mode: 'offline' no es el ajuste adecuado para este flujo de transferencia de mano.

2. Reutilice el nonce de Apple Generarlo una vez, enviarlo a Apple native login, luego enviar el mismo valor a Better Auth.

3. Trate a Facebook de manera diferente según la plataforma Limited Login en iOS le da un token de ID. Otros flujos pueden proporcionar solo un token de acceso.

4. No mezcle flujos OAuth generales a menos que tenga una razón Si Better Auth es dueño de la configuración del proveedor de OAuth, que Better Auth también sea dueño del flujo de redirección.

Leer más

• Documentación del proveedor de Google de Better Auth
• Documentación de proveedor de autenticación de Apple mejorada
• Documentación de proveedor de autenticación de Facebook mejorada
• Documentación del plugin de OAuth genérico de autenticación mejorada
• Proveedores de inicio de sesión social OAuth2 y OIDC

Sigue adelante desde la integración de autenticación mejorada

Si estás utilizando Integración de autenticación mejorada para planificar flujos de autenticación y cuentas, conecta Usando @capgo/capacitor-inicio-de-sesión-social para la capacidad nativa en Usando @capgo/capacitor-inicio-de-sesión-social, Usando @capgo/capacitor-inicio-de-sesión-social para el detalle de implementación en @capgo/capacitor-login-social, @capgo/capacitor-clave-llave para el detalle de implementación en @capgo/capacitor-clave-llave, @capgo/capacitor-biometría-nativa para el detalle de implementación en @capgo/capacitor-biometría-nativa, y Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores.