Provider OAuth2 generici

Introduzione

Il plugin Capgo Social Login include un motore OAuth2 e OpenID Connect integrato. Puoi usarlo per connettere qualsiasi identity provider standard, tra cui:

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

Il oauth2 la configurazione è multi-provider per design. Puoi registrare più provider contemporaneamente e selezionarne uno al login con providerId.

Cosa ti serve

Prima di configurare un provider, recupera:

• Il tuo OAuth client ID
• Un redirect URL che corrisponda allo scheme della tua app o all'URL di callback web
• Un authorization endpoint
• Un token endpoint per il flusso di autorizzazione code, oppure un issuerUrl per l'OIDC discovery
• Gli scope necessari alla tua app, come openid profile email

Configurazione multi-provider

Usa SocialLogin.initialize() una sola volta all'avvio dell'app e registra ogni provider necessario:

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

Discovery OIDC e alias

Se il tuo provider espone un documento di discovery 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 i comuni alias OAuth e OIDC:

• 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 l'override delle richieste di auth
• additionalTokenParameters per l'override dello scambio token
• additionalResourceHeaders per gli header degli endpoint delle risorse
• additionalLogoutParameters e postLogoutRedirectUrl per i 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 provider, usa 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 provider preset supportati:

• auth0
• azure
• cognito
• okta
• onelogin

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

Opzioni di configurazione

Opzione	Tipo	Obbligatorio	Descrizione
appId / clientId	string	Sì	Client identifier OAuth2
issuerUrl	string	No	URL base per l'OIDC discovery
authorizationBaseUrl / authorizationEndpoint	string	Sì*	URL dell'endpoint di autorizzazione
accessTokenEndpoint / tokenEndpoint	string	No*	URL dell'endpoint del token
redirectUrl	string	Sì	URL di callback
scope / scopes	string / string[]	No	Scope richiesti
pkceEnabled	boolean	No	Predefinito su true
responseType	'code' o 'token'	No	Predefinito su 'code'
resourceUrl	string	No	Endpoint info utente o risorsa
logoutUrl / endSessionEndpoint	string	No	URL di logout o fine sessione
postLogoutRedirectUrl	string	No	URL di redirect dopo il logout
additionalParameters	Record<string, string>	No	Parametri extra per la richiesta di auth
additionalTokenParameters	Record<string, string>	No	Parametri extra per la richiesta del token
additionalResourceHeaders	Record<string, string>	No	Header extra per resourceUrl
additionalLogoutParameters	Record<string, string>	No	Parametri extra per il logout
loginHint	string	No	Scorciatoia per additionalParameters.login_hint
prompt	string	No	Scorciatoia per additionalParameters.prompt
iosPrefersEphemeralSession	boolean	No	Preferisci sessione browser effimera su iOS
logsEnabled	boolean	No	Abilita il debug logging dettagliato

authorizationBaseUrl e accessTokenEndpoint sono opzionali solo quando issuerUrl è sufficiente per il discovery. Gli endpoint espliciti hanno sempre la precedenza sui valori scoperti.

Usare il login OAuth2

Accedi

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

Flusso di redirect sul web

Usa flow: 'redirect' se vuoi un redirect a pagina intera invece di un popup:

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

Nella pagina che riceve la callback, analizza il risultato del login:

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

Stato del login e logout

const status = await SocialLogin.isLoggedIn({
  provider: 'oauth2',
  providerId: 'github',
});

await SocialLogin.logout({
  provider: 'oauth2',
  providerId: 'github',
});

Refresh token

await SocialLogin.refresh({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

const refreshed = await SocialLogin.refreshToken({
  provider: 'oauth2',
  providerId: 'github',
  refreshToken: 'existing-refresh-token',
});

refresh() utilizza il refresh token memorizzato dal plugin. refreshToken() ti permette di passare manualmente un refresh token e restituisce la nuova risposta OAuth2.

Ottieni l'access token corrente

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

Esempi specifici per provider

Esempio GitHub

Usa GitHub quando desideri un semplice flusso OAuth e i dati base del profilo:

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 Azure AD / Microsoft Entra ID

Usa Azure quando hai bisogno di dati da 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 Auth0

Auth0 è l'ideale se hai bisogno di OIDC e di una API audience personalizzata:

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 usi il redirect flow sul web, leggi il risultato nella callback page:

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

Esempio 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 discovery quando il tuo provider la 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);

Formato della risposta OAuth2

Un login OAuth2 riuscito restituisce:

Campo	Descrizione
providerId	La chiave del provider configurata per il login
accessToken	Il payload dell'access token o null
idToken	L'ID token OIDC, se restituito dal provider
refreshToken	Il refresh token, se gli scope richiesti lo consentono
resourceData	Il JSON grezzo recuperato da resourceUrl
scope	Gli scope autorizzati
tokenType	Di solito bearer
expiresIn	Durata del token in secondi

Riferimento configurazione provider

GitHub

1. Crea un'app OAuth Apri Impostazioni sviluppatore di GitHub e crea una nuova app OAuth.

2. Imposta l'URL di callback Usa l'URL di redirect della tua 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 su Azure Portal, apri App registrations, e crea una registrazione per app nativa o mobile.

2. Aggiungi la redirect URI Aggiungi una redirect URI mobile o desktop che corrisponda alla callback URL della tua app.

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 tenant ID se la tua app è single-tenant.

Auth0

1. Crea un'applicazione nativa Apri la Dashboard di Auth0 e crea un'app Native.

2. Imposta le callback URL consentite Aggiungi l'URL di redirect esatto usato dalla tua app Capacitor.

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'app nativa OIDC Nella Okta Admin Console, crea un'applicazione OIDC Native.

2. Aggiungi il tuo redirect URI Registra l'URL di callback esatto usato 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 l'OpenID Connect discovery, 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 discovery non è disponibile, configura manualmente gli endpoint di authorization e token.

Note specifiche per piattaforma

iOS

• Il plugin utilizza ASWebAuthenticationSession.
• Imposta iosPrefersEphemeralSession: true se desideri una sessione browser privata senza cookie condivisi.

Android

• I redirect OAuth tornano tramite lo scheme e l'host della tua app.
• Assicurati che la callback URL del provider corrisponda esattamente alla configurazione del deep link su Android.
• Il plugin gestisce già l'attività OAuth. Aggiungi intent filter personalizzati solo se la tua app richiede un pattern di redirect diverso.

Web

• Il flusso popup è quello predefinito e funziona bene per le single-page app.
• Il flusso redirect è preferibile se il provider blocca i popup o se le tue regole di auth richiedono una navigazione top-level.
• Alcuni provider bloccano lo scambio diretto del token nel browser tramite CORS. In questi casi, usa uno scambio lato backend o una configurazione del provider che permetta client pubblici.

Best practice di sicurezza

1. Usa PKCE Mantieni pkceEnabled: true per i client pubblici.

2. Preferisci il flusso di autorizzazione code responseType: 'code' è più sicuro del flusso implicit.

3. Valida i token sul tuo backend Decodifica e verifica issuer, audience, expiration e signature lato server.

4. Memorizza i refresh token in modo sicuro Per le app native, abbina questo plugin a @capgo/capacitor-persistent-account.

5. Usa HTTPS ovunque Gli endpoint di auth e logout in produzione devono sempre usare HTTPS.

Risoluzione 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

Chiama SocialLogin.initialize() prima del login e assicurati che il providerId corrisponda alla chiave dell'oggetto sotto oauth2.

Redirect URL non corrispondente

• Confronta la redirect URL configurata nell'app e nella dashboard del provider carattere per carattere.
• Controlla slash finali, discrepanze nello scheme e host differenti.
• Assicurati che gli URL scheme dell'app mobile siano registrati prima di testare sul dispositivo.

Nessun refresh token restituito

La maggior parte dei provider restituisce i refresh token solo se richiedi scope come offline_access o forzi esplicitamente il consenso. Controlla la policy specifica del provider.

Debug dello scambio token

Abilita logsEnabled: true sulla configurazione del provider per ispezionare gli URL generati e i dettagli del token exchange.

Documentazione correlata

• Guida rapida Social Login
• Migrazione da Ionic Auth Connect

Continua dai provider OAuth2 generici

Se stai usando Provider OAuth2 generici per pianificare i flussi di autenticazione e account, collegandolo a Utilizzo di @capgo/capacitor-social-login per la funzionalità nativa in Utilizzo di @capgo/capacitor-social-login, @capgo/capacitor-social-login per i dettagli 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 sull'implementazione dell'autenticazione a due fattori.