Fournisseurs OAuth2 génériques

Introduction

Le plugin Social Login de Capgo inclut un moteur OAuth2 et OpenID Connect intégré. Vous pouvez l'utiliser pour connecter n'importe quel fournisseur d'identité conforme aux standards, notamment :

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

Le oauth2 la configuration est nativement multi-fournisseur. Vous pouvez enregistrer plusieurs fournisseurs à la fois, puis en sélectionner un au moment de la connexion avec providerId.

Ce dont vous avez besoin

Avant de configurer un fournisseur, rassemblez :

• Votre ID client OAuth
• Une URL de redirection correspondant à votre schéma d’application ou à votre URL de rappel web
• Un endpoint d'autorisation
• Un endpoint de token pour le flux d'autorisation code, ou un issuerUrl pour la découverte OIDC
• Les scopes dont votre app a besoin, tels que openid profile email

Configuration multi-fournisseurs

Utiliser SocialLogin.initialize() once during app startup and register every provider you need:

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 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 comme alias de appId
• authorizationEndpoint comme alias de authorizationBaseUrl
• tokenEndpoint comme alias de accessTokenEndpoint
• endSessionEndpoint comme alias de logoutUrl
• scopes comme alias de scope

Aussi disponible :

• additionalParameters pour les overrides de requête d’authentification
• additionalTokenParameters pour les overrides d’échange de token
• additionalResourceHeaders for custom resource endpoint headers
• additionalLogoutParameters et postLogoutRedirectUrl pour les flux de déconnexion
• loginHint, prompt, et iosPrefersEphemeralSession

Presets compatibles Auth Connect

Si vous migrez depuis Ionic Auth Connect et souhaitez conserver les mêmes noms de fournisseurs, 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 fournisseurs pris en charge :

• auth0
• azure
• cognito
• okta
• onelogin

Si un fournisseur nécessite des points de terminaison personnalisés, remplacez-les dans le preset ou contournez les presets et configurez le fournisseur directement dans oauth2.

Options de configuration

Option	Type	Requis	Description
appId / clientId	string	Oui	Identifiant client OAuth2
issuerUrl	string	Non	URL de base de découverte OIDC
authorizationBaseUrl / authorizationEndpoint	string	Oui*	URL du point d'accès d'autorisation
accessTokenEndpoint / tokenEndpoint	string	Non*	URL du point d'accès de token
redirectUrl	string	Oui	URL de rappel
scope / scopes	string / string[]	Non	Scopes demandés
pkceEnabled	booléen	Non	Valeur par défaut true
responseType	'code' ou 'token'	Non	Valeur par défaut 'code'
resourceUrl	string	Non	Point de terminaison d'informations utilisateur ou de ressource
logoutUrl / endSessionEndpoint	string	Non	URL de déconnexion ou de fin de session
postLogoutRedirectUrl	string	Non	URL de redirection après déconnexion
additionalParameters	Record<string, string>	Non	Paramètres supplémentaires de la requête d'authentification
additionalTokenParameters	Record<string, string>	Non	Paramètres supplémentaires de la requête de token
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	string	Non	Raccourci pour additionalParameters.login_hint
prompt	string	Non	Raccourci pour additionalParameters.prompt
iosPrefersEphemeralSession	booléen	Non	Préférer une session de navigateur éphémère sur iOS
logsEnabled	booléen	Non	Activer les logs de debug détaillés

authorizationBaseUrl et accessTokenEndpoint ne sont optionnels que si issuerUrl suffit pour la découverte. Les endpoints explicites priment toujours sur les valeurs découvertes.

Utiliser la connexion OAuth2

Connexion

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

Utiliser flow: 'redirect' si vous voulez une redirection pleine page plutôt qu’une popup :

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

Sur la page qui reçoit le callback, parsez le résultat de la 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',
});

Tokens 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 refresh token stocké par le plugin. refreshToken() vous permet de fournir vous-même un refresh token et renvoie la réponse OAuth2 actualisée.

Récupérer le token d'accès actuel

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

console.log(code.accessToken);

Exemples par fournisseur

Exemple GitHub

Utilisez GitHub si vous voulez un flux 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, comme le profil 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 lorsqu'il vous faut OIDC et une audience API personnalisée :

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, récupérez le résultat sur la page de callback :

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

Structure de la réponse OAuth2

Les connexions OAuth2 réussies renvoient :

Champ	Description
providerId	Clé du fournisseur configurée utilisée pour la connexion
accessToken	Charge utile du token d’accès ou null
idToken	Token ID OIDC si le fournisseur en a renvoyé un
refreshToken	Token de rafraîchissement si les scopes demandés le permettaient
resourceData	JSON brut récupéré depuis resourceUrl
scope	Portées accordées
tokenType	Généralement bearer
expiresIn	Durée de vie du token en secondes

Référence de configuration du provider

GitHub

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

2. Définir l’URL de rappel Use your app redirect URL, for example 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 Accédez au portail Azure, ouvrez App registrations, et créez une inscription d’application native ou mobile.

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

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

   Remplacer common avec votre identifiant de tenant si votre application est mono-tenant.

Auth0

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

2. Définir les URL de callback autorisées Ajoutez 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éer une application native OIDC Dans la console d'administration Okta, créez une application native OIDC.

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

3. Configurer 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, privilégiez 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 manuellement les endpoints d'autorisation et de token.

Notes spécifiques à la plateforme

iOS

• Le plugin utilise ASWebAuthenticationSession.
• Définissez iosPrefersEphemeralSession: true si vous souhaitez une session de navigation privée sans cookies partagés.

Android

• Les redirections OAuth reviennent via le scheme et l'hôte de votre application.
• Assurez-vous que l'URL de callback du fournisseur correspond exactement à votre configuration de deep link Android.
• Le plugin gère déjà l'activité OAuth. N'ajoutez des intent filters personnalisés que si votre application a besoin d'un autre schéma de redirection.

Le Web

• Le flux popup est le mode par défaut et fonctionne bien pour les applications single-page.
• Le flux redirect est préférable si le fournisseur bloque les popups ou si vos règles d'auth exigent une navigation de premier niveau.
• Certains fournisseurs bloquent l'échange direct de token via le navigateur à cause de CORS. Dans ce cas, utilisez un échange via un backend ou une configuration de fournisseur autorisant les clients publics.

Bonnes pratiques de sécurité

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

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

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

4. Stockez les refresh tokens en toute sécurité Pour les apps natives, associez ce plugin à @capgo/capacitor-persistent-account.

5. Utilisez HTTPS partout Les endpoints d'authentification et de déconnexion en production doivent toujours utiliser HTTPS.

Troubleshooting

providerId is required

Chaque méthode OAuth2 nécessite la clé du fournisseur configurée :

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

OAuth2 provider "xxx" not configured

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

Incohérence de l'URL de redirection

• Comparez caractère par caractère l'URL de redirection configurée dans votre app et dans le dashboard du fournisseur.
• Attention aux slashs de fin, aux erreurs de scheme et aux différences d'hôtes.
• Assurez-vous que les URL schemes de l'app mobile sont enregistrés avant de tester sur un appareil.

Aucun refresh token retourné

La plupart des fournisseurs ne renvoient des refresh tokens que si vous demandez des scopes comme offline_access ou forcer explicitement le consentement. Consultez la politique spécifique au fournisseur.

Déboguer l'échange de token

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

Docs associées

• Démarrer avec Social Login
• Migration Ionic Auth Connect

Continuer depuis les fournisseurs OAuth2 génériques

Si vous utilisez Fournisseurs OAuth2 génériques pour planifier les flux d'authentification et de compte, le connecter à Utiliser @capgo/capacitor-social-login pour la capacité native dans Utiliser @capgo/capacitor-social-login @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login @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 Authentification à deux facteurs pour les détails d'implémentation de l'authentification à deux facteurs.