Proveedores de OAuth2 genéricos

Introducción

El plugin de inicio de sesión social 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
• Okta
• Keycloak
• Servidores de OAuth2 o OIDC personalizados

El oauth2 La configuración es multi-proveedor por diseño. Puedes registrar varios proveedores a la vez y luego seleccionar uno en el momento del inicio de sesión con providerId.

¿Qué necesitas

Antes de configurar un proveedor, recopila:

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

Configuración multi-proveedor

Usar SocialLogin.initialize() una vez durante el arranque de la aplicación y registrar cada proveedor que necesites:

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 OIDC y alias

Si tu proveedor expone un documento de descubrimiento OpenID Connect, 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 comunes alias de OAuth y OIDC:

• clientId como alias de appId
• authorizationEndpoint como alias de authorizationBaseUrl
• tokenEndpoint como 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 intercambio 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 proveedores de preset admitidos:

• auth0
• azure
• cognito
• okta
• onelogin

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

Opciones de configuración

Opción	Tipo	Requerido	Descripción
appId / clientId	cadena	Sí	Identificador de cliente OAuth2
issuerUrl	string	No	URL base de descubrimiento OIDC
authorizationBaseUrl / authorizationEndpoint	string	Sí*	URL del punto de autorización
accessTokenEndpoint / tokenEndpoint	string	No*	URL del punto de token
redirectUrl	string	Sí	URL de llamada de retorno
scope / scopes	string / string[]	No	Ámbitos solicitados
pkceEnabled	boolean	No	Por defecto es true
responseType	'code' o 'token'	No	Por defecto es 'code'
resourceUrl	string	No	Información del usuario o punto de conexión de recurso
logoutUrl / endSessionEndpoint	string	No	URL de salida o cierre de sesión
postLogoutRedirectUrl	string	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 salida adicionales
loginHint	cadena	No	Atajo para additionalParameters.login_hint
prompt	cadena	No	Atajo para additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Preferir sesión de navegador ephemeris 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.

Usar inicio de sesión OAuth2

Inicio de sesión

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' si deseas un redireccionamiento de página completa en lugar de un popup:

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

En la página que recibe la llamada de retorno, analiza 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() utiliza el token de actualización 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

Ejemplo de GitHub

Utiliza GitHub cuando deseas un flujo de aplicación 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);

Ejemplo de Azure AD / Microsoft Entra ID

Utilice 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);

Ejemplo de Auth0

Auth0 es una buena opción cuando necesita OIDC más un audiencia personalizada API :

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 web, lea el resultado en la página de llamada de vuelta:

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

Ejemplo de Okta

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

Los logueos OAuth2 exitosos devuelven:

Campo	Descripción
providerId	La clave del proveedor configurada utilizada para el inicio de sesión
accessToken	Payload del token de acceso o null
idToken	Si el proveedor devolvió uno, el token ID de OIDC
refreshToken	Si se permitieron los ámbitos solicitados, el token de actualización
resourceData	JSON crudo obtenido desde resourceUrl
scope	Ámbitos concedidos
tokenType	Suele ser bearer
expiresIn	Tiempo de vida del token en segundos

Referencia de configuración del proveedor

GitHub

1. Crear una aplicación OAuth Abrir GitHub Configuración de desarrollador y crear una nueva aplicación OAuth.

2. Establecer la URL de llamada Utilice la URL de redirección de su aplicación, por ejemplo myapp://oauth/github.

3. Configurar 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. Registrar una aplicación Vaya al Portal de Azure, abra App registrations, y cree una registro de aplicación nativa o móvil.

2. Agregar la URI de redirección Agregar una URI de redirección móvil o de escritorio que coincida con la URL de llamada de su aplicación.

3. Configurar el plugin

   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 Abra el Panel de control de Auth0 y cree una aplicación nativa.

2. Establecer URLs de llamada de retorno permitidas Agregue la URL de redirección exacta utilizada por su aplicación Capacitor.

3. Configurar el plugin

   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 el panel de administración de Okta, cree una aplicación nativa OIDC.

2. Agregar su URI de redirección Registrar la URL de llamada de retorno exacta utilizada por su aplicación.

3. Configurar el plugin

   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 OIDC personalizados y Keycloak

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 no está disponible el descubrimiento, configura los puntos de conexión de autorización y tokens manualmente.

Notas específicas de plataforma

iOS

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

Android

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

Web

• El 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 los popup o tus reglas de autenticación requieren navegación de nivel superior.
• Algunos proveedores bloquean el intercambio de tokens directo con CORS en el navegador. En esos casos, utiliza un intercambio de backend o una configuración de proveedor que permita clientes públicos.

Prácticas de seguridad

1. Utiliza PKCE Mantén pkceEnabled: true para clientes públicos.

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

3. Valida tokens en tu servidor Descodifica y verifica emisor, audiencia, expiración y firma en el lado del servidor.

4. Almacena tokens de refresco de manera segura Para aplicaciones nativas, paira este plugin con @capgo/capacitor-cuenta-persistent.

5. Utiliza HTTPS en todas partes Los puntos de conexión de autenticación de producción y los puntos de conexión de cierre de sesión deben utilizar siempre 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 providerId coincida con la clave del objeto bajo oauth2.

No coincidencia de URL de redirección

• Compare la URL de redirección configurada en tu aplicación y panel de control del proveedor caracter por caracter.
• Ten en cuenta las barras inclinadas, las incompatibilidades de esquema y diferentes hosts.
• Asegúrese de que los esquemas de URL de la aplicación móvil estén registrados antes de realizar pruebas en el dispositivo.

No se devolvió token de refresco

La mayoría de los proveedores solo devuelven tokens de refresco cuando solicita ámbitos como offline_access o fuerza explícitamente el consentimiento. Revisar la política específica del proveedor.

Depuración de intercambio de tokens

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

Documentación relacionada

• Getting started con inicio de sesión social
• Migración de Ionic Auth Connect

Sigue adelante desde Proveedores de OAuth2 Genericos

Si estás utilizando Proveedores de OAuth2 Genericos para planificar flujos de autenticación y cuentas, 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-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-biométrico nativo para el detalle de implementación en @capgo/capacitor-biométrico nativo, y Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores.