Integración de Autenticación mejorada

Resumen

Better Auth funciona bien con @capgo/capacitor-social-login cuando desees inicio de sesión nativo 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:

• Entrega de tokens nativos para Google, Apple y Facebook
• Autenticación genérica de OAuth de Better Auth para proveedores como Auth0, Okta, Keycloak y servidores OIDC personalizados

¿Cuál patrón utilizar

Usar entrega de tokens nativos

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

• Google
• Apple
• Facebook

Use Mejor Autenticación OAuth Genérica

Deje que Mejor Autenticación 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 Mejor Autenticación y evita duplicar la lógica de redirección entre dos sistemas.

Configuración del servidor de autenticación mejorada

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 indica 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 autenticación mejorada

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

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

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

Google ejemplo

Esta es la ruta de 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 nativo y de 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 token de acceso: pasa el token de acceso tanto como token y accessToken

Funciona con la forma de respuesta de @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 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 Better Auth Generic OAuth

Better Auth incluye ayudantes preconfigurados para varios proveedores. Estos son la mejor opción para 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 de OAuth genérica manual

GitHub no tiene un asistente de autenticación mejorado 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 mezcles flujos de 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 se encargue 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 de OAuth genérico de Better Auth
• Proveedores de OAuth2 y OIDC de inicio de sesión social

Continuar desde la integración de Better Auth

Si estás utilizando Integración de Better Auth To plan autenticación y flujos de cuenta, conecte con Usando @capgo/capacitor-login-social 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 en dos factores Para el detalle de implementación en Autenticación en dos factores.