Generic OAuth2 Providers

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 provider di identità basato su standard, compresi:

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 selezionare 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 What you need
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

Disponibile anche:

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

Impostazioni di connessione 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 preset supportati:

auth0
azure
cognito
okta
onelogin

Se un provider richiede endpoint personalizzati, o sovrascrivi gli endpoint nel preset o bypassa i preset e configura il provider direttamente in oauth2.

Opzioni di configurazione

Opzione	Tipo	Richiesto	Descrizione
`appId` / `clientId`	string	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'`	Predefinito a	No `'code'`
`resourceUrl`	string	No	Endpoint per informazioni utente o risorse
`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 richiesta di autenticazione	Parametri aggiuntivi per richiesta 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 navigazione temporanea sul dispositivo iOS
`logsEnabled`	boolean	No	Abilita registrazione dei messaggi di debug dettagliati

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

Usa flow: 'redirect' se desideri un reindirizzamento a schermo intero invece di un popup:

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

Nella 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

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 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 refresh se i permessi richiesti glielo hanno consentito
`resourceData`	JSON raw recuperato da `resourceUrl`
`scope`	Permessi 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 registrations, e crea un registro 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 dell'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.
Imposta gli URL di callback consentiti Aggiungi l'URL di reindirizzamento esatto utilizzato da tua 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 In Console di amministrazione Okta, crea un'applicazione Native OIDC.
Aggiungi il tuo URI di reindirizzamento Registra l'URL di callback esatto utilizzato da 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 di 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 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 intento personalizzati se il tuo app ha bisogno di un diverso modello di redirect.

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 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 consente 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 server-side.
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 corrispondenza dell'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 diversi host.
Assicurati di aver registrato gli URL di schema per l'app mobile prima di testarla sul dispositivo.

Nessun token di refresh restituito

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

Debugging dell'interscambio di token

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

Continua da Generic OAuth2 Providers

Generic OAuth2 Providers per pianificare l'autenticazione e le flussi di account, connettilo con Utilizza @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login per la capacità nativa in Utilizza @capgo/capacitor-social-login @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.

Generic OAuth2 Providers

Introduzione

Cosa ti serve

Configurazione multi-providers

Scoperta OIDC e alias

Impostazioni di connessione 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 corrispondenza dell'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`