Proveedores de OAuth2 genéricos

Introducción

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

The configuration is multi-provider by design. You can register several providers at once and then select one at login time with oauth2 ¿Qué necesitas providerId.

Sección titulada “¿Qué necesitas”

Tu ID de cliente OAuth

• Una URL de redireccionamiento que coincida con tu esquema de aplicación o URL de llamada web
• Punto de acceso de autorización
• Punto de acceso de token para el flujo de autorización __CAPGO_KEEP_0__ o un
• A token endpoint for authorization code flow, or an issuerUrl Los ámbitos que tu aplicación necesita, como
• Configuración de varios proveedores openid profile email

Configuración de varios proveedores

Usa SocialLogin.initialize() una sola vez durante el arranque de la aplicación 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 comunes alias de OAuth y OIDC:

• clientId como alias de appId
• authorizationEndpoint como 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 intercambio de tokens
• additionalResourceHeaders para encabezados de recursos personalizados
• additionalLogoutParameters y postLogoutRedirectUrl para flujos de cierre de sesión
• loginHint, prompty iosPrefersEphemeralSession

presets compatibles con Auth Connect

If you are migrating from Ionic Auth Connect and want to keep the same provider names, use 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

If a provider needs custom endpoints, either override them in the preset or bypass presets and configure the provider directly in 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 conexión de autorización
accessTokenEndpoint / tokenEndpoint	string	No*	URL del punto de conexión de token
redirectUrl	string	Sí	URL de llamada de respaldo
scope / scopes	cadena / cadena[]	No	Ámbitos solicitados
pkceEnabled	boolean	No	Por defecto es true
responseType	'code' o 'token'	No	Por defecto es 'code'
resourceUrl	cadena	No	Información del usuario o punto final de recurso
logoutUrl / endSessionEndpoint	string	No	URL de cierre de sesión o logout
postLogoutRedirectUrl	string	No	URL de redirección después de logout
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	Preferir sesión de navegador temporal en iOS
logsEnabled	boolean	No	Habilitar depuración de registro detallado

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

Iniciar sesión con 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

Si desea una redirección de página completa en lugar de una ventana emergente: flow: 'redirect' Copiar a portapapeles

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

Copiar a portapapeles

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

Título de la sección “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',
});

Título de la sección “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 plugin. 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

Utiliza GitHub cuando quieras 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 necesitas OIDC más un público personalizado 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 redireccionamiento en web, lee 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

Inicios de sesión 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	Token ID de OIDC si el proveedor devolvió uno
refreshToken	Renueva el token si los ámbitos solicitados se permitieron
resourceData	JSON crudo obtenido desde resourceUrl
scope	Ámbitos concedidos
tokenType	Normalmente 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 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 Ir al Portal de Azure, abre App registrations, y crea una registro de aplicación nativa o móvil.

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

3. Configure 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 ID de inquilino si tu aplicación es de un solo inquilino.

Auth0

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

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

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, crea una aplicación de aplicación nativa OIDC.

2. Agregar tu URI de redirección Registrar la URL de llamada exacta utilizada por tu app.

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',
       },
     },
   });

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.

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

• Los redireccionamientos de OAuth regresan a través de su esquema y host de aplicación.
• Asegúrese 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 agregue filtros de intención personalizados si su 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 tokens directos de navegador con CORS. En esos casos, utilice un intercambio de backend o una configuración de proveedor que permita clientes públicos.
• Prácticas de seguridad recomendadas

Sección titulada “Prácticas de seguridad recomendadas”

1. Use PKCE Conservar 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. Validar tokens en tu servidor Descodificar y verificar emisor, destinatario, expiración y firma en el servidor.

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

5. Usar 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.

Resolución de problemas

providerId is required

Todos los métodos OAuth2 necesitan la clave del 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.

Error de URL de redirección

• Comparar la URL de redirección configurada en tu aplicación y panel de control del proveedor caracter por caracter.
• Ten en cuenta los slashes finales, coincidencias 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 se solicitan ámbitos como __CAPGO_KEEP_0__ o se fuerza explícitamente el consentimiento. Revisar la política específica del proveedor. offline_access Depuración de intercambio de tokens

Sección titulada “Depuración de intercambio de tokens”

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

Sección titulada “Documentación relacionada”

• Iniciación de 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 la autenticación y los flujos de cuenta, conecta con Usando @capgo/capacitor-inicio-de-sesion-social para la capacidad nativa en Usando @capgo/capacitor-inicio-de-sesion-social, @capgo/capacitor-inicio-de-sesion-social para el detalle de implementación en @capgo/capacitor-inicio-de-sesion-social, @capgo/capacitor-clave-de-entrada 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 Autenticación de dos factores.