Come accedere con Okta utilizzando Capacitor

Per accedere a Okta in un'app Capacitor, crea un'applicazione OIDC nativa Applicazione OIDC nativa in Console di amministrazione di Okta, registra un URI di reindirizzamento di accesso come com.example.app://oauth/okta, e esegui il flusso di autorizzazione code con PKCE in un browser del sistema. Con @capgo/capacitor-social-login Configura Okta una volta con il tuo fornitore e ID client, quindi chiama SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Questa guida copre l'integrazione dell'app Okta, le politiche del server di autorizzazione, il plugin code per iOS, Android e web, il rinnovo del token, il profilo utente, l'uscita, e gli errori Okta che si verificano più spesso. Si concentra su Capacitor 8 a partire da ottobre 2026.

Cosa ti serve

• Un'organizzazione Okta (Identità del Lavoro o Identità del Cliente) con accesso amministrativo per creare integrazioni di app.
• Un'app Capacitor 8.
• La tua Capacitor appIdche utilizzerai nuovamente come schema di reindirizzamento.
• Opzionalmente, un backend API che verifica i token di accesso Okta.

Come funziona il login Okta in un'app Capacitor

La tua app non mostra mai un modulo di password. Apre la pagina di accesso Okta in un browser sicuro, Okta gestisce la MFA e le politiche, quindi reindirizza nuovamente alla tua app con un code. L'app scambia il code più il verificatore PKCE per i token.

Preferisci le Custom Tabs su Android. Okta Verify, FastPass e passkeys si comportano meglio nel browser di sistema rispetto a un WebView incorporato, e i cookie SSO sono condivisi con Chrome.

Step 1: Creare l'integrazione dell'app Okta

1. In console di amministrazione Okta, vai a Applicazioni > Applicazioni > Creare integrazione dell'app.
2. Scegli OIDC - OpenID Connect e Applicazione nativa.
3. Nominalo, quindi sotto Grant type mantieni L'autorizzazione Code e seleziona Token di ricarica se gli utenti dovrebbero rimanere connessi.
4. URI di reindirizzamento di accesso: com.example.app://oauth/okta. Aggiungi https://app.example.com/auth/callback se stai distribuendo una build web.
5. URI di reindirizzamento di disconnessione: com.example.app://oauth/logout (e l'URL web se necessario).
6. Assegnazioni: scegli chi può utilizzare l'app. Gli utenti non assegnati ottengono un errore all'accesso.
7. Salva, quindi copia il ID del client. Sotto Credenziali del client, l'autenticazione del client dovrebbe essere None e Richiedi PKCE dovrebbe essere abilitato.

Okta richiede URI di reindirizzamento nativi con schema di uso privato in forma di dominio inverso. Il tuo ID bundle o ID applicazione si adatta.

Verifica il server di autorizzazione

Vai a Security > API > Serveri di autorizzazione. La maggior parte delle configurazioni utilizza il default server di autorizzazione personalizzato, emittente https://your-org.okta.com/oauth2/default.

Apri la scheda Politiche di accesso di server. Deve esserci una politica assegnata al tuo app (o Tutti i clienti) con una regola che consente il grant di autorizzazione Code e il Token di refresh Se lo utilizzi. Una regola mancante produce “Policy evaluation failed per questa richiesta”.

Origini attendibili per web

Se esegui lo stesso code sul web, aggiungi la tua origine web sotto Security > API > Origini attendibili con CORS selezionato. Senza di esso, il browser blocca la richiesta del token.

Passo 2: Installa il plugin

bun add @capgo/capacitor-social-login
bunx cap sync

Se Okta è il solo provider, disattiva i SDK social inclusi in capacitor.config.ts:

plugins: {
  SocialLogin: {
    providers: { google: false, facebook: false, apple: false, twitter: false },
  },
},

Passo 3: Aggiungi il filtro di intento Android

In android/app/src/main/AndroidManifest.xml, all'interno di MainActivity attività:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.example.app" android:host="oauth" />
</intent-filter>

MainActivity deve rimanere android:launchMode="singleTask", che è il valore predefinito di Capacitor, quindi la reindirizzamento arriva nell'attività in esecuzione.

Passo 4: Inizializza Okta

import { Capacitor } from '@capacitor/core';
import { SocialLogin } from '@capgo/capacitor-social-login';

const OKTA_ISSUER = 'https://your-org.okta.com/oauth2/default';
const isWeb = Capacitor.getPlatform() === 'web';

export async function initAuth() {
  await SocialLogin.initialize({
    oauth2: {
      okta: {
        appId: 'YOUR_OKTA_CLIENT_ID',
        authorizationBaseUrl: `${OKTA_ISSUER}/v1/authorize`,
        accessTokenEndpoint: `${OKTA_ISSUER}/v1/token`,
        resourceUrl: `${OKTA_ISSUER}/v1/userinfo`,
        redirectUrl: isWeb
          ? 'https://app.example.com/auth/callback'
          : 'com.example.app://oauth/okta',
        scope: 'openid profile email offline_access',
        pkceEnabled: true,
        logoutUrl: `${OKTA_ISSUER}/v1/logout`,
        postLogoutRedirectUrl: isWeb
          ? 'https://app.example.com/'
          : 'com.example.app://oauth/logout',
        androidUseCustomTabs: true,
      },
    },
  });
}

alternativa più breve: impostare issuerUrl: OKTA_ISSUER e cancella gli URL degli endpoint. Il plugin carica /.well-known/openid-configuration e lasciare cadere le URL degli endpoint. Il plugin carica SocialLoginAuthConnect con okta con ilissuer, clientId, redirectUrl), covered in the descritto nella.

Passo 5: Accedi e leggi il profilo

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function signInWithOkta() {
  try {
    const { result } = await SocialLogin.login({
      provider: 'oauth2',
      options: { providerId: 'okta' },
    });

    const profile = result.resourceData as {
      sub: string;
      email?: string;
      name?: string;
      preferred_username?: string;
    } | null;

    return {
      accessToken: result.accessToken?.token,
      idToken: result.idToken,
      refreshToken: result.refreshToken,
      scopes: result.scope,
      profile,
    };
  } catch (error: any) {
    if (error?.code === 'USER_CANCELLED') return null;
    throw error;
  }
}

resourceData detiene il JSON restituito dal /userinfo endpoint, quindi ottieni il profilo senza un'altra richiesta. Per leggere le affermazioni del token ID per la visualizzazione, utilizza SocialLogin.decodeIdToken({ idToken }). Quel chiamata non verifica la firma.

Opzioni di accesso da sapere:

• loginHint pre-compila l'utente.
• prompt: 'login' obbliga la riautenticazione anche con una sessione Okta attiva.
• additionalParameters: { idp: '0oa...' } indirizza direttamente a un provider di identità specifico configurato in Okta.

Sul web con flow: 'redirect', chiama SocialLogin.handleRedirectCallback() su pagina di callback per completare l'interscambio.

Passo 6: Verifica i token Okta sul tuo API

import { createRemoteJWKSet, jwtVerify } from 'jose';

const ISSUER = 'https://your-org.okta.com/oauth2/default';
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/v1/keys`));

export async function verifyOktaAccessToken(token: string) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: 'api://default', // the Audience value of your authorization server
  });
  return payload; // payload.uid is the Okta user ID, payload.sub the login
}

Trova l'utenza sul server di autorizzazione Impostazioni tab. Non validare i token di accesso dal server di autorizzazione dell'organizzazione nel tuo API. Okta non lo supporta.

Passo 7: Aggiorna i token

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function ensureFreshOktaToken() {
  const { isLoggedIn } = await SocialLogin.isLoggedIn({ provider: 'oauth2', providerId: 'okta' });
  if (!isLoggedIn) {
    await SocialLogin.refresh({ provider: 'oauth2', options: { providerId: 'okta' } });
  }
  const { accessToken } = await SocialLogin.getAuthorizationCode({ provider: 'oauth2', providerId: 'okta' });
  return accessToken;
}

Se il token di refresh è scaduto o revocato, refresh rifiuta. Cattura questo e invia l'utente indietro signInWithOkta().

Controlla il Token di Rinnovo sezione di integrazione dell'app. Con Sezione dei token di aggiornamento, each refresh returns a new refresh token and the old one stops working after a short grace period. The plugin replaces its stored copy automatically. If you hold the refresh token yourself (for example in the Keychain through @capgo/capacitor-nativo-biometrico setData), use SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) e salva il valore restituito.

Step 8: Disconnetti

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

La plugin cancella i suoi token memorizzati, quindi apre /v1/logout con id_token_hint e post_logout_redirect_uri. Okta ends the session and redirects to your sign-out URI, which must be listed in the app integration. On mobile the logout page opens in the system browser.

To also revoke the refresh token server-side, call Okta’s /v1/revoke endpoint dal tuo backend o dall'app prima di effettuare il logout. Vedi il nostro guida alla revoca dei token per il pattern.

Risolvere i problemi

Attiva logsEnabled: true in la configurazione del provider mentre si debugga per visualizzare l'URL di autorizzazione e le risposte del token nei registri nativi.

Rilascio delle modifiche Okta

I clienti aziendali cambiano spesso le politiche o le pretese dopo il lancio. Le modifiche client-side come gli ambiti, la gestione delle pretese o le schermate degli errori possono essere inviate con Capgo aggiornamenti in tempo reale Invece di una completa revisione dello store. Le parti native (filtro di intento, nuovo schema) richiedono ancora una nuova build.

Guida correlate

• How to sign in with Auth0 using Capacitor
• How to sign in with Microsoft Entra ID using Capacitor
• Come accedere con Auth0 utilizzando Capacitor
• Come accedere con Microsoft Entra ID utilizzando __CAPGO_KEEP_0__