Provider 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 connettere qualsiasi provider di identità basato su standard, tra cui:

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

La oauth2 La configurazione è multi-providers 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:

ID del tuo 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 autorizzazione per il flusso di autorizzazione code o un punto di scoperta OIDC issuerUrl Cosa ti serve
Le autorizzazioni che il tuo app richiede, ad esempio openid profile email

Configurazione multi-providers

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 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 delle richieste di autenticazione
additionalTokenParameters per override degli scambi di token
additionalResourceHeaders per intestazioni personalizzate degli endpoint di risorsa
additionalLogoutParameters e postLogoutRedirectUrl per flussi di logout
loginHint, prompte iosPrefersEphemeralSession

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

Ilenco degli ID dei provider supportati:

auth0
azure
cognito
okta
onelogin

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

Opzioni di configurazione

Opzione	Tipo	Richiesto	Descrizione
`appId` / `clientId`	Identificatore del client OAuth2	Sì	Identificatore del client OAuth2
`issuerUrl`	stringa	No	URL di base per la scoperta OIDC
`authorizationBaseUrl` / `authorizationEndpoint`	stringa	Sì*	URL del endpoint di autorizzazione
`accessTokenEndpoint` / `tokenEndpoint`	stringa	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`	Informazioni utente o endpoint risorsa	No	Endpoint per l'accesso OAuth2
`logoutUrl` / `endSessionEndpoint`	string	No	URL di logout o fine sessione
`postLogoutRedirectUrl`	string	No	URL di reindirizzamento dopo logout
`additionalParameters`	`Record<string, string>`	string	No
`additionalTokenParameters`	`Record<string, string>`	Parametri aggiuntivi per la richiesta di autenticazione	Parametri aggiuntivi per richieste di token
`additionalResourceHeaders`	`Record<string, string>`	No	Intestazioni aggiuntive per `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	No	Parametri aggiuntivi per logout
`loginHint`	stringa	No	Attenzione per `additionalParameters.login_hint`
`prompt`	stringa	No	Attenzione per `additionalParameters.prompt`
`iosPrefersEphemeralSession`	booleano	No	Prefer sessione di browser temporanea su iOS
`logsEnabled`	boolean	No	Abilita registrazione dei log di debug dettagliati

authorizationBaseUrl e accessTokenEndpoint sono facoltativi solo quando issuerUrl è sufficiente per la scoperta. I punti finali 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 sul web

Usa flow: 'redirect' se desideri un reindirizzamento di pagina completa 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 aggiornamento

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

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

Utilizza Azure quando hai bisogno di dati del 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

Utilizza 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 dell'accesso token o `null`
`idToken`	ID token OIDC se il provider ne ha restituito uno
`refreshToken`	Token di rinfresco se i permessi richiesti glielo hanno consentito
`resourceData`	JSON raw recuperato da `resourceUrl`
`scope`	Scopi concesi
`tokenType`	Di solito `bearer`
`expiresIn`	Durata del token in secondi

Riferimento alla configurazione del provider

GitHub

Creare un'app OAuth Apri GitHub Impostazioni dello sviluppatore e crea una nuova 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',
    },
  },
});

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 per dispositivi mobili o desktop che corrisponde all'URL di callback del tuo'applicazione.

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 Apre il Dashboard Auth0 e crea un'app nativa.
Configura gli URL di callback consentiti Aggiungi l'URL di reindirizzamento esatto utilizzato dalla tua app Capacitor.

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

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.

Note specifiche per piattaforma

iOS

Il plugin utilizza ASWebAuthenticationSession.
Configura iosPrefersEphemeralSession: true Se desideri una sessione del browser privata senza cookie condivisi.

Android

Il redirect OAuth torna 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 intento 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 del token del browser con CORS. In questi casi, utilizza un'acquisizione di backend o una configurazione del provider che consenta ai clienti pubblici.

Pratiche di sicurezza

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

Risolvere i 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`

Chiamare 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 di controllo del provider carattere per carattero.
Controlla per eventuali slash finali, disaccordi di schema e host diversi.
Assicurati di registrare i schemi di URL delle app mobili prima di testare sul dispositivo.

Nessun token di refresh restituito

La maggior parte dei provider restituisce i token di refresh solo quando richiesti gli ambiti come offline_access o forza esplicitamente il consenso. Recupera 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.

Continua da Generic OAuth2 Providers

Se stai utilizzando Generic OAuth2 Providers 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 i dettagli di implementazione in @capgo/capacitor-login-social @capgo/capacitor-chiave-pass per i dettagli di implementazione in @capgo/capacitor-chiave-pass @capgo/capacitor-biometria-nativa per i dettagli di implementazione in @capgo/capacitor-biometria-nativa, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori.

Provider OAuth2 Generici

Introduzione

Cosa ti serve

Configurazione multi-providers

Scoperta OIDC e alias

Presetti compatibili con Auth Connect

Opzioni di configurazione

Utilizzo del login OAuth2

Accedi

Flusso di reindirizzamento sul web

Stato di accesso e disconnessione

Token di aggiornamento

Ottieni l'accesso token corrente

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

Keycloak e provider OIDC personalizzati

Note specifiche per piattaforma

iOS

Android

Web

Pratiche di sicurezza

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 Generic OAuth2 Providers

`providerId is required`

`OAuth2 provider "xxx" not configured`