Integración de Autenticación mejorada

Resumen

Mejor Autenticación funciona bien con @capgo/capacitor-social-login cuando deseas iniciar sesión nativa en el dispositivo pero aún 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:

• Token de mano nativa para Google, Apple y Facebook
• Autenticación mejorada OAuth genérica 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 uses:

• Google
• Apple
• Facebook

Use 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 apoyar:

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 para que el audiencia del token de Apple ID coincida con el identificador de paquete utilizado por iOS.

Configuración del cliente de 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 de Better Auth para React que su aplicación ya utiliza. El patrón de transferencia de tokens sigue siendo el mismo.

Ejemplo de Google

Esta es la ruta de integración más limpia para el inicio de sesión nativo de Google 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 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 describen dos modos de Facebook de transferencia de mano:

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

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

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 de la extensión 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 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

1. Usar el modo en línea de Google Better Auth necesita el idTokenpor lo tanto google.mode: 'offline' no es la opción adecuada para este flujo de transferencia de mano.

2. Reutilizar el nonce de Apple Generarlo una vez, enviarlo a la autenticación nativa de Apple, luego enviar el mismo valor a Better Auth.

3. 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 proporcionarte solo un token de acceso.

4. No mezclar 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

• Documentación del proveedor de Google de Better Auth
• Documentación del proveedor de Apple de Better Auth
• Documentación del proveedor de Facebook de Better Auth
• Documentación del plugin OAuth genérico de Better Auth
• Proveedores de Social Login 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-login-social, @capgo/capacitor-login-social para el detalle de implementación en @capgo/capacitor-login-social, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-biométrica-nativa para el detalle de implementación en @capgo/capacitor-biométrica-nativa, y Autenticación de dos factores para el detalle de implementación en Autenticación de dos factores.