Fournisseurs OAuth2 génériques

Copiez un prompt de configuration avec les étapes d'installation et le guide Markdown complet pour ce plugin.

Introduction

Le plugin de connexion sociale Capgo inclut un moteur OAuth2 et OpenID Connect intégré. Vous pouvez l'utiliser pour vous connecter à tout fournisseur d'identité conforme aux normes, notamment :

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
Serveurs OAuth2 ou OIDC personnalisés

Le oauth2 La configuration est multi-fournisseur par conception. Vous pouvez enregistrer plusieurs fournisseurs à la fois et sélectionner ensuite un à l'heure du connexion avec providerId.

Ce dont vous avez besoin

Avant de configurer un fournisseur, collectez :

Votre identifiant client OAuth
Une URL de redirection qui correspond à votre schéma d'application ou à votre URL de rappel web
Un point de terminaison d'autorisation
Un point de terminaison de jeton pour la flèche d'autorisation code ou un point de terminaison pour la découverte OIDC issuerUrl What you need
Les champs d'accès dont votre application a besoin, comme openid profile email

La configuration de plusieurs fournisseurs

Utilisez SocialLogin.initialize() une seule fois lors du démarrage de l'application et enregistrez chaque fournisseur dont vous avez besoin :

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

La découverte OIDC et les alias

Si votre fournisseur expose un document de découverte OpenID Connect, issuerUrl est la configuration la plus simple :

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

Le plugin prend également en charge les alias OAuth et OIDC courants :

clientId en tant que nom de code de appId
authorizationEndpoint en tant que nom de code de authorizationBaseUrl
tokenEndpoint en tant que nom de code de accessTokenEndpoint
endSessionEndpoint en tant que nom de code de logoutUrl
scopes en tant que nom de code de scope

Disponible également :

additionalParameters pour les surcharges de requête d'authentification
additionalTokenParameters pour les surcharges d'échange de jetons
additionalResourceHeaders pour les en-têtes de ressources personnalisés
additionalLogoutParameters et postLogoutRedirectUrl pour les flux de déconnexion
loginHint, promptet iosPrefersEphemeralSession

Compatibilité avec Auth Connect

Si vous migrez de Ionic Auth Connect et que vous souhaitez conserver les mêmes noms de fournisseur, utilisez 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',
    },
  },
});

Identifiants de fournisseur pris en charge par les presets :

auth0
azure
cognito
okta
onelogin

Si un fournisseur nécessite des points de terminaison personnalisés, vous pouvez soit les surcharger dans le preset, soit les ignorer et configurer le fournisseur directement dans oauth2.

Options de configuration

Option	Type	Obligatoire	Description
`appId` / `clientId`	Identifiant du client OAuth2	Oui	Identifiant du client OAuth2
`issuerUrl`	chaîne	Non	URL de base de découverte OIDC
`authorizationBaseUrl` / `authorizationEndpoint`	chaîne	Oui*	URL du point de terminaison d'autorisation
`accessTokenEndpoint` / `tokenEndpoint`	chaîne	Non*	URL du point de terminaison d'accès à jeton
`redirectUrl`	string	Oui	Adresse de rappel
`scope` / `scopes`	chaîne / chaîne[]	Non	Scopes demandés
`pkceEnabled`	booléen	Non	Par défaut `true`
`responseType`	`'code'` ou `'token'`	Non	Par défaut `'code'`
`resourceUrl`	Informations de chaîne	Non	Point de terminaison d'informations de l'utilisateur ou de ressources
`logoutUrl` / `endSessionEndpoint`	Informations de chaîne	Non	URL de déconnexion ou de fin de session
`postLogoutRedirectUrl`	Informations de chaîne	Non	URL de redirection après déconnexion
`additionalParameters`	`Record<string, string>`	Non	Paramètres supplémentaires de requête d'authentification
`additionalTokenParameters`	`Record<string, string>`	Non	Paramètres supplémentaires pour requête de jeton
`additionalResourceHeaders`	`Record<string, string>`	Non	En-têtes supplémentaires pour `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Non	Paramètres supplémentaires pour déconnexion
`loginHint`	chaîne	Non	Raccourci pour `additionalParameters.login_hint`
`prompt`	chaîne	Non	Raccourci pour `additionalParameters.prompt`
`iosPrefersEphemeralSession`	booléen	No	Préférez une session de navigateur éphémère sur iOS
`logsEnabled`	boolean	No	Activer la journalisation de débogage détaillée

authorizationBaseUrl et accessTokenEndpoint seuls les paramètres facultatifs sont requis lorsque issuerUrl est suffisant pour la découverte. Les points de terminaison explicites l'emportent toujours sur les valeurs découvertes.

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

Flux de redirection sur le web

Utilisez flow: 'redirect' si vous souhaitez une redirection de page complète au lieu d'une fenêtre contextuelle :

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

Sur la page qui reçoit l'appel de retour, analysez le résultat de connexion :

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

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

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

Mise à jour des jetons

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

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

refresh() utilise le jeton de rafraîchissement stocké par le plugin. refreshToken() vous permet de passer un jeton de rafraîchissement vous-même et renvoie la réponse OAuth2 fraîche.

Obtenez le jeton d'accès actuel

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

console.log(code.accessToken);

Exemples spécifiques au fournisseur

GitHub exemple

Utilisez GitHub lorsque vous voulez un flux d'application OAuth simple et des données de profil de base :

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

Exemple Azure AD / Microsoft Entra ID

Utilisez Azure lorsque vous avez besoin de données Microsoft Graph telles que le profil de l'utilisateur :

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

Exemple Auth0

Auth0 est un bon choix lorsque vous avez besoin d'OIDC plus d'un auditoire personnalisé 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 vous utilisez le flux de redirection sur le web, lisez le résultat à nouveau sur la page de rappel :

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

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

Exemple Keycloak

Utilisez la découverte lorsque votre fournisseur publie /.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);

Forme de la réponse OAuth2

Les connexions OAuth2 réussies retournent :

Champ	Description
`providerId`	La clé de fournisseur configurée utilisée pour la connexion
`accessToken`	Payload de jeton d'accès ou `null`
`idToken`	ID token OIDC si le fournisseur en a retourné un
`refreshToken`	Jeton de rafraîchissement si les scopes demandés le permettaient
`resourceData`	JSON brut récupéré de `resourceUrl`
`scope`	Scopes accordés
`tokenType`	Généralement `bearer`
`expiresIn`	Durée de vie du jeton en secondes

Référence de configuration du fournisseur

GitHub

Créer une application OAuth Ouvrir GitHub Paramètres du développeur et créez une nouvelle application OAuth.
Définissez l'URL de rappel Utilisez l'URL de redirection de votre application, par exemple myapp://oauth/github.

Configurez le 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

Inscrivez-vous à l'application Allez sur le Portail Azure, ouvrez App registrations, et créez une inscription d'application native ou mobile.
Ajoutez l'URI de redirection Configurez l'URI de redirection mobile ou de bureau qui correspond à l'URL de rappel de votre application.

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

Auth0

Créez une application native Ouvrez le Auth0 Dashboard créez une application native.
Définissez les URL de rappel autorisées Ajoutez l'URL de redirection exacte utilisée par votre application Capacitor.

Configurez le 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

Créez une application native OIDC Dans le console d'administration Okta, créez une application Native OIDC.
Ajoutez votre URI de rappel Enregistrez l'URL de rappel exacte utilisée par votre application.

Configurez le 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 et fournisseurs OIDC personnalisés

Si votre fournisseur prend en charge la découverte OpenID Connect, préférez 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 la découverte n'est pas disponible, configurez les points de terminaison d'autorisation et de jeton manuellement.

Remarques spécifiques à la plateforme

iOS

Le plugin utilise ASWebAuthenticationSession.
Configurez iosPrefersEphemeralSession: true Si vous souhaitez une session de navigateur privée sans cookies partagés.

Android

Les redirections OAuth retournent par votre schéma et votre hôte d'application.
Assurez-vous que l'URL de rappel du fournisseur correspond exactement à votre configuration de lien profond Android.
Le plugin gère déjà l'activité OAuth. Ajoutez uniquement des filtres d'intent personnalisés si votre application nécessite un modèle de redirection différent.

Web

Le flux de popup est le mode par défaut et fonctionne bien pour les applications monopage.
Le flux de redirection est préférable lorsque le fournisseur bloque les popup ou que vos règles d'autorisation nécessitent une navigation de niveau supérieur.
Certains fournisseurs bloquent l'échange de jetons de navigateur direct avec CORS. Dans ces cas, utilisez un échange de backend ou une configuration du fournisseur qui permet aux clients publics.

Pratiques de sécurité recommandées

Utilisez PKCE Conservation pkceEnabled: true pour les clients publics.
Préférez le flux d'autorisation code responseType: 'code' est plus sûr que le flux implicite.
Vérifiez les jetons sur votre serveur Décodez et vérifiez l'émetteur, l'audience, la date d'expiration et la signature côté serveur.
Stockez les jetons de rafraîchissement de manière sécurisée Pour les applications natives, associez ce plugin avec @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-compte persistant @capgo/capacitor-persistent-account.
Utilisez HTTPS partout Les points de terminaison d'authentification de production et les points de terminaison de déconnexion doivent toujours utiliser HTTPS.

Résolution des problèmes

`providerId is required`

Tout méthode OAuth2 nécessite la clé de fournisseur configurée :

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

`OAuth2 provider "xxx" not configured`

Appeler SocialLogin.initialize() avant la connexion et assurez-vous que le providerId correspond à la clé de l'objet sous oauth2.

Mismatch de l'URL de redirection

Comparez l'URL de redirection configurée dans votre application et dans le tableau de bord du fournisseur caractère par caractère.
Faites attention aux slash supplémentaires, aux incohérences de schéma et aux hôtes différents.
Assurez-vous que les URL de schéma mobile soient enregistrées avant de tester sur appareil.

Aucun jeton de renouvellement retourné

La plupart des fournisseurs ne retournent des jetons de renouvellement que lorsque vous demandez des scopes comme offline_access ou que vous forcez explicitement le consentement. Vérifiez la politique spécifique du fournisseur.

Débogage de l'échange de jetons

Activer logsEnabled: true sur la configuration du fournisseur pour inspecter les URL générées et les détails de l'échange de jetons.

Continuez à partir des fournisseurs OAuth2 génériques

Si vous utilisez Fournisseurs OAuth2 génériques pour planifier l'authentification et les flux de compte, connectez-l’avec Utilisez @capgo/capacitor-connexion sociale pour la capacité native dans Utilisez @capgo/capacitor-connexion sociale @capgo/capacitor-connexion sociale pour les détails d'implémentation dans @capgo/capacitor-connexion-social, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-authentification-native-biometrique pour les détails d'implémentation dans @capgo/capacitor-authentification-native-biometrique, et Authentification à deux facteurs pour les détails d'implémentation dans Authentification à deux facteurs.

Fournisseurs OAuth2 génériques

Introduction

Ce dont vous avez besoin

La configuration de plusieurs fournisseurs

La découverte OIDC et les alias

Compatibilité avec Auth Connect

Options de configuration

Utilisation du login OAuth2

Se connecter

Flux de redirection sur le web

Statut de connexion et déconnexion

Mise à jour des jetons

Obtenez le jeton d'accès actuel

Exemples spécifiques au fournisseur

GitHub exemple

Exemple Azure AD / Microsoft Entra ID

Exemple Auth0

Exemple Okta

Exemple Keycloak

Forme de la réponse OAuth2

Référence de configuration du fournisseur

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak et fournisseurs OIDC personnalisés

Remarques spécifiques à la plateforme

iOS

Android

Web

Pratiques de sécurité recommandées

Résolution des problèmes

providerId is required

OAuth2 provider "xxx" not configured

Mismatch de l'URL de redirection

Aucun jeton de renouvellement retourné

Débogage de l'échange de jetons

Documents connexes

Continuez à partir des fournisseurs OAuth2 génériques

`providerId is required`

`OAuth2 provider "xxx" not configured`