Mejor integración de autenticación

Copie un prompt de configuración con los pasos de instalación y la guía de markdown completa para este plugin.

Resumen

Mejor Autenticación funciona bien con @capgo/capacitor-social-login cuando deseas inicio de sesión nativo en el dispositivo pero aún quieres que Mejor Autenticación cree y administre 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

¿Cuál patrón utilizar?

Utilice la transferencia de token nativa

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

Google
Apple
Facebook

Utilice Better Auth Generic OAuth

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

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

Eso 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

Comience 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'],
});

Configuración del cliente Better Auth

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

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

Si usas React, utiliza el paquete de cliente Better Auth de React que ya estás utilizando en tu 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 en móviles:

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

Los documentos de Better Auth describen dos modos de Facebook handoff:

iOS Limited Login: pase el idToken
Flujo de token de acceso: 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 Better Auth

Para Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID y proveedores similares, el plugin de OAuth genérico de Better Auth es usualmente la mejor opción que 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,
        },
      ],
    }),
  ],
});

Copiar a portapapeles

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',
});

Auth0

Para Auth0, Okta, Keycloak, __CAPGO_KEEP_0__, Microsoft Entra ID y proveedores similares, el plugin de OAuth genérico de Better Auth es usualmente la mejor opción que pasar tokens desde

Servidor de Better Auth

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 un asistente de autenticación mejorada en la página de 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

Usar modo en línea de Google Better Auth necesita idTokenno es el ajuste correcto para este flujo de transferencia de mano. google.mode: 'offline' Reutilizar el nonce de Apple
Generarlo una vez, enviarlo a la autenticación nativa de Apple, luego enviar el mismo valor a Better Auth. Tratar a Facebook de manera diferente según la plataforma
El inicio de sesión limitado en iOS te da un token de ID. Otros flujos pueden proporcionar solo un token de acceso. No mezcles flujos de OAuth genericos a menos que tengas 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

Sección titulada “Leer más”

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-iniciode sesión social para la capacidad nativa en Usando @capgo/capacitor-iniciode sesión social, @capgo/capacitor-iniciode sesión social para el detalle de implementación en @capgo/capacitor-iniciode sesión social, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, y Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores.