Provider OAuth2 Generici

Introduzione

Il plugin di accesso sociale Capgo include un motore di OAuth2 e OpenID Connect integrato. Puoi utilizzarlo per connettere qualsiasi fornitore di identità basato su standard, tra cui:

• GitHub
• Azure AD / Microsoft Entra ID
• Auth0
• Okta
• Keycloak
• Server OIDC o OAuth2 personalizzati

Il oauth2 La configurazione è multi-providers di progetto. Puoi registrare più provider contemporaneamente e poi selezionare uno al momento del login con providerId.

Cosa ti serve

Prima di configurare un provider, raccogli:

• Il tuo ID client OAuth
• Un URL di reindirizzamento che corrisponde allo schema del tuo app o all'URL di callback web
• Un endpoint di autorizzazione
• Un endpoint di token per l' autorizzazione code del flusso, o un issuerUrl per la scoperta OIDC
• Gli ambiti che il tuo app necessita, come openid profile email

Configurazione multi-provider

Usa SocialLogin.initialize() una volta durante l'avvio dell'applicazione e registra ogni provider di cui hai bisogno:

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

Scoperta OIDC e alias

Se il tuo provider espone un documento di scoperta OpenID Connect, issuerUrl è la configurazione più semplice:

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

Il plugin supporta anche gli alias OIDC e OAuth comuni:

• clientId come alias di appId
• authorizationEndpoint come alias di authorizationBaseUrl
• tokenEndpoint come alias di accessTokenEndpoint
• endSessionEndpoint come alias di logoutUrl
• scopes come alias di scope

Inoltre disponibile:

• additionalParameters per override richieste di autenticazione
• additionalTokenParameters per override di scambio di token
• additionalResourceHeaders per intestazioni di endpoint di risorse personalizzate
• additionalLogoutParameters e postLogoutRedirectUrl per flussi di logout
• loginHint, prompt, e iosPrefersEphemeralSession

preset compatibili con Auth Connect

Se stai migrando da Ionic Auth Connect e desideri mantenere gli stessi nomi di provider, utilizza 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',
    },
  },
});

ID dei provider di preset supportati:

• auth0
• azure
• cognito
• okta
• onelogin

Se un provider richiede endpoint personalizzati, si possono sovrascriverli nel preset o bypassare i preset e configurare il provider direttamente in oauth2.

Opzioni di configurazione

Opzione	Tipo	Richiesto	Descrizione
appId / clientId	stringa	Sì	Identificatore del client OAuth2
issuerUrl	string	No	URL di scoperta OIDC
authorizationBaseUrl / authorizationEndpoint	string	Sì*	URL del endpoint di autorizzazione
accessTokenEndpoint / tokenEndpoint	string	No*	URL del endpoint del token
redirectUrl	string	Sì	URL di callback
scope / scopes	string / string[]	No	Scopi richiesti
pkceEnabled	boolean	No	Predefinito a true
responseType	'code' o 'token'	No	Predefinito a 'code'
resourceUrl	string	No	Informazioni sull'utente o endpoint di risorsa
logoutUrl / endSessionEndpoint	string	No	URL di uscita o di fine sessione
postLogoutRedirectUrl	string	No	URL di reindirizzamento dopo l'uscita
additionalParameters	Record<string, string>	No	Parametri di richiesta di autenticazione aggiuntivi
additionalTokenParameters	Record<string, string>	No	Parametri di richiesta di token aggiuntivi
additionalResourceHeaders	Record<string, string>	No	Intestazioni aggiuntive per resourceUrl
additionalLogoutParameters	Record<string, string>	No	Parametri di logout aggiuntivi
loginHint	stringa	No	Scorciatoia per additionalParameters.login_hint
prompt	stringa	No	Scorciatoia per additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Preferisci sessione di browser temporanea su iOS
logsEnabled	booleano	No	Abilita registrazione di debug verboso

authorizationBaseUrl e accessTokenEndpoint sono facoltative solo quando issuerUrl è sufficiente per la scoperta. I punti finali espliciti sempre vincono sui valori scoperti.

Utilizzo del login OAuth2

Accedi

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

Flusso di reindirizzamento su web

Usa flow: 'redirect' se desideri un redirect a pagina intera al posto di un popup:

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

Nella pagina che riceve il callback, analizza il risultato di login:

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

Stato di login e logout

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

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

Token di rinfresco

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

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

refresh() utilizza il token di rinfresco memorizzato dal plugin. refreshToken() ti consente di passare un token di aggiornamento da te e restituisce la risposta OAuth2 fresca.

Ottieni il token di accesso corrente

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

console.log(code.accessToken);

Esempi specifici del provider

GitHub esempio

Usa GitHub quando desideri un flusso di app OAuth semplice e dati di profilo 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);

Esempio di Azure AD / Microsoft Entra ID

Usa Azure quando hai bisogno di dati di Microsoft Graph come il profilo dell'utente:

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

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

Se utilizzi il flusso di reindirizzamento sul web, leggi il risultato nuovamente sulla pagina di callback:

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

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

Esempio di Keycloak

Usa la scoperta quando il tuo provider pubblica /.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 della risposta OAuth2

I login OAuth2 riusciti restituiscono:

Campo	Descrizione
providerId	La chiave del provider configurata utilizzata per l'accesso
accessToken	Token di accesso payload o null
idToken	Token ID OIDC se il provider ne ha restituito uno
refreshToken	Token di refresh se i permessi richiesti glielo consentivano
resourceData	JSON di origine recuperato da resourceUrl
scope	Scopi concesso
tokenType	Di solito bearer
expiresIn	Durata del token in secondi

Riferimento alla configurazione del provider

GitHub

1. Creare un'app OAuth Apre GitHub Impostazioni dello sviluppatore e crea una nuova app OAuth.

2. Imposta l'URL di callback Utilizza l'URL di reindirizzamento del tuo app, ad esempio myapp://oauth/github.

3. Configura il 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. Registra un'app Vai al portale Azure, apri App registrationse crea una registrazione di app nativa o mobile.

2. Aggiungi l'URI di reindirizzamento Aggiungi un URI di reindirizzamento per mobile o desktop che corrisponde all'URL di callback del tuo app.

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

   Sostituisci con l'ID tenant se il tuo'applicazione è single-tenant. common Auth0

Sezione intitolata “Auth0”

1. Apri il Pannello di controllo di Auth0 e crea un'applicazione nativa. Imposta gli URL di callback consentiti

2. __CAPGO_KEEP_0__ Aggiungi l'URL di reindirizzamento esatto utilizzato dal tuo Capacitor app.

3. Configura il 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. Crea un'app nativa OIDC Nel Console di amministrazione Okta, crea un'applicazione OIDC nativa.

2. Aggiungi il tuo URI di reindirizzamento Registra l'URL di callback esatto utilizzato dal tuo app.

3. Configura il 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 e provider OIDC personalizzati

Se il tuo provider supporta la scoperta OpenID Connect, preferisci 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,
    },
  },
});

Se la scoperta non è disponibile, configura manualmente gli endpoint di autorizzazione e token.

Nota specifica della piattaforma

iOS

• Il plugin utilizza ASWebAuthenticationSession.
• Imposta iosPrefersEphemeralSession: true se desideri una sessione di navigazione privata senza cookie condivisi.

Android

• Le redirect OAuth tornano attraverso il tuo schema e host dell'applicazione.
• Assicurati che l'URL di callback del provider corrisponda esattamente alla configurazione del collegamento profondo Android.
• Il plugin gestisce già l'attività OAuth. Aggiungi solo filtri di intent personalizzati se la tua app richiede un diverso modello di redirect.

Web

• Il flusso di popup è il default e funziona bene per gli app web a pagina singola.
• Il flusso di redirect è meglio quando il provider blocca i popup o le tue regole di autenticazione richiedono la navigazione a livello di finestra.
• Alcuni provider bloccano l'intercambio di token diretto con CORS. In questi casi, utilizza un'intercettazione di backend o una configurazione del provider che consente ai client pubblici.

Pratiche di sicurezza

1. Utilizza PKCE Conserva pkceEnabled: true per i clienti pubblici.

2. Preferisci l'autenticazione code rispetto al flusso implicito. responseType: 'code' il flusso di autenticazione __CAPGO_KEEP_0__ è più sicuro del flusso implicito.

3. Verifica i token sul tuo server Decodifica e verifica l'emittente, l'audience, la scadenza e la firma sul server.

4. Memorizza i token di refresh in modo sicuro Per le app native, associa questo plugin con @capgo/capacitor-account-persistente.

5. Utilizza HTTPS in ogni momento I punti di accesso di autenticazione e di logout nella produzione dovrebbero sempre utilizzare HTTPS.

Risolvere i problemi

providerId is required

Tutti i metodi OAuth2 richiedono la chiave del provider configurata:

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

OAuth2 provider "xxx" not configured

Chiamata SocialLogin.initialize() prima dell'accesso e assicurati che providerId corrisponda alla chiave dell'oggetto sotto oauth2.

Mancanza di corrispondenza dell'URL di reindirizzamento

• Confronta l'URL di reindirizzamento configurato nel tuo'app e nel pannello del provider carattere per carattere.
• Tieni d'occhio gli slash aggiuntivi, le dissonanze di schema e gli host diversi.
• Assicurati di registrare i schemi di URL degli app mobili prima di testare su dispositivo.

No token di aggiornamento restituito

La maggior parte dei provider restituisce i token di aggiornamento solo quando richiesti scope come offline_access o esplicitamente forza il consenso. Recensisci la politica specifica del provider.

Debugging dell'interscambio di token

Abilita logsEnabled: true su la configurazione del provider per esaminare gli URL generati e i dettagli dell'interscambio di token.

Documentazione correlata

• Avvio rapido del Social Login
• Migrazione di Ionic Auth Connect

Continua da Provider OAuth2 Generici

Se stai utilizzando Provider OAuth2 Generici per pianificare l'autenticazione e le flussi di account, connettilo con Utilizzare @capgo/capacitor-login-social per la capacità nativa in Utilizzare @capgo/capacitor-social-login, @capgo/capacitor-social-login per il dettaglio di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-autenticazione-biometrica-nativa per i dettagli di implementazione in @capgo/capacitor-autenticazione-biometrica-nativa, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori.