Generic OAuth2 Providers

Introduzione

Il plugin di accesso sociale Capgo include un motore di autenticazione 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
• Server OAuth2 o OIDC personalizzati

La oauth2 La configurazione è multi-providers di progetto. Puoi registrare più 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 accesso per l'autorizzazione del flusso code o un punto di accesso per la scoperta OIDC issuerUrl Punto di accesso per l'autorizzazione del flusso per la scoperta OIDC
• 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 delle risorse endpoint
• additionalLogoutParameters e postLogoutRedirectUrl per flussi di logout
• loginHint, prompte iosPrefersEphemeralSession

Compatibilità 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 dei provider ID 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	Obbligatorio	Descrizione
appId / clientId	string	Sì	Identificatore del client OAuth2
issuerUrl	string	No	URL di base per la scoperta OIDC
authorizationBaseUrl / authorizationEndpoint	Sì*	URL del endpoint di autorizzazione	string
accessTokenEndpoint / tokenEndpoint	No*	URL del endpoint del token	protectedTokens
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	URL del provider OAuth2
logoutUrl / endSessionEndpoint	string	No	URL di logout o fine sessione
postLogoutRedirectUrl	string	No	URL di reindirizzamento dopo logout
additionalParameters	Record<string, string>	No	Parametri aggiuntivi per richiesta di autenticazione
additionalTokenParameters	Record<string, string>	No	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 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. Gli endpoint espliciti sempre prevalgono sui valori scoperti.

Utilizzo del login 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 invece 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);
}

Stato di accesso e disconnessione

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 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 dell'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 di 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

Il login OAuth2 riuscito restituisce:

Campo	Descrizione
providerId	La chiave del provider configurato 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	Scopi concesso
tokenType	Sono soliti bearer
expiresIn	Durata del token in secondi

Riferimento alla configurazione del provider

GitHub

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

Azure AD / Microsoft Entra ID

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

2. Aggiungi l'URI di reindirizzamento Aggiungi un URI di reindirizzamento per dispositivi mobili o desktop che corrisponde all'URL di callback del tuo'applicazione.

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. Crea un'applicazione nativa Apre il Dashboard Auth0 e crea un'app nativa.

2. Imposta gli URL di callback consentiti Aggiungi l'URL di reindirizzamento esatto utilizzato dalla tua 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 nativa OIDC In Console di amministrazione Okta, crea un'applicazione nativa OIDC.

2. Aggiungi il tuo URI di reindirizzamento Registra l'URL di callback esatto utilizzato dalla tua 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',
       },
     },
   });

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 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 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 pagina.
• 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

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 sul server.

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

5. 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 aver registrato gli schemi di URL dell'app mobile prima di testarla 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. Recensisci la politica specifica del provider.

Debugging dell'interscambio di token

Abilita logsEnabled: true per l'ispezione delle URL generate e dei dettagli dell'interscambio di token nel config del provider.

Documenti correlati

• Avvio del Social Login
• Migrazione di Ionic Auth Connect

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-rilevamento-biometrico-nativo per i dettagli di implementazione in @capgo/capacitor-rilevamento-biometrico-nativo, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori