Proveurs OAuth2 génériques

Introduction

Le plugin de connexion sociale Capgo comprend 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 OIDC ou OAuth2 personnalisés

The configuration is multi-provider by design. You can register several providers at once and then select one at login time with oauth2 Ce que vous avez besoin providerId.

Avant de configurer un fournisseur, collectez :

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 __CAPGO_KEEP_0__ ou un
• pour la découverte OIDC
• A token endpoint for authorization code flow, or an issuerUrl La configuration multi-fournisseur
• Section titled “What you need” openid profile email

Section intitulée « Ce que vous avez besoin »

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

Découverte OIDC et alias

Si votre fournisseur expose un document de découverte OpenID Connect, issuerUrl est le paramétrage le 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 comme un alias de appId
• authorizationEndpoint comme un alias de authorizationBaseUrl
• tokenEndpoint comme un alias de accessTokenEndpoint
• endSessionEndpoint comme un alias de logoutUrl
• scopes comme un alias de scope

Disponible également :

• additionalParameters pour les overrides de requêtes d'authentification
• additionalTokenParameters pour les overrides 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

Presets compatibles avec Auth Connect

If vous êtes en train de migrer 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 de présélection pris en charge :

• auth0
• azure
• cognito
• okta
• onelogin

Si un fournisseur nécessite des points de terminaison personnalisés, vous pouvez soit les surcharger dans la présélection, soit contourner les présélections 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
authorizationBaseUrl / authorizationEndpoint	chaîne	Oui*	URL de l'endpoint d'autorisation
accessTokenEndpoint / tokenEndpoint	chaîne	Non*	URL de l'endpoint 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 supplémentaires de requête d'authentification
additionalTokenParameters	Record<string, string>	Non	Paramètres supplémentaires de requête de jeton
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	chaîne	Non	Raccourci pour additionalParameters.prompt
iosPrefersEphemeralSession	booléen	Non	Préférence de session de navigateur éphémère sur iOS
logsEnabled	boolean	Non	Activer la journalisation de débogage détaillée

authorizationBaseUrl et accessTokenEndpoint sont facultatifs uniquement 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 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);
}

Statut de connexion et déconnexion

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

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

Jetons de rafraîchissement

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 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 d'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 d'Auth0

Auth0 is a good fit when you need OIDC plus a custom API audience:

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 la méthode de redirection sur le web, lisez le résultat sur la page de rappel :

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

Exemple d'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 logins OAuth2 réussis retournent :

Champ	Description
providerId	La clé du fournisseur configurée utilisée pour le connexion
accessToken	Charge d'accès ou null
idToken	ID token OIDC si le fournisseur en a retourné un
refreshToken	Rafraîchir le jeton si les champs demandés sont autorisés
resourceData	JSON brut récupéré depuis 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

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

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

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

1. Enregistrer une application Allez dans 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',
       },
     },
   });

   Note

   Remplacer common avec votre ID de locataire si votre application est multilocataire.

Auth0

1. Créer une application native Ouvrez le Auth0 Dashboard et créez une application Native.

2. Configurez les URL de rappel autorisées Ajoutez l'URL de redirection exacte utilisée par votre Capacitor application.

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

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

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

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.

Notes spécifiques au plateforme

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 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'autorisation nécessitent une navigation de niveau supérieur.
• Certains fournisseurs bloquent l'échange de jeton direct 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 Gardez 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. Vérifiez les jetons sur votre serveur 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 rafraîchissement 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 SocialLogin.initialize() avant la connexion et assurez-vous que providerId correspond à la clé de l'objet sous oauth2.

Erreur de correspondance de l'URL de redirection

• Comparez l'URL de redirection configurée dans votre application et le tableau de bord du fournisseur caractère par caractère.
• Vérifiez les slash de fin, les incohérences de schéma et les hôtes différents.
• Assurez-vous que les schémas d'URL des applications mobiles soient enregistrés avant de tester sur appareil.

Aucun jeton de rafraîchissement retourné

La plupart des fournisseurs ne retournent des jetons de rafraîchissement que lorsque vous demandez des scopes comme __CAPGO_KEEP_0__ ou que vous forcez explicitement le consentement. Consultez la politique spécifique au fournisseur. offline_access Débogage de l'échange de jetons

Sous-section intitulée “Débogage de l'échange de jetons”

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

Sous-section intitulée “Documents connexes”

• Authentification par connexion sociale : démarrage
• Migration vers Ionic Auth Connect

Continuez avec les fournisseurs OAuth2 génériques

Si vous utilisez Fournisseurs OAuth2 génériques pour planifier l'authentification et les flux de compte, connectez-le avec En utilisant @capgo/capacitor-authentification-par-connexion-sociale pour la capacité native dans En utilisant @capgo/capacitor-authentification-par-connexion-sociale, @capgo/capacitor-authentification-par-connexion-sociale pour le détail d'implémentation dans @capgo/capacitor-authentification-par-connexion-sociale, @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey, @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, et L'authentification à deux facteurs pour les détails d'implémentation dans L'authentification à deux facteurs.