Comment vous connecter à Okta à l'aide de Capacitor

Pour vous connecter avec Okta dans une application Capacitor , créez un Application native OIDC dans le console d'administration Okta, enregistrez une URI de redirection de connexion comme com.example.app://oauth/okta, et exécutez le flux d'autorisation code avec PKCE dans un navigateur système. Avec @capgo/capacitor-social-login Vous configurez Okta une fois avec votre émetteur et votre ID client, puis appelez SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Cette guide couvre l'intégration de l'application Okta, les politiques du serveur d'autorisation, le plugin code pour iOS, Android et web, la mise à jour des jetons, le profil de l'utilisateur, la déconnexion et les erreurs Okta qui apparaissent le plus souvent. Il s'adresse à Capacitor 8 à partir d'octobre 2026.

Ce dont vous avez besoin

• Une organisation Okta (Identité du personnel ou Identité du client) avec accès administrateur pour créer des intégrations d'application.
• Une application Capacitor 8.
• Votre Capacitor appId, que vous reutiliserez comme schéma de redirection.
• Optionnellement, un backend API qui valide les jetons d'accès Okta.

How Okta login works in a Capacitor app

Votre application ne montre jamais un formulaire de mot de passe. Elle ouvre la page de connexion Okta dans un navigateur sécurisé, Okta gère la MFA et les politiques, puis redirige vers votre application avec un code. L'application échange le code plus le vérificateur PKCE pour des jetons.

Prefer Custom Tabs on Android. Okta Verify, FastPass and passkeys behave better in the system browser than in an embedded WebView, and SSO cookies are shared with Chrome.

Étape 1 : Créez l'intégration d'application Okta

1. Sur le tableau de bord d'administration Okta, allez à Applications > Applications > Créer une intégration d'application.
2. Sélectionnez OIDC - Connectez-vous avec OpenID et Application native.
3. Nommez-le, puis sous Type de subvention gardez L'autorisation Code et cochez Jetons de rafraîchissement Si les utilisateurs doivent rester connectés.
4. URIs de redirection de connexion: com.example.app://oauth/oktaAjoutez. https://app.example.com/auth/callback Si vous envoyez une build web.
5. URIs de redirection de déconnexion: com.example.app://oauth/logout (et l’URL web si nécessaire).
6. AssignmentsDéfinissez qui peut utiliser l'application. Les utilisateurs non affectés obtiennent une erreur lors de la connexion.
7. Sauvegardez, puis copiez le SousAssignments Crédentiels du client, l'authentification client devrait être None et Requière PKCE devrait être activé.

Okta nécessite des URIs de redirection natives sous forme de schéma de domaine inversé à usage privé. Votre ID de bundle ou votre ID d'application convient.

Vérifiez le serveur d'autorisation

Allez à Sécurité > API > Serveurs d'autorisationLa plupart des configurations utilisent le default serveur d'autorisation personnalisé, émetteur https://your-org.okta.com/oauth2/default.

Ouvrez la fenêtre de l'onglet Politiques d'accès votre application (ou tous les clients) doit avoir une politique assignée avec une règle qui permet le Autorisation Code d'octroi, et Jetons de rafraîchissement Si vous l'utilisez. Une règle manquante produit « Évaluation de politique échouée pour cette demande ».

Origines fiables pour le web

Si vous exécutez le même code sur le web, ajoutez votre origine web sous Security > API > Origines fiables avec CORS coché. Sans cela, le navigateur bloque la demande de jeton.

Étape 2 : Installez le plugin

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

Si Okta est le seul fournisseur, désactivez les SDK sociaux embarqués dans capacitor.config.ts:

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

Étape 3 : Ajoutez le filtre d'intention de redirection Android

Dans android/app/src/main/AndroidManifest.xml, à l'intérieur de MainActivity activité :

<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 doit rester android:launchMode="singleTask", ce qui est le Capacitor par défaut, donc la redirection arrive dans l'activité en cours.

Étape 4 : Initialiser 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,
      },
    },
  });
}

Étape 4 : Initialiser Okta issuerUrl: OKTA_ISSUER Alternative plus courte : définir /.well-known/openid-configuration et abandonner les URL des points de terminaison. Le plugin charge SocialLoginAuthConnect avec okta avec leissuer, clientId, redirectUrlpréconfiguré ( présenté dans le.

Étape 5 : Connectez-vous et lisez le profil

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 contient le JSON retourné par le /userinfo l'endpoint, vous obtenez donc le profil sans autre requête. Pour lire les revendications du jeton ID pour affichage, utilisez SocialLogin.decodeIdToken({ idToken }). Cette appelle ne vérifie pas la signature.

Options de connexion à connaître :

• loginHint remplit automatiquement le nom d'utilisateur.
• prompt: 'login' oblige une nouvelle authentification même avec une session Okta active.
• additionalParameters: { idp: '0oa...' } dirige directement vers un fournisseur d'identité spécifique configuré dans Okta.

Sur le web avec flow: 'redirect', appelez SocialLogin.handleRedirectCallback() sur la page de rappel pour terminer l'échange.

Étape 6 : Validez les jetons Okta sur votre 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
}

Trouvez l'audience sur le serveur d'autorisation Paramètres ne validez pas les jetons d'accès de l'org serveur d'autorisation dans votre API. Okta ne le supporte pas.

Étape 7 : Raffraîchir les jetons

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;
}

Si le jeton de rafraîchissement est expiré ou révoqué, refresh refuse. Capturer cela et renvoyer l'utilisateur à signInWithOkta().

Vérifiez la section des jetons de rafraîchissement de l'intégration de l'application. Avec Roter le jeton après chaque utilisation, chaque rafraîchissement renvoie un nouveau jeton de rafraîchissement et l'ancien cesse de fonctionner après un court délai. Le plugin remplace automatiquement sa copie stockée. Si vous détenez vous-même le jeton de rafraîchissement (par exemple dans la clé de chiffrement à travers @capgo/capacitor-native-biometrique setDatautilisez SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) et enregistrez la valeur retournée.

Étape 8 : Déconnexion

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

Le plugin efface ses jetons stockés, puis ouvre /v1/logout avec id_token_hint et post_logout_redirect_uri. Okta termine la session et redirige vers votre URI de déconnexion, qui doit être listée dans l'intégration de l'application. Sur mobile, la page de déconnexion s'ouvre dans le navigateur système.

Appeler Okta pour révoquer le jeton de rafraîchissement serveur. /v1/revoke de votre serveur ou de l'application avant de vous déconnecter. Consultez notre guide de révocation de jetons pour le modèle.

Troubleshooting

Activer logsEnabled: true Dans la configuration du fournisseur pendant la débogage pour voir l'URL d'autorisation et les réponses de jeton dans les journaux natifs.

Sortie progressive des modifications Okta

Enterprise customers often change policies or claims after launch. Client-side changes like scopes, claim handling or error screens can ship with Capgo mises à jour en direct au lieu d'une revue complète du magasin. Les pièces natives (filtre d'intention, nouveau schéma) nécessitent toujours une nouvelle build.

Guides connexes

• Comment vous connecter avec Auth0 à l'aide de Capacitor
• Comment vous connecter avec Microsoft Entra ID à l'aide de Capacitor
• Comment ajouter une authentification à une application Capacitor
• Documentation d'intégration Okta pour le plugin de connexion sociale