Provider OAuth2 generici

Introduzione

Il plugin di accesso sociale Capgo include un motore OAuth2 e OpenID Connect integrato. Puoi utilizzarlo per connetterti a 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 selezionare uno al momento del login con providerId.

Cosa ti serve

Prima di configurare un provider, raccogli:

• Il tuo ID del 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 issuerUrl per la scoperta OIDC
• I percorsi che il tuo app richiede, come openid profile email

Configurazione di provider multipli

Usa SocialLogin.initialize() una 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 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 dell'exchange di token
• additionalResourceHeaders per intestazioni personalizzate degli endpoint di risorsa
• additionalLogoutParameters e postLogoutRedirectUrl per flussi di disconnessione
• loginHint, prompt, e 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',
    },
  },
});

ID dei provider dei presetti supportati:

• auth0
• azure
• cognito
• okta
• onelogin

Se un provider richiede endpoint personalizzati, puoi sovrascriverli nel presetto o bypassare i presetti e configurare il provider direttamente in oauth2.

Opzioni di configurazione

Opzione	Tipo	Richiesto	Descrizione
appId / clientId	stringa	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	stringa	No	Informazioni dell'utente o endpoint dei risorse
logoutUrl / endSessionEndpoint	stringa	No	URL di logout o fine sessione
postLogoutRedirectUrl	stringa	No	URL di reindirizzamento dopo il logout
additionalParameters	Record<string, string>	No	Parametri di autenticazione aggiuntivi
additionalTokenParameters	Record<string, string>	No	Parametri di token aggiuntivi
additionalResourceHeaders	Record<string, string>	No	Parametri di intestazione aggiuntivi per resourceUrl
additionalLogoutParameters	Record<string, string>	No	Parametri di logout aggiuntivi
loginHint	stringa	No	Attenzione per additionalParameters.login_hint
prompt	stringa	No	Scorciatoia per additionalParameters.prompt
iosPrefersEphemeralSession	booleano	No	Preferire una sessione del browser temporanea su iOS
logsEnabled	booleano	No	Abilitare la registrazione di debug verboso

authorizationBaseUrl e accessTokenEndpoint sono facoltativi solo quando issuerUrl è sufficiente per la scoperta. I endpoint espliciti sempre vincono sui valori scoperti.

Utilizzare l'accesso 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 schermo intero al posto 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);
}

Stato di accesso e disconnessione

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

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

Rinnova i 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 token di rinnovo memorizzato dal plugin. refreshToken() ti consente di passare un token di rinnovo da te e 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

GitHub esempio

Usa GitHub quando desideri un flusso di autenticazione 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 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 è una buona scelta quando hai bisogno di OIDC più un pubblico personalizzato API:

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 nuovamente sulla pagina di callback:

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 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 di accesso token o null
idToken	Token ID OIDC se il provider ne ha restituito uno
refreshToken	Token di refresh se i permessi richiesti lo consentivano
resourceData	JSON raw recuperato da resourceUrl
scope	Permessi concesi
tokenType	Soltanto 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 callback 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 / ID Microsoft Entra

1. Registra un'app Accedi al Portale di Azure, apri App registrationse crea un registro di app nativa o mobile.

2. Aggiungi l'URI di reindirizzamento Aggiungi un URI di reindirizzamento mobile o desktop che corrisponde all'URL di callback dell'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 con l'ID tenant se la tua app è single-tenant. common Auth0

Sezione intitolata “Auth0”

1. Crea un'applicazione nativa Apri il Pannello di controllo Auth0 e crea un'applicazione 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 OIDC nativa Nel Console di amministrazione Okta, crea un'applicazione OIDC nativa.

2. Aggiungi l'URI di reindirizzamento Registra l'URL di callback esatto utilizzato dal tuo 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 token.

Nota specifica per piattaforma

iOS

• Il plugin utilizza ASWebAuthenticationSession.
• Impostato iosPrefersEphemeralSession: true Se desideri una sessione di navigazione privata senza cookie condivisi.

Android

• I redirect OAuth tornano 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 ha bisogno di un diverso modello di redirect.

Web

• Sezione intitolata “Web”
• Il flusso di reindirizzamento è migliore quando il provider blocca i pop-up o le tue regole di autenticazione richiedono la navigazione a livello di top.
• Alcuni provider bloccano l'intercambio di token del browser diretto con CORS. In questi casi, utilizza un intercambio di backend o una configurazione del provider che consente ai clienti pubblici.

Pratiche di sicurezza migliori

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. Valuta i token sul tuo backend Decodifica e verifica l'emittente, l'audience, la scadenza e la firma sul server.

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

5. Usare HTTPS in ogni punto I punti di accesso di autenticazione e di logout nella produzione dovrebbero sempre utilizzare HTTPS.

Risoluzione dei 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

Chiamata SocialLogin.initialize() prima dell'accesso e assicurati che providerId corrisponde alla chiave dell'oggetto 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.
• Tieni d'occhio gli slash finali, le disuguaglianze di schema e gli host diversi.
• Assicurati che gli schemi di URL delle app mobili siano registrati prima di testare sul dispositivo.

Nessun token di aggiornamento restituito

La maggior parte dei provider restituisce i token di aggiornamento 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 nella configurazione del provider per esaminare gli URL generati e i dettagli di scambio di token.

Documenti correlati

• Avvio del Social Login
• Migrazione di Ionic Auth Connect

Continua da Generic OAuth2 Providers

Se stai utilizzando Generic OAuth2 Providers per pianificare l'autenticazione e i flussi di account, connettilo con Usando @capgo/capacitor-social-login per la capacità nativa in Utilizzare @capgo/capacitor-login-social, @capgo/capacitor-login-social per il dettaglio di implementazione in @capgo/capacitor-login-social, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-biometric-nativo per il dettaglio di implementazione in @capgo/capacitor-biometric-nativo, e Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.