Fournisseurs OAuth2 génériques

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

La 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 ID client OAuth
• Une URL de redirection qui correspond à votre schéma d'application ou à l'URL de rappel web
• Un point de terminaison d'autorisation
• Un point de terminaison de jeton pour le flux d'autorisation code ou un issuerUrl pour la découverte OIDC
• Les scopes dont votre application a besoin, comme openid profile email

La configuration de plusieurs fournisseurs

Utilisez SocialLogin.initialize() une seule fois pendant le 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

If 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 qu'alias de appId
• authorizationEndpoint en tant qu'alias de authorizationBaseUrl
• tokenEndpoint en tant qu'alias de accessTokenEndpoint
• endSessionEndpoint en tant qu'alias de logoutUrl
• scopes en tant qu'alias de scope

Disponible également :

• additionalParameters pour les surcharges de requête d'authentification
• additionalTokenParameters pour les surcharges d'échange de jeton
• additionalResourceHeaders pour les en-têtes d'endpoint de ressource personnalisés
• additionalLogoutParameters et postLogoutRedirectUrl pour les flux de déconnexion
• loginHint, prompt, et iosPrefersEphemeralSession

préférences compatibles 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',
    },
  },
});

Fournisseurs d'ID de préférence pris en charge :

• auth0
• azure
• cognito
• okta
• onelogin

Si un fournisseur nécessite des endpoints personnalisés, vous pouvez soit les surcharger dans la préférence, soit contourner les préférences et configurer le fournisseur directement dans oauth2.

Options de configuration

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

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

Utiliser l'authentification OAuth2

Se connecter

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 popup :

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

État de connexion et déconnexion

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

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

Rafraîchir les 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.

Obtenir 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 souhaitez 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 public API personnalisé :

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

Connexions OAuth2 réussies retournent :

Champ	Description
providerId	La clé de fournisseur configurée utilisée pour la connexion
accessToken	Charge utile du jeton d'accès ou null
idToken	Si le fournisseur a retourné un jeton ID OIDC,
refreshToken	Jeton de rafraîchissement si les étendues demandées le lui ont permis
resourceData	JSON brut récupéré depuis resourceUrl
scope	Étendues concédées
tokenType	Généralement bearer
expiresIn	Durée de vie du jeton en secondes

Référence de configuration du fournisseur

GitHub

1. Créez une application OAuth Ouvrez GitHub Paramètres du développeur et créez une nouvelle application OAuth.

2. Définissez l'URL de rappel Utilisez l'URL de redirection de votre application, par exemple myapp://oauth/github.

3. Configurez le plug-in

   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 / ID Microsoft Entra

1. Inscrivez une application Allez sur le Portail Azure, ouvrez App registrations, et créez une inscription d'application native ou mobile.

2. Ajoutez l'URI de redirection Ajoutez une URI de redirection mobile ou de bureau qui correspond à l'URL de rappel de votre application.

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

   Remarque

   Remplacez common par votre ID de locataire si votre application est multilocataire.

Auth0

1. Créer une application native Ouvrir le Tableau de bord Auth0 et créer une application Native.

2. Définir les URL de rappel autorisées Ajouter l'URL de redirection exacte utilisée par votre application Capacitor.

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

1. Créez une application native OIDC Dans le console d'administration Okta, créez une application native OIDC.

2. Ajoutez votre URI de redirection Enregistrez l'URL de rappel exacte utilisée par votre application.

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

Copiez dans le presse-papiers 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,
    },
  },
});

Remarques spécifiques à la plateforme

Si votre fournisseur prend en charge la découverte OpenID Connect, préférez la configuration automatique.

iOS

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

Android

• Les redirections OAuth retournent par votre schéma d'application et votre hôte.
• 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 la norme 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'authentification nécessitent une navigation de niveau supérieur.
• Certains fournisseurs bloquent l'échange de jetons directement dans le navigateur avec CORS. Dans ces cas, utilisez un échange backend ou une configuration de fournisseur qui permet aux clients publics.

Meilleures pratiques de sécurité

1. Utilisez PKCE Conservation pkceEnabled: true pour les clients publics.

2. Préférez le flux d'autorisation code responseType: 'code' est plus sûr que le flux implicite.

3. Validez les jetons sur votre backend Décodez et vérifiez l'émetteur, l'audience, la date d'expiration et la signature côté serveur.

4. Stockez les jetons de renouvellement de manière sécurisée. Pour les applications natives, associez ce plugin avec @capgo/capacitor-compte persistant.

5. 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 avant connexion et vous assurer que SocialLogin.initialize() correspond à la clé de l'objet sous providerId Mauvais match de l'URL de redirection oauth2.

Section intitulée “Mauvais match de l'URL de redirection”

• Faites attention aux slash finals, aux incohérences de schéma et aux hôtes différents.
• Assurez-vous que les schémas d'URL des applications mobiles sont enregistrés avant de tester sur appareil.
• Aucun jeton de rafraîchissement retourné

Section intitulée “Aucun jeton de rafraîchissement retourné”

ou que vous imposez explicitement le consentement. Vérifiez la politique spécifique au fournisseur. offline_access Most providers only return refresh tokens when you request scopes like __CAPGO_KEEP_0__ or explicitly force consent. Review the provider-specific policy.

Échange de jetons de débogage

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.

Documents connexes

• Demarrage de l'authentification par les réseaux sociaux
• Mise à niveau de l'authentification Ionic Auth Connect

Continuez de Generic OAuth2 Providers

Si vous utilisez Les fournisseurs OAuth2 génériques pour planifier l'authentification et les flux de compte, connectez-le avec Utiliser @capgo/capacitor-login-social pour la capacité native dans Utiliser @capgo/capacitor-login-social, @capgo/capacitor-login-social pour le détail d'implémentation dans @capgo/capacitor-login-social, @capgo/capacitor-passkey pour le détail d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-biométrique-native pour le détail d'implémentation dans @capgo/capacitor-biométrique-native, et L'authentification à deux facteurs pour le détail d'implémentation dans L'authentification à deux facteurs.