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

La 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.

Lo que necesitas

Antes de configurar un proveedor, recolecta:

• Tu ID de cliente de OAuth
• Una URL de redireccionamiento que coincida con el esquema de tu aplicación o la URL de llamada web
• Un punto de acceso de autorización
• Un punto de acceso de token para el flujo de autorización code o un issuerUrl para el descubrimiento de 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 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 OAuth y OIDC:

• clientId As un alias de appId
• authorizationEndpoint As un alias de authorizationBaseUrl
• tokenEndpoint As un alias de accessTokenEndpoint
• endSessionEndpoint As un alias de logoutUrl
• scopes As 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

Configuraciones 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 configuración compatibles:

• auth0
• azure
• cognito
• okta
• onelogin

Si un proveedor necesita puntos finales personalizados, ya sea sobrescribirlos en la configuración predeterminada o saltar las configuraciones y configurar el proveedor directamente en oauth2.

Opciones de configuración

Opción	Tipo	Requerido	Descripción
appId / clientId	string	Sí	Identificador del cliente OAuth2
issuerUrl	string	No	URL base de descubrimiento OIDC
authorizationBaseUrl / authorizationEndpoint	Sí*	URL del punto de conexión de autorización	string
accessTokenEndpoint / tokenEndpoint	No*	URL del punto de conexión de token	OIDC discovery base URL is required for the plugin to work correctly.
redirectUrl	string	Sí	URL de llamada de retorno
scope / scopes	string / string[]	No	Ámbitos solicitados
pkceEnabled	boolean	No	Por defecto true
responseType	'code' o 'token'	No	Por defecto 'code'
resourceUrl	Información de usuario o punto de conexión de recursos	No	Punto de conexión de recursos de inicio de sesión OAuth2
logoutUrl / endSessionEndpoint	string	No	URL de cierre de sesión o fin de sesión
postLogoutRedirectUrl	string	No	URL de redirección después de cierre de sesión
additionalParameters	Record<string, string>	No	Parámetros adicionales de solicitud de autenticación
additionalTokenParameters	Record<string, string>	No	Parámetros adicionales de solicitud de token
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	boolean	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

Iniciar sesión

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

Flujo de redirección en web

Usar flow: 'redirect' Si deseas una redirección de página completa en lugar de una ventana emergente:

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

En la página que recibe la respuesta de llamada, 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() usa el token de actualización almacenado por el complemento. refreshToken() te permite pasar un token de actualización 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

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

Utiliza Azure cuando necesites 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 necesites 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 utilizas flujo de redirección en web, lee el resultado en la página de llamada:

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

Inicios de sesión OAuth2 exitosos devuelven:

Campo	Descripción
providerId	La clave de proveedor configurada utilizada para el inicio de sesión
accessToken	Payload del token de acceso o null
idToken	ID token OIDC si el proveedor lo devolvió
refreshToken	Token de refresco si los ámbitos solicitados lo permitieron
resourceData	JSON crudo recuperado de resourceUrl
scope	Ámbitos concedidos
tokenType	Normalmente bearer
expiresIn	Tiempo de vida del token en segundos

Referencia de configuración del proveedor

GitHub

1. Crea una aplicación de OAuth Abre GitHub Configuración del desarrollador y crea una nueva aplicación OAuth.

2. Establece la URL de llamada Utiliza la URL de redirección de tu aplicación, por ejemplo 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 Ve a Azure Portal, abre App registrations, y crea una registro de aplicación nativa o de móvil.

2. Agregar la URI de redirección Agregar una URI de redirección para móviles o escritorios que coincida con la URL de llamada de tu 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 Abrir el Auth0 Dashboard 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 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 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. Configura 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',
       },
     },
   });

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

Observaciones específicas de la plataforma

iOS

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

Android

• Los redireccionamientos 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 ventana emergente es el predeterminado y funciona bien para aplicaciones de una sola página.
• El flujo de redirección es mejor cuando el proveedor bloquea ventanas emergentes o tus reglas de autenticación requieren navegación de nivel superior.
• El flujo de redirección es mejor cuando el proveedor bloquea el intercambio de tokens de navegador directo con CORS. En esos casos, utiliza un intercambio de servidor o una configuración de proveedor que permita clientes públicos.

Prácticas de seguridad recomendadas

1. Usar PKCE Conservar 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 tu servidor backend Descodificar y verificar emisor, audiencia, expiración y firma en el servidor.

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

5. Use HTTPS en todas partes Los puntos de conexión de autenticación y de cierre de sesión en producción deben utilizar siempre HTTPS.

Ayuda

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.

Desacuerdo de la URL de redirección

• Compare la URL de redireccionamiento configurada en tu aplicación y en la consola del proveedor caracter por caracter.
• Ten en cuenta las barras inclinadas al final, las incompatibilidades de esquema y diferentes dominios.
• Asegúrate de que los esquemas de URL de la aplicación móvil estén registrados antes de realizar pruebas en el dispositivo.

No se devuelve un token de refresco

La mayoría de los proveedores solo devuelven tokens de refresco 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 para inspeccionar las URL generadas y los detalles del intercambio de tokens.

Documentos relacionados

• Empezar con el inicio de sesión social
• Migración a 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-inicio-de-sesión-social para la capacidad nativa en Usando @capgo/capacitor-inicio-de-sesión-social @capgo/capacitor-inicio-de-sesión-social para los detalles de implementación en @capgo/capacitor-login-social @capgo/capacitor-clave-privada para los detalles de implementación en @capgo/capacitor-clave-privada @capgo/capacitor-autenticación-biográfica-nativa para los detalles de implementación en @capgo/capacitor-autenticación-biográfica-nativa, y autenticación de dos factores para los detalles de implementación en autenticación de dos factores.