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 integrato OAuth2 e OpenID Connect. Puoi utilizzarlo per connetterti a qualsiasi provider di identità basato su standard, tra cui:

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

La oauth2 La configurazione è multi-provider di progetto. Puoi registrare diversi provider contemporaneamente e poi selezionarne 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 del flusso code 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 sola volta durante l'avvio dell'app e registra ogni provider che 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 OAuth e OIDC comuni:

clientId Section titled “Configurazione dei provider multipli” appId
authorizationEndpoint Section titled “Configurazione dei provider multipli” authorizationBaseUrl
tokenEndpoint come alias di accessTokenEndpoint
endSessionEndpoint come alias di logoutUrl
scopes come alias di scope

Disponibile anche:

additionalParameters per override delle richieste di autenticazione
additionalTokenParameters per override degli scambi di token
additionalResourceHeaders per endpoint di risorsa personalizzati
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',
    },
  },
});

ID dei provider di default supportati:

auth0
azure
cognito
okta
onelogin

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

Opzioni di configurazione

Opzione	Tipo	Risposta	Risposta
`appId` / `clientId`	Risposta	Sì	Identificatore del client OAuth2
`issuerUrl`	stringa	No	URL di base di OIDC discovery
`authorizationBaseUrl` / `authorizationEndpoint`	stringa	Sì*	URL del endpoint di autorizzazione
`accessTokenEndpoint` / `tokenEndpoint`	stringa	No*	URL del endpoint di token
`redirectUrl`	stringa	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 utente o endpoint risorsa
`logoutUrl` / `endSessionEndpoint`	stringa	No	URL di logout o fine sessione
`postLogoutRedirectUrl`	stringa	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 aggiuntivi
`loginHint`	stringa	No	Attenzione: questo campo è obbligatorio `additionalParameters.login_hint`
`prompt`	stringa	No	Attenzione: questo campo è obbligatorio `additionalParameters.prompt`
`iosPrefersEphemeralSession`	booleano	No	Preferisci una sessione del browser temporanea su iOS
`logsEnabled`	boolean	No	Abilita logging di debug verboso

authorizationBaseUrl e accessTokenEndpoint sono facoltativi solo quando issuerUrl è sufficiente per la scoperta. Gli endpoint espliciti sempre vincono 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 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 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 rinfresco memorizzato dal plugin. refreshToken() ti consente di passare un token di refresh da te e restituisce la risposta OAuth2 fresca.

Ottieni 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 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 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 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`	Rinnova il token se i permessi richiesti lo consentivano
`resourceData`	JSON raw recuperato da `resourceUrl`
`scope`	Scopi concesso
`tokenType`	Solitamente `bearer`
`expiresIn`	Durata del token in secondi

Riferimento alla configurazione del provider

GitHub

Crea un'app OAuth Apre GitHub Impostazioni dello sviluppatore e crea un nuovo App OAuth.
Imposta l'URL di callback Usa 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',
    },
  },
});

Azure AD / Microsoft Entra ID

Registra un'app Vai al Portale Azure, apri App registrationse 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

Creare un'applicazione nativa Apre il Pannello di controllo Auth0 e crea un'applicazione nativa.
Configura 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'applicazione nativa OIDC In 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 di accesso 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 vuoi una sessione di navigazione privata senza cookie condivisi.

Android

Il flusso OAuth ritorna attraverso il tuo schema e l'host dell'applicazione.
Make sure the provider callback URL exactly matches your Android deep link setup.
Il plugin gestisce già l'attività OAuth. Aggiungi solo filtri di intento personalizzati se il tuo app richiede un diverso modello di reindirizzamento.

Web

Il flusso popup è il default e funziona bene per gli app monopagina.
Il flusso redirect è meglio quando il provider blocca i popup o le tue regole di autenticazione richiedono la navigazione a livello di host.
Alcuni provider bloccano l'accesso diretto al token del browser tramite CORS. In questi casi, utilizzare un'intercetta di backend o una configurazione del provider che consenta ai clienti pubblici.

Pratiche di sicurezza migliori

Usa PKCE Tieni 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'audience, la scadenza e la firma server-side.
Rifresca i token di accesso 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.

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 il providerId corrisponda alla chiave dell'oggetto sotto oauth2.

Mancanza di URL di reindirizzamento

Confronta l'URL di reindirizzamento configurato nel tuo app e nel pannello provider carattere per carattero.
Attenti a eventuali slash finali, disaccordi di schema e host diversi.
Assicurati di registrare i schemi di URL dell'app mobile prima di testare sul dispositivo.

Nessun token di refresh restituito

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

Debugging dell'interscambio di token

Abilita logsEnabled: true per visualizzare le URL generati e i dettagli dell'interscambio di token nella configurazione del provider.

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-login con accesso sociale per il dettaglio di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-chiave di accesso per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-autenticazione-biometrica-nativa 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

Cosa ti serve

Configurazione multi-provider

Scoperta OIDC e alias

preset compatibili con Auth Connect

Opzioni di configurazione

Utilizzo del login OAuth2

Accedi

Flusso di reindirizzamento sul web

Stato di accesso e disconnessione

Token di refresh

Ottieni 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

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Chiave di accesso e provider OIDC personalizzati

Note specifiche per piattaforma

iOS

Android

Web

Pratiche di sicurezza migliori

Risolvere i problemi

providerId is required

OAuth2 provider "xxx" not configured

Mancanza di URL di reindirizzamento

Nessun token di refresh restituito

Debugging dell'interscambio di token

Documenti correlati

Continua da Provider OAuth2 Generici

`providerId is required`

`OAuth2 provider "xxx" not configured`