Integración de Autenticación Mejorada

Overview

Sección titulada “Resumen” @capgo/capacitor-social-login cuando desees iniciar sesión nativamente en el dispositivo pero aún quieras que Better Auth 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:

• Token de autenticación nativa para Google, Apple y Facebook
• Autenticación mejorada OAuth genérico para proveedores como Auth0, Okta, Keycloak y servidores OIDC personalizados

¿Cuál patrón utilizar?

Usar token de mano nativa

Usar SocialLogin.login() primero, luego envíe el token devuelto a Autenticación mejorada con authClient.signIn.social() cuando utilice:

• Google
• Apple
• Facebook

Usar Autenticación mejorada OAuth genérico

Deje que Better Auth controle el flujo de redirección OAuth completo cuando utilice:

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

Mantiene la comunicación 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

Inicie configurando Better Auth con los proveedores sociales que desee 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 Apple en iOS nativo, Better Auth documenta que debe proporcionar appBundleIdentifier El token de Apple ID para audiencia coincide 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 React que ya utiliza su aplicación. El patrón de transferencia de tokens sigue siendo el mismo.

Ejemplo de Google

Esta es la integración más limpia para el inicio de sesión móvil nativo de Google:

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 ambas solicitudes de inicio de sesión nativas 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

Better Auth documents two Facebook handoff modes:

• Inicio de sesión limitado de iOS: pase el idToken
• flujo-de-token-de-acceso: pasa el token de acceso tanto como 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 OAuth genéricos con Better Auth

Para Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID y proveedores similares, el plugin OAuth genérico de Better Auth suele ser la opción más adecuada en lugar de pasar tokens desde SocialLogin.login({ provider: 'oauth2' }).

Servidor de Better Auth

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 Better Auth

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 OAuth genérico de Better Auth

Better Auth incluye ayudantes preconfigurados para varios proveedores. Estos son la mejor coincidencia con los ejemplos de proveedores adicionales que ve en los documentos del 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 OAuth genérica manual

GitHub no tiene una ayuda de autenticación mejorada en la página OAuth genérica, por lo que utilice la 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 Better Auth necesita el idTokenpor lo tanto google.mode: 'offline' No es el ajuste adecuado para este flujo de transferencia.

2. Reutilizar el nonce de Apple Genera una vez, envíala a la autenticación nativa de Apple, luego envía el mismo valor a Better Auth.

3. Maneja Facebook de manera diferente según la plataforma Inicia sesión limitado en iOS te da un token de ID. Otros flujos pueden proporcionarte solo un token de acceso.

4. No mezcles flujos OAuth genéricos a menos que tengas una razón Si Better Auth posee la configuración del proveedor de OAuth, que Better Auth también controle el flujo de redirecció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.

• Documentación del proveedor de Google de Better Auth
• Documentación del proveedor de Apple de Better Auth
• Better Auth Facebook provider docs
• Better Auth Generic OAuth plugin docs
• Proveedores de inicio de sesión social OAuth2 y OIDC

Sigue adelante desde la integración de Better Auth

Si estás utilizando Integración de Better Auth para planificar la autenticación y los flujos de cuenta, conecta con Usando @capgo/capacitor-social-login para la capacidad nativa en Usando @capgo/capacitor-social-login, @capgo/capacitor-login-social para los detalles de implementación en @capgo/capacitor-login-social @capgo/capacitor-clave-privada para los detalles de implementación en @capgo/capacitor-clave-privada @capgo/capacitor-biometría-nativa para los detalles de implementación en @capgo/capacitor-biometría-nativa, y autenticación de dos factores para los detalles de implementación en autenticación de dos factores.