Provideri OAuth2 generici

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Introduzione

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

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
Servizi 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'autorizzazione
Punto di accesso per l'autorizzazione del flusso __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

What you need

Usa SocialLogin.initialize() una sola 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 vuoi mantenere gli stessi nomi dei 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',
    },
  },
});

Provider ID supportati per impostazioni predefinite:

auth0
azure
cognito
okta
onelogin

Se un provider richiede endpoint personalizzati, puoi sovrascriverli nelle impostazioni predefinite o saltare le impostazioni predefinite 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 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	Informazioni dell'utente o endpoint dei risorse
`logoutUrl` / `endSessionEndpoint`	__CAPGO_KEEP_0__	No	URL di logout o fine sessione
`postLogoutRedirectUrl`	__CAPGO_KEEP_0__	No	URL di reindirizzamento dopo il 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 registrazione di debug verboso

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

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

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

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 l'attuale token di accesso

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

I login 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 glielo consentivano
`resourceData`	JSON raw recuperato da `resourceUrl`
`scope`	Permessi concesi
`tokenType`	Di solito `bearer`
`expiresIn`	Durata del token in secondi

Riferimento alla configurazione del provider

Sezione intitolata “GitHub”

Apri __CAPGO_KEEP_0__ Impostazioni dello sviluppatore Impostazioni dello sviluppatore per GitHub e crea un nuovo App OAuth.
Imposta l'URL di callback Utilizza l'URL di reindirizzamento del tuo app, ad esempio myapp://oauth/github.

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

Registra un'app Vai al Portale Azure, apri App registrations, e crea una registrazione di app nativa o mobile.
Aggiungi l'URI di reindirizzamento Aggiungi un URI di reindirizzamento mobile o desktop che corrisponde all'URL di callback del tuo app.

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

Auth0

Crea un'applicazione nativa Apri il Pannello di controllo Auth0 e crea un'applicazione nativa.
Imposta gli URL di callback consentiti Aggiungi l'URL di reindirizzamento esatto utilizzato dal tuo Capacitor app.

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

Crea un'app nativa OIDC Nel Console di amministrazione Okta, crea un'applicazione nativa OIDC.
Aggiungi il tuo URI di reindirizzamento Registra l'URL di callback esatto utilizzato dal tuo app.

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 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 popup è il default e funziona bene per le app a pagina singola.
Il flusso 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 del browser con CORS. In questi casi, utilizza un'intercetta di backend o una configurazione del provider che consente ai clienti pubblici.

Pratiche di sicurezza migliori

Usa PKCE Conserva pkceEnabled: true per i clienti pubblici.
Preferisci il flusso di autorizzazione code responseType: 'code' è più sicuro del flusso implicito.
Valida i token sul tuo backend Decodifica e verifica l'emittente, l'utenza, la scadenza e la firma server-side.
Memorizza i token di refresh in modo sicuro Per le app native, associa questo plugin con @capgo/capacitor-account-persistente.
Usa HTTPS ovunque I punti di accesso di autenticazione e di logout nella produzione dovrebbero sempre utilizzare HTTPS.

Risoluzione dei problemi

`providerId is required`

Ogni metodo OAuth2 richiede 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 dashboard del provider carattere per carattero.
Guarda per eventuali slash di fine, incongruenze di schema e host diversi.
Assicurati che i schemi delle URL degli app mobili siano registrati prima di testare sul dispositivo.

Nessun token di refresh restituito

La maggior parte dei provider restituisce i token di refresh solo quando si richiedono gli ambiti come offline_access o si forza esplicitamente il consenso. Recensisci la politica specifica del provider.

Debugging dell'interscambio di token

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

Continua da Provider OAuth2 Generici

Se stai utilizzando Provider OAuth2 Generici per pianificare l'autenticazione e le flussi di account, connettilo con Utilizza @capgo/capacitor-social-login per la capacità nativa in Utilizza @capgo/capacitor-social-login, @capgo/capacitor-social-login per il dettaglio di implementazione in @capgo/capacitor-social-login, @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.

Provideri OAuth2 generici

Introduzione

Sezione intitolata “Quello che ti serve”

What you need

Scoperta OIDC e alias

preset compatibili con Auth Connect

Opzioni di configurazione

Utilizzo del login OAuth2

Login

Flusso di reindirizzamento su web

Stato di accesso e logout

Token di refresh

Ottenere l'attuale token di accesso

Esempi specifici del provider

Esempio di GitHub

Esempio di Azure AD / Microsoft Entra ID

Esempio di Auth0

Esempio di Okta

Esempio Keycloak

Forma della risposta OAuth2

Riferimento alla configurazione del provider

Sezione intitolata “GitHub”

ID Azure AD / Microsoft Entra

Auth0

Okta

Chiave della sicurezza e provider OIDC personalizzati

Note specifiche per piattaforma

iOS

Android

Web

Pratiche di sicurezza migliori

Risoluzione dei problemi

providerId is required

OAuth2 provider "xxx" not configured

Mancanza di corrispondenza dell'URL di reindirizzamento

Nessun token di refresh restituito

Debugging dell'interscambio di token

Documentazione correlata

Continua da Provider OAuth2 Generici

`providerId is required`

`OAuth2 provider "xxx" not configured`