Proveedores OAuth2 genéricos

Introducción

El plugin Social Login de Capgo incluye un motor integrado de OAuth2 y OpenID Connect. Puedes usarlo para conectar cualquier proveedor de identidad basado en estándares, como:

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

El oauth2 la configuración es multi-proveedor por diseño. Puedes registrar varios proveedores a la vez y luego seleccionar uno al iniciar sesión con providerId.

Qué necesitas

Antes de configurar un proveedor, obtén:

• Tu OAuth client ID
• Una URL de redirección que coincida con el scheme de tu app o la URL de callback web
• Un endpoint de autorización
• Un endpoint de token para el flujo de autorización code, o uno issuerUrl para el descubrimiento de OIDC
• Los scopes que necesite tu app, como openid profile email

Configuración multiproveedor

Usa SocialLogin.initialize() una vez al iniciar la app y registra 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 de 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 alias comunes de OAuth y OIDC:

• 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 overrides de peticiones de auth
• additionalTokenParameters para overrides de intercambio de tokens
• additionalResourceHeaders para headers de endpoints de recursos personalizados
• additionalLogoutParameters y postLogoutRedirectUrl para flujos de logout
• loginHint, prompt, y iosPrefersEphemeralSession

Presets compatibles con Auth Connect

Si estás migrando desde Ionic Auth Connect y quieres mantener los mismos nombres de provider, usa 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 presets de providers soportados:

• auth0
• azure
• cognito
• okta
• onelogin

Si un proveedor requiere endpoints personalizados, puedes sobrescribirlos en el preset o saltarte los presets y configurar el proveedor directamente en oauth2.

Opciones de configuración

Opción	Tipo	Obligatorio	Descripción
appId / clientId	string	Sí	Identificador de cliente OAuth2
issuerUrl	string	No	URL base de descubrimiento OIDC
authorizationBaseUrl / authorizationEndpoint	string	Sí*	URL del endpoint de autorización
accessTokenEndpoint / tokenEndpoint	string	No*	URL del endpoint de token
redirectUrl	string	Sí	URL de callback
scope / scopes	string / string[]	No	Scopes solicitados
pkceEnabled	booleano	No	Por defecto true
responseType	'code' o 'token'	No	Por defecto 'code'
resourceUrl	string	No	Endpoint de recursos o info de usuario
logoutUrl / endSessionEndpoint	string	No	URL de logout o fin de sesión
postLogoutRedirectUrl	string	No	URL de redirección tras logout
additionalParameters	Record<string, string>	No	Parámetros extra de la petición de auth
additionalTokenParameters	Record<string, string>	No	Parámetros extra de la petición de token
additionalResourceHeaders	Record<string, string>	No	Headers extra para resourceUrl
additionalLogoutParameters	Record<string, string>	No	Parámetros extra de logout
loginHint	string	No	Atajo para additionalParameters.login_hint
prompt	string	No	Atajo para additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Preferir sesión de navegador efímera en iOS
logsEnabled	booleano	No	Activar logs de depuración detallados

authorizationBaseUrl y accessTokenEndpoint solo son opcionales cuando issuerUrl es suficiente para el descubrimiento. Los endpoints explícitos siempre tienen prioridad sobre los descubiertos.

Uso de login con OAuth2

Login

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

Usa flow: 'redirect' si quieres una redirección a página completa en lugar de un popup:

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

En la página que recibe el callback, parsea el resultado del login:

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

Estado de login y logout

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

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

Refrescar tokens

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

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

refresh() usa el refresh token almacenado por el plugin. refreshToken() te permite pasar un refresh token manualmente y devuelve la respuesta OAuth2 actualizada.

Obtener el access token actual

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

console.log(code.accessToken);

Ejemplos específicos por proveedor

Ejemplo de GitHub

Usa GitHub cuando busques un flujo de OAuth sencillo 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

Usa Azure cuando necesites datos de Microsoft Graph, como el perfil de 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 con Auth0

Auth0 es ideal cuando necesitas OIDC junto con un API audience personalizado:

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 usas el flujo de redirección en web, lee el resultado en la página de callback:

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

Ejemplo con 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 con Keycloak

Usa discovery 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);

Estructura de la respuesta OAuth2

Los inicios de sesión OAuth2 exitosos devuelven:

Campo	Descripción
providerId	La clave del proveedor configurada para el login
accessToken	El payload del access token o null
idToken	El ID token de OIDC si el proveedor lo devolvió
refreshToken	El refresh token si los scopes permitieron solicitarlo
resourceData	El JSON bruto obtenido de resourceUrl
scope	Los scopes concedidos
tokenType	Normalmente bearer
expiresIn	Duración del token en segundos

Referencia de configuración del proveedor

GitHub

1. Crea una app OAuth Abrir Configuración de desarrollador de GitHub y crea una nueva app OAuth.

2. Configura la URL de callback Usa la URL de redirección de tu app, 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. Registrar una app Ve al portal de Azure y abre App registrations, y crea un registro de app nativa o móvil.

2. Añadir la URI de redirección Añade una URI de redirección móvil o de escritorio que coincida con la URL de callback de tu app.

3. Configura 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

   Reemplazar common con tu tenant ID si tu app es single-tenant.

Auth0

1. Crea una aplicación nativa Abre la Dashboard de Auth0 y crea una app Native.

2. Configura las callback URLs permitidas Añade la redirect URL exacta que usa tu app Capacitor.

3. Configura 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. Crea una app nativa OIDC En la Admin Console de Okta, crea una Native Application OIDC.

2. Añade tu URI de redirección Registra la URL de callback exacta que usa tu app.

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 tu proveedor soporta OpenID Connect discovery, es preferible 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 el discovery no está disponible, configura manualmente los endpoints de autorización y de token.

Notas específicas de la plataforma

iOS

• El plugin usa ASWebAuthenticationSession.
• Configurar iosPrefersEphemeralSession: true si quieres una sesión de navegador privada sin cookies compartidas.

Android

• Los redirects de OAuth vuelven por scheme y host de tu app.
• Asegúrate de que la URL de callback del proveedor coincida exactamente con tu configuración de deep link en Android.
• El plugin ya gestiona la actividad de OAuth. Solo añade intent filters personalizados si tu app requiere un patrón de redirección distinto.

Web

• El flujo de popup es el predeterminado y funciona bien para single-page apps.
• El flujo de redirect es mejor cuando el proveedor bloquea popups o tus reglas de auth requieren navegación de nivel superior.
• Algunos proveedores bloquean el intercambio de tokens directo en el navegador por CORS. En esos casos, usa un intercambio en el backend o una configuración de proveedor que permita clientes públicos.

Buenas prácticas de seguridad

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

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

3. Valida los tokens en tu backend Decodifica y verifica el issuer, audience, expiration y la firma en el servidor.

4. Almacena los refresh tokens de forma segura Para apps nativas, combina este plugin con @capgo/capacitor-persistent-account.

5. Usa HTTPS en todas partes Los endpoints de auth y logout en producción siempre deben usar HTTPS.

Solución de problemas

providerId is required

Cada método OAuth2 requiere la clave del proveedor configurada:

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

OAuth2 provider "xxx" not configured

Llama a SocialLogin.initialize() antes del login y asegúrate de que el providerId coincida con la clave del objeto en oauth2.

Redirect URL no coincide

• Compara la redirect URL configurada en tu app y en el dashboard del proveedor carácter por carácter.
• Presta atención a las barras finales, discrepancias en el scheme y diferentes hosts.
• Asegúrate de registrar los URL schemes de la app móvil antes de probar en un dispositivo.

No se recibió el refresh token

La mayoría de los proveedores solo devuelven refresh tokens cuando solicitas scopes como offline_access o fuerzas el consentimiento explícitamente. Revisa la política de cada proveedor.

Depuración del intercambio de tokens

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

Docs relacionadas

• Primeros pasos con Social Login
• Migración de Ionic Auth Connect

Continuar desde Generic OAuth2 Providers

Si estás usando Proveedores OAuth2 genéricos para planificar los flujos de autenticación y de cuenta, conéctalo con Uso de @capgo/capacitor-social-login para la capacidad nativa en el uso de @capgo/capacitor-social-login, @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, y Autenticación de dos factores para el detalle de implementación en la autenticación de dos factores.