Proveedores de OAuth2 genéricos

Introduction

El plugin de inicio de sesión social de Capgo incluye un motor de OAuth2 y OpenID Connect integrado. Puede utilizarlo para conectarse a cualquier proveedor de identidad basado en estándares, incluyendo:

• GitHub
• Azure AD / Microsoft Entra ID
• Auth0
• Auth0
• Okta
• Servidores OAuth2 o OIDC personalizados

El oauth2 La configuración es multi-proveedor por diseño. Puede registrar varios proveedores al mismo tiempo y luego seleccionar uno en el momento del inicio de sesión con providerId.

Qué necesitas

Antes de configurar un proveedor, recolecta:

• Tu ID de cliente OAuth
• Una URL de redirección que coincida con tu esquema de aplicación o URL de llamada web
• Un punto de acceso de autorización
• Un punto de conexión de token para el flujo de autorización code. issuerUrl para el descubrimiento OIDC
• Los ámbitos que necesita tu aplicación, como openid profile email

Configuración de múltiples proveedores

Usar SocialLogin.initialize() Una vez durante el arranque de la aplicación y registre cada proveedor que necesite:

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
    auth0: {
      issuerUrl: 'https://your-tenant.auth0.com',
      appId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

Descubrimiento de OIDC y alias

Sección titulada “Descubrimiento OIDC y alias” issuerUrl es la configuración más sencilla:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

El plugin también admite alias OAuth y OIDC comunes:

• clientId como un alias de appId
• authorizationEndpoint como un alias de authorizationBaseUrl
• tokenEndpoint como un alias de accessTokenEndpoint
• endSessionEndpoint como un alias de logoutUrl
• scopes como un alias de scope

También disponible:

• additionalParameters para sobreescribir solicitudes de autenticación
• additionalTokenParameters para sobreescribir intercambios de tokens
• additionalResourceHeaders para encabezados de recursos personalizados
• additionalLogoutParameters y postLogoutRedirectUrl para flujos de cierre de sesión
• loginHint, prompt, y iosPrefersEphemeralSession

presets compatibles con Auth Connect

Si está migrando desde Ionic Auth Connect y quiere mantener los mismos nombres de proveedor, utilice SocialLoginAuthConnect.

import { SocialLoginAuthConnect } from '@capgo/capacitor-social-login';

await SocialLoginAuthConnect.initialize({
  authConnect: {
    auth0: {
      domain: 'https://your-tenant.auth0.com',
      clientId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      audience: 'https://your-api.example.com',
    },
    azure: {
      tenantId: 'common',
      clientId: 'your-azure-client-id',
      redirectUrl: 'myapp://oauth/azure',
    },
    okta: {
      issuer: 'https://dev-12345.okta.com/oauth2/default',
      clientId: 'your-okta-client-id',
      redirectUrl: 'myapp://oauth/okta',
    },
  },
});

IDs de proveedor de preset admitidos:

• auth0
• azure
• cognito
• okta
• onelogin

Si un proveedor necesita puntos finales personalizados, puede sobrescribirlos en el preset o saltarse los presets y configurar el proveedor directamente en oauth2.

Opciones de configuración

Opción	Tipo	Requerido	Descripción
appId / clientId	cadena	Sí	Identificador del cliente OAuth2
issuerUrl	cadena	No	URL base de descubrimiento OIDC
authorizationBaseUrl / authorizationEndpoint	cadena	Sí*	URL de punto de autorización
accessTokenEndpoint / tokenEndpoint	cadena	No*	URL de punto de conexión de token
redirectUrl	cadena	Sí	URL de llamada de respaldo
scope / scopes	cadena / cadena[]	No	Ámbitos solicitados
pkceEnabled	booleano	No	Por defecto true
responseType	'code' o 'token'	No	Por defecto 'code'
resourceUrl	cadena	No	Información del usuario o punto de conexión de recursos
logoutUrl / endSessionEndpoint	cadena	No	URL de cierre de sesión
postLogoutRedirectUrl	cadena	No	URL de redirección después de cerrar sesión
additionalParameters	Record<string, string>	No	Parámetros de solicitud de autenticación adicionales
additionalTokenParameters	Record<string, string>	No	Parámetros de solicitud de token adicionales
additionalResourceHeaders	Record<string, string>	No	Encabezados adicionales para resourceUrl
additionalLogoutParameters	Record<string, string>	No	Parámetros de cierre adicionales
loginHint	cadena	No	Atajo para additionalParameters.login_hint
prompt	cadena	No	Atajo para additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Prefer sesión de navegador temporal en iOS
logsEnabled	booleano	No	Habilitar depuración de registro detallado

authorizationBaseUrl y accessTokenEndpoint son solo opcionales cuando issuerUrl es suficiente para la descubierta. Los puntos finales explícitos siempre ganan sobre los valores descubiertos.

Usando inicio de sesión OAuth2

Login

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

Flujo de redireccionamiento en web

Usar flow: 'redirect' if you want a full-page redirect instead of a popup:

await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

En la página que recibe la llamada de retorno, analice el resultado de inicio de sesión:

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.providerId);
}

Estado de inicio de sesión y cierre de sesión

const status = await SocialLogin.isLoggedIn({
  provider: 'oauth2',
  providerId: 'github',
});

await SocialLogin.logout({
  provider: 'oauth2',
  providerId: 'github',
});

Tokens de actualización

await SocialLogin.refresh({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

const refreshed = await SocialLogin.refreshToken({
  provider: 'oauth2',
  providerId: 'github',
  refreshToken: 'existing-refresh-token',
});

refresh() usa el token de refresco almacenado por el complemento. refreshToken() te permite pasar un token de refresco tú mismo y devuelve la respuesta OAuth2 fresca.

Obtén el token de acceso actual

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

Ejemplos específicos del proveedor

GitHub ejemplo

Usa GitHub cuando quieras un flujo de OAuth simple y datos de perfil básicos:

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});

const githubResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

console.log(githubResult.result.accessToken?.token);
console.log(githubResult.result.resourceData);

Microsoft Azure / ID de Microsoft Entra ejemplo

Utilice Microsoft Azure cuando necesite datos de Microsoft Graph, como el perfil del usuario:

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});

const azureResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'azure',
  },
});

console.log(azureResult.result.idToken);
console.log(azureResult.result.resourceData);

Auth0 ejemplo

Auth0 is a good fit when you need OIDC plus a custom API audience:

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

const auth0Result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

Si utiliza el flujo de redirección en la web, lea el resultado en la página de llamada:

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

Okta ejemplo

await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});

const oktaResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'okta',
  },
});

console.log(oktaResult.result.resourceData);

Ejemplo de Keycloak

Usar descubrimiento cuando tu proveedor publique /.well-known/openid-configuration:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

const keycloakResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'keycloak',
  },
});

console.log(keycloakResult.result.idToken);

Forma de respuesta OAuth2

Inicios de sesión exitosos de OAuth2 devuelven:

Campo	Descripción
providerId	La clave de proveedor configurada utilizada para el inicio de sesión
accessToken	Carga del token de acceso o null
idToken	ID token OIDC si el proveedor lo devolvió
refreshToken	token de actualización si los ámbitos solicitados lo permitieron
resourceData	JSON crudo recuperado de resourceUrl
scope	ámbitos concedidos
tokenType	Suele ser bearer
expiresIn	vida útil del token en segundos

referencia de configuración del proveedor

GitHub

1. Crear una aplicación OAuth Open GitHub Configuración del Desarrollador y crea una nueva aplicación OAuth.

2. Establece la URL de llamada. Use your app redirect URL, for example myapp://oauth/github.

3. Configura el plugin

   await SocialLogin.initialize({
     oauth2: {
       github: {
         appId: 'your-github-client-id',
         authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
         accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
         redirectUrl: 'myapp://oauth/github',
         scope: 'read:user user:email',
         pkceEnabled: true,
         resourceUrl: 'https://api.github.com/user',
       },
     },
   });

Azure AD / Microsoft Entra ID

1. Registra una aplicación Registrar una aplicación App registrationsy crear una inscripción nativa o de aplicación móvil.

2. Agregar la URI de redireccionamiento Agregar un URI de redirección móvil o de escritorio que coincida con la URL de llamada de tu aplicación.

3. Configurar el complemento

   await SocialLogin.initialize({
     oauth2: {
       azure: {
         appId: 'your-azure-client-id',
         authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
         accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
         redirectUrl: 'myapp://oauth/azure',
         scope: 'openid profile email User.Read',
         pkceEnabled: true,
         resourceUrl: 'https://graph.microsoft.com/v1.0/me',
       },
     },
   });

   Nota

   Sustituir common con tu ID de inquilino si tu aplicación es de un solo inquilino.

Auth0

1. Crear una aplicación nativa Abrir el Panel de control de Auth0 y crear una aplicación nativa.

2. Establecer URLs de llamada permitidas Agregar la URL de redirección exacta utilizada por tu aplicación Capacitor.

3. Configurar el complemento

   await SocialLogin.initialize({
     oauth2: {
       auth0: {
         appId: 'your-auth0-client-id',
         authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
         accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
         redirectUrl: 'myapp://oauth/auth0',
         scope: 'openid profile email offline_access',
         pkceEnabled: true,
         additionalParameters: {
           audience: 'https://your-api.example.com',
         },
         logoutUrl: 'https://your-tenant.auth0.com/v2/logout',
       },
     },
   });

Okta

1. Crear una aplicación nativa OIDC En la consola de administración de Okta, crea una aplicación nativa OIDC.

2. Agregar tu URI de redirección Registra la URL de llamada exacta utilizada por tu aplicación.

3. Configurar el complemento

   await SocialLogin.initialize({
     oauth2: {
       okta: {
         appId: 'your-okta-client-id',
         authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
         accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
         redirectUrl: 'myapp://oauth/okta',
         scope: 'openid profile email offline_access',
         pkceEnabled: true,
         resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
       },
     },
   });

Proveedores de Keycloak y OIDC personalizados

Si su proveedor admite el descubrimiento de OpenID Connect, prefiere issuerUrl:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

Si la descubierta no está disponible, configura los puntos de conexión de autorización y token manualmente.

Notas específicas de plataforma

iOS

• El plugin utiliza ASWebAuthenticationSession.
• Set iosPrefersEphemeralSession: true Si deseas una sesión de navegador privada sin cookies compartidas.

Android

• OAuth redirects devuelven a través de tu esquema de aplicación y host.
• Asegúrate de que la URL de llamada del proveedor coincida exactamente con tu configuración de enlace profundo de Android.
• El plugin ya maneja la actividad de OAuth. Solo agrega filtros de intención personalizados si tu aplicación necesita un patrón de redirección diferente.

Web

• Flujo de popup es el predeterminado y funciona bien para aplicaciones de una sola página.
• El flujo de redirección es mejor cuando el proveedor bloquea popups o tus reglas de autenticación requieren navegación de nivel superior.
• Algunos proveedores bloquean el intercambio de tokens de navegador directo con CORS. En esos casos, utiliza un intercambio de backend o una configuración del proveedor que permita clientes públicos.

Prácticas de seguridad recomendadas

1. Utilice PKCE Mantenga pkceEnabled: true para clientes públicos.

2. Preferir el flujo de autorización code responseType: 'code' es más seguro que el flujo implícito.

3. Validar tokens en su servidor Descodifique y verifique emisor, audiencia, expiración y firma en el servidor.

4. Almacene tokens de refresco de manera segura Para aplicaciones nativas, pairé este plugin con @capgo/capacitor-cuenta-persistente.

5. Utilice HTTPS en todas partes Production auth endpoints and logout endpoints should always use HTTPS.

Solución de problemas

providerId is required

Cada método OAuth2 necesita la clave de proveedor configurada:

await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'github' },
});

OAuth2 provider "xxx" not configured

Llamar SocialLogin.initialize() antes de iniciar sesión y asegurarse de que el providerId coincida con la clave del objeto bajo oauth2.

Coincidencia de URL de redirección

• Compare el URL de redireccionamiento configurado en tu aplicación y panel de control del proveedor caracter por caracter.
• Ten cuidado con los slashes finales, incompatibilidades de esquema y diferentes dominios.
• Make sure mobile app URL schemes are registered before testing on device.

No se devuelve token de actualización.

La mayoría de los proveedores solo devuelven tokens de actualización cuando solicitas ámbitos como offline_access o fuerzas explícitamente el consentimiento. Revisa la política específica del proveedor.

Depuración del intercambio de tokens.

Habilita logsEnabled: true inspeccione los detalles de intercambio de tokens y las URL generadas en la configuración del proveedor.

Documentación relacionada

• Empezar con Social Login
• Migración de Ionic Auth Connect

Sigue adelante desde Proveedores de OAuth2 genéricos

Si estás utilizando Proveedores de OAuth2 genéricos para planificar la autenticación y los flujos de cuenta, conecta 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-clave de acceso para los detalles de implementación en @capgo/capacitor-passkey @capgo/capacitor-nativo-biometria para los detalles de implementación en @capgo/capacitor-native-biometric, y Autenticación en dos factores para los detalles de implementación en Autenticación en dos factores.