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. Puedes registrar varios proveedores de una sola 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 de OAuth
• Una URL de redireccionamiento que coincida con el esquema de tu aplicación o la URL de llamada de web
• Un punto de acceso de autorización
• Un punto de conexión de token para autorización del flujo code o issuerUrl para el descubrimiento OIDC
• Los ámbitos que necesita su 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 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 OIDC y alias

Si su 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 OAuth y OIDC alias:

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

Conjuntos de configuración 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 conjuntos de configuración admitidos:

• auth0
• azure
• cognito
• okta
• onelogin

Si un proveedor necesita puntos finales personalizados, ya sea sobrescribirlos en el conjunto de configuración o saltarse los conjuntos de configuración 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 del punto de autorización
accessTokenEndpoint / tokenEndpoint	cadena	No	Punto de conexión de token
redirectUrl	string	Sí	Dirección de llamada de retorno
scope / scopes	string / string[]	No	Ámbitos solicitados
pkceEnabled	boolean	No	Predeterminado a true
responseType	'code' o 'token'	No	Predeterminado a 'code'
resourceUrl	cadena	No	Información del usuario o endpoint de recurso
logoutUrl / endSessionEndpoint	cadena	No	URL de cierre de sesión o fin de sesión
postLogoutRedirectUrl	cadena	No	URL de redirección después de cierre de 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 solicitud de cierre de sesión adicionales
loginHint	string	No	Atajo para additionalParameters.login_hint
prompt	string	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.

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

Usa 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 devolución 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',
});

Actualizar 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 token de actualización almacenado por el plugin. refreshToken() te permite pasar un token de actualización tú mismo y devuelve la respuesta OAuth2 fresca.

Obtener 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

Utilice GitHub cuando desee 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);

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:

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	Carga del token de acceso o null
idToken	ID token OIDC si el proveedor devolvió uno
refreshToken	Token de actualización 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. Crear una aplicación OAuth Abrir GitHub Configuración del 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 Ir al Portal de Azure, abre App registrationsy crea una inscripción 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 tu aplicación.

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

   Sustituye 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 de vuelta 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 el Panel de administración de Okta, crear una aplicación nativa OIDC.

2. Agregar la URI de redirección Registre la URL de llamada exacta utilizada por su 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',
       },
     },
   });

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

Notas específicas de plataforma

iOS

• El complemento utiliza ASWebAuthenticationSession.
• Establecer iosPrefersEphemeralSession: true Si desea una sesión de navegador privada sin cookies compartidas.

Android

• Los redireccionamientos de OAuth regresan a través de su esquema de aplicación y host.
• Asegúrese de que la URL de llamada del proveedor coincida exactamente con la configuración de enlace profundo de Android.
• El complemento 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

• Si desea una sesión de navegador privada sin cookies compartidas.
• El flujo de redirección es mejor cuando el proveedor bloquea ventanas emergentes o sus reglas de autenticación requieren navegación de nivel superior.
• Algunos proveedores bloquean el intercambio de tokens directo con el navegador mediante CORS. En esos casos, utilice un intercambio de backend o una configuración de proveedor que permita clientes públicos.

Prácticas recomendadas de seguridad

1. Mantener para clientes públicos. pkceEnabled: true Preferir el flujo de autorización __CAPGO_KEEP_0__

2. Prefer authorization code flow responseType: 'code' Validar tokens en su servidor

3. Descodificar y verificar emisor, audiencia, expiración y firma en el servidor. Almacenar tokens de refresco de manera segura

4. Prácticas recomendadas de seguridad Para aplicaciones nativas, combine este plugin con @capgo/capacitor-cuenta persistente.

5. Utilice 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 coincide con la clave del objeto subyacente oauth2.

Diferencia en la URL de redirección

• Compara la URL de redirección configurada en tu aplicación y el panel de control del proveedor caracter por caracter.
• Ten en cuenta las barras finales, las diferencias en el esquema y los diferentes hosts.
• 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

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

Documentación relacionada

• Iniciar sesión con redes sociales
• Migración de Ionic Auth Connect

Siga adelante desde Proveedores de OAuth2 Genericos

Si está utilizando Proveedores de OAuth2 Genericos para planificar la autenticación y los flujos de cuenta, conecte con Usando @capgo/capacitor-iniciar-sesion-social para la capacidad nativa en @capgo/capacitor-login-social, @capgo/capacitor-login-social para el detalle de implementación en @capgo/capacitor-login-social, @capgo/capacitor-clave-de-entrada para el detalle de implementación en @capgo/capacitor-clave-de-entrada, @capgo/capacitor-biometría-nativa para el detalle de implementación en @capgo/capacitor-biometría-nativa, y autenticación de dos factores para el detalle de implementación en autenticación de dos factores.