Come accedere con Okta usando Capacitor

Per accedere con Okta in un'app Capacitor, crea un Applicazione nativa OIDC nella Okta Admin Console, registra un URI di reindirizzamento per l'accesso come com.example.app://oauth/okta, ed esegui il flusso di autorizzazione code con PKCE in un browser di sistema. Con @capgo/capacitor-social-login configuri Okta una sola volta con il tuo issuer e client ID, poi chiama SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Questa guida copre l'integrazione dell'app Okta, le policy dell'authorization server, il plugin code per iOS, Android e web, il token refresh, il profilo utente, il logout e gli errori Okta più comuni. Si basa su Capacitor 8, versione ottobre 2026.

Cosa ti serve

• Un'organizzazione Okta (Workforce Identity o Customer Identity) con accesso admin per creare integrazioni app.
• Un'app Capacitor 8.
• Il tuo Capacitor appId, che riutilizzerai come schema di redirect.
• Opzionalmente, un backend API che valida i token di accesso Okta.

Come funziona il login Okta in un'app Capacitor

La tua app non mostra mai un form per la password. Apre la pagina di sign-in di Okta in un browser sicuro, Okta gestisce MFA e policy, poi reindirizza alla tua app con un code. L'app scambia il code più il PKCE verifier per ottenere i token.

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

Passo 1: Crea l'integrazione app Okta

1. Nella console di amministrazione di Okta, vai a Applicazioni > Applicazioni > Crea integrazione app.
2. Usa OIDC - OpenID Connect e Applicazione nativa.
3. Dalle un nome, poi sotto Grant type mantieni Autorizzazione Code e seleziona Refresh Token se gli utenti devono restare autenticati.
4. URI di redirect per il sign-in: com.example.app://oauth/okta. Aggiungi https://app.example.com/auth/callback se pubblichi una build web.
5. URI di redirect per il sign-out: com.example.app://oauth/logout (e l'URL web, se necessario).
6. Assegnazioni: scegli chi può usare l'app. Gli utenti non assegnati riceveranno un errore al login.
7. Salva, quindi copia il ID Client. Sotto Credenziali del client, l'autenticazione del client deve essere Nessuna e Richiedi PKCE deve essere attivo.

Okta richiede URI di redirect nativi con uno scheme di uso privato in formato reverse-domain. Il tuo bundle ID o application ID è adatto.

Controlla l'autorizzazione server

Vai su Sicurezza > API > Server di autorizzazione. La maggior parte delle configurazioni utilizza il default server di autorizzazione personalizzato, issuer https://your-org.okta.com/oauth2/default.

Apri la scheda Policy di accesso del server. Deve esserci una policy assegnata alla tua app (o a tutti i client) con una regola che consenta il grant Authorization Code e il Refresh Token se lo usi. Una regola mancante genera l'errore “Policy evaluation failed for this request”.

Origini attendibili per il web

Se esegui lo stesso code sul web, aggiungi la tua origine web sotto Sicurezza > API > Origini attendibili con CORS spuntato. 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 è l'unico provider, disattiva gli SDK social inclusi in capacitor.config.ts:

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

Passo 3: Aggiungi l'intent filter di redirect per Android

In android/app/src/main/AndroidManifest.xml, all'interno dell' MainActivity activity:

<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 default di Capacitor, così il redirect arriva nell'activity 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: imposta issuerUrl: OKTA_ISSUER e rimuovi gli URL degli endpoint. Il plugin carica /.well-known/openid-configuration e li compila. I team che migrano da Ionic Auth Connect possono usare SocialLoginAuthConnect con il okta preset (issuer, clientId, redirectUrl), descritto nella guida alla migrazione.

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 contiene il JSON restituito da /userinfo endpoint, così ottieni il profilo senza un'altra richiesta. Per leggere i claim del token ID per la visualizzazione, usa SocialLogin.decodeIdToken({ idToken }). Questa chiamata non verifica la firma.

Opzioni di login da conoscere:

• loginHint compila automaticamente il nome utente.
• prompt: 'login' forza la ri-autenticazione anche con una sessione Okta attiva.
• additionalParameters: { idp: '0oa...' } instrada direttamente a un identity provider specifico configurato in Okta.

Sul web con flow: 'redirect', chiama SocialLogin.handleRedirectCallback() sulla pagina di callback per completare lo scambio.

Passo 6: Valida 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'audience nella scheda dell'authorization server Impostazioni tab. Non validare i token di accesso del server di autorizzazione dell'organizzazione nel tuo API. Okta non supporta questa operazione.

Passaggio 7: Refresh 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 refresh token è scaduto o revocato, refresh rifiuta. Gestisci l'errore e rimanda l'utente alla signInWithOkta().

Consulta la Refresh Token sezione dell'integrazione dell'app. Con Ruota il token dopo ogni utilizzo, ogni refresh restituisce un nuovo refresh token e il precedente smette di funzionare dopo un breve periodo di grazia. Il plugin sostituisce automaticamente la copia salvata. Se gestisci tu il refresh token (ad esempio nel Keychain tramite @capgo/capacitor-native-biometric setData), usa SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) e salva il valore restituito.

Passo 8: Esci

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

Il plugin cancella i token memorizzati, poi apre /v1/logout con id_token_hint e post_logout_redirect_uri. Okta termina la sessione e reindirizza al tuo URI di logout, che deve essere elencato nell'integrazione dell'app. Su mobile, la pagina di logout si apre nel browser di sistema.

Per revocare anche il refresh token lato server, chiama l'endpoint /v1/revoke di Okta dal tuo backend o dall'app prima di fare logout. Consulta la nostra guida alla revoca dei token per il pattern.

Risoluzione problemi

Attiva logsEnabled: true nella config del provider durante il debug per vedere l'URL di autorizzazione e le risposte del token nei log nativi.

Rollout delle modifiche a Okta

I clienti enterprise spesso modificano policy o claim dopo il lancio. Le modifiche lato client come scope, gestione dei claim o schermate di errore possono essere pubblicate con Live updates di Capgo invece di una revisione completa dello store. Le parti native (intent filter, nuovo scheme) richiedono comunque una nuova build.

Guide correlate

• Come accedere con Auth0 usando Capacitor
• Come accedere con Microsoft Entra ID usando Capacitor
• Come aggiungere l'autenticazione a un'app Capacitor
• Documentazione integrazione Okta per il plugin Social Login