Provider OAuth2 Generici

Introduzione

Il plugin di accesso sociale Capgo include un motore 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

The configuration is multi-provider by design. You can register several providers at once and then select one at login time with oauth2 Quello che ti serve providerId.

Sezione intitolata “Quello che ti serve”

ID del client OAuth

• Un URL di reindirizzamento che corrisponde allo schema del tuo app o all'URL di callback web
• Punto di accesso all'autenticazione
• Punto di accesso per l'autorizzazione del flusso di autorizzazione __CAPGO_KEEP_0__ o un
• A token endpoint for authorization code flow, or an issuerUrl I permessi che il tuo app necessita, come
• Configurazione multi-provider 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 un alias di accessTokenEndpoint
• endSessionEndpoint come un alias di logoutUrl
• scopes come un alias di scope

Inoltre disponibile:

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

preset compatibili con Auth Connect

If you are migrating from Ionic Auth Connect and want to keep the same provider names, use 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',
    },
  },
});

Provider ID dei provider di presetto supportati:

• auth0
• azure
• cognito
• okta
• onelogin

If a provider needs custom endpoints, either override them in the preset or bypass presets and configure the provider directly in oauth2.

Opzioni di configurazione

Opzione	Tipo	Richiesto	Descrizione
appId / clientId	stringa	Sì	Identificatore del client OAuth2
issuerUrl	string	No	URL di base per la 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	stringa	No	Dati utente o endpoint risorsa
logoutUrl / endSessionEndpoint	string	No	URL di disconnessione o logout
postLogoutRedirectUrl	string	No	URL di reindirizzamento dopo logout
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	Aggiunti intestazioni per resourceUrl
additionalLogoutParameters	Record<string, string>	No	Aggiunti parametri di logout
loginHint	stringa	No	Attenzione per additionalParameters.login_hint
prompt	stringa	No	Attenzione per additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Preferisci una sessione di browser temporanea su iOS
logsEnabled	boolean	No	Abilita logging di debug dettagliato

authorizationBaseUrl e accessTokenEndpoint sono facoltative solo quando issuerUrl è sufficiente per la scoperta. I endpoint espliciti sempre hanno la precedenza sui valori scoperti.

Utilizzare l'accesso con OAuth2

Accedi

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

Flusso di reindirizzamento sul web

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

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

Sulla 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 refresh

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 aggiornamento memorizzato dal plugin. refreshToken() ti consente di passare un token di aggiornamento da te e di restituire la risposta OAuth2 fresca.

Ottenere il token di accesso corrente

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

console.log(code.accessToken);

Esempi specifici del provider

Esempio di GitHub

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 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 è una buona scelta quando hai bisogno di OIDC più un pubblico personalizzato 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',
  },
});

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

Accessi OAuth2 riusciti restituiscono:

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

Riferimento alla configurazione del provider

Sezione intitolata “GitHub”

1. Apri __CAPGO_KEEP_0__ Impostazioni dello sviluppatore GitHub e crea un nuovo App OAuth.

2. Imposta l'URL di chiamata 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',
       },
     },
   });

ID Azure AD / Microsoft Entra

1. Registra un'app Vai al Portale Azure, apri App registrations, e crea un registro di app nativa o mobile.

2. Aggiungi l'URI di reindirizzamento Aggiungi un URI di reindirizzamento mobile o desktop che corrisponde all'URL di chiamata 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 common con il tuo ID tenant se la tua app è single-tenant.

Auth0

1. Creare un'applicazione nativa Apre il Dashboard Auth0 e crea un'applicazione nativa.

2. Imposta gli URL di callback consentiti 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'applicazione OIDC nativa Nell'interfaccia di amministrazione di 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',
       },
     },
   });

Chiave della sicurezza e provider OIDC personalizzati

Se il tuo provider supporta la scoperta di 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.

Note specifiche per piattaforma

iOS

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

Android

• I redirect OAuth tornano attraverso lo schema e l'host del tuo app.
• 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 il tuo app ha bisogno di un diverso modello di redirect.

Web

• 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'acquisizione diretta di token con CORS. In quei casi, utilizza un'intercetta di backend o una configurazione del provider che consenta ai client pubblici.
• Pratiche di sicurezza migliori

Sezione intitolata “Pratiche di sicurezza migliori”

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

2. Preferisci il flusso di autorizzazione code responseType: 'code' è più sicuro del flusso implicito.

3. Verifica i token sul tuo backend Decodifica e verifica l'emittente, l'utenza, la scadenza e la firma server-side.

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

5. Usa HTTPS ovunque I punti di accesso di autenticazione e i punti di logout nella produzione dovrebbero sempre utilizzare HTTPS.

Risoluzione dei problemi

providerId is required

Tutti i metodi OAuth2 richiedono la chiave del provider configurata: __CAPGO_KEEP_0__

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

OAuth2 provider "xxx" not configured

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

Mancanza di URL di reindirizzamento

• Confronta l'URL di reindirizzamento configurato nel tuo app e nel dashboard del provider carattere per carattero.
• Attenti a slash finali, incongruenze di schema e host diversi.
• Assicurati di registrare i schemi di URL degli app mobili prima di testare sul dispositivo.

Non è stato restituito alcun token di refresh.

La maggior parte dei provider restituisce i token di refresh solo quando si richiedono ambiti come __CAPGO_KEEP_0__ o si impone esplicitamente il consenso. Consulta la politica specifica del provider. offline_access Debugging dell'interscambio di token

Sottosezione intitolata “Debugging dell'interscambio di token”

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

Sottosezione intitolata “Documentazione correlata”

• Avvio per l'accesso sociale
• Migrazione di Ionic Auth Connect

Continua dall'accesso OAuth2 Generico

Se stai utilizzando Provider di accesso OAuth2 Generico per pianificare l'autenticazione e i flussi di account, connettilo con Utilizza @capgo/capacitor-accesso-sociale per la capacità nativa in Utilizza @capgo/capacitor-accesso-sociale Utilizza @capgo/capacitor-accesso-sociale per il dettaglio di implementazione in @capgo/capacitor-accesso-sociale Utilizza @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori.