Comment se connecter avec Okta en utilisant Capacitor

Pour vous connecter avec Okta dans une application Capacitor, créez une Application native OIDC dans la console d’administration Okta, enregistrez un URI de redirection de connexion tel que 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 seule fois avec votre issuer et votre client ID, puis vous appelez SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Ce guide couvre l’intégration de l’application Okta, les politiques du serveur d’autorisation, le plugin code pour iOS, Android et web, le rafraîchissement des tokens, le profil utilisateur, la déconnexion et les erreurs Okta les plus courantes. Il cible Capacitor 8 à partir d’octobre 2026.

Ce dont vous avez besoin

• Une organisation Okta (Workforce Identity ou Customer Identity) avec un accès administrateur pour créer des intégrations d’applications.
• Une application Capacitor 8.
• Votre Capacitor appId, que vous réutiliserez comme schéma de redirection.
• Optionnellement, une API backend qui valide les tokens d'accès Okta.

Fonctionnement de la connexion Okta dans une app Capacitor

Votre app n'affiche jamais de 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 app avec un code. L'app échange le code et le vérificateur PKCE contre des tokens.

Privilégiez les Custom Tabs sur Android. Okta Verify, FastPass et les passkeys fonctionnent mieux dans le navigateur système que dans une WebView intégrée, et les cookies SSO sont partagés avec Chrome.

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

1. Dans la console d'administration Okta, allez dans Applications > Applications > Créer une intégration d'application.
2. Choisissez OIDC - OpenID Connect et Application native.
3. Donnez-lui un nom, puis sous Type d’octroi conservez Autorisation Code et cochez Token de rafraîchissement si les utilisateurs doivent rester connectés.
4. URI de redirection de connexion: com.example.app://oauth/okta. Ajoutez https://app.example.com/auth/callback si vous livrez un build web.
5. URI de redirection de déconnexion: com.example.app://oauth/logout (et l'URL web si nécessaire).
6. Affectations: choisissez qui peut utiliser l'app. Les utilisateurs non affectés reçoivent une erreur à la connexion.
7. Enregistrez, puis copiez le ID client. Sous Client Credentials, l’authentification client doit être Aucun et Exiger PKCE doit être activé.

Okta exige des URI de redirection natives utilisant un schéma de usage privé au format de domaine inversé. Votre bundle ID ou application ID convient.

Vérifier le serveur d'autorisation

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

Ouvrez l’onglet Politiques d'accès du serveur. Une politique doit être assignée à votre application (ou à All clients) avec une règle autorisant le Autorisation Code grant, et Token de rafraîchissement si vous l’utilisez. Une règle manquante provoque l’erreur « Policy evaluation failed for this request ».

Trusted Origins pour le web

Si vous exécutez le même code sur le web, ajoutez votre origine web sous Security > API > Trusted Origins par CORS vérifié. Sans cela, le navigateur bloque la requête de token.

Étape 2 : Installer le plugin

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

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

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

Étape 3 : Ajouter le filtre d'intent de redirection Android

Dans android/app/src/main/AndroidManifest.xml, à l'intérieur de l' 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 doit rester android:launchMode="singleTask", qui est la valeur par défaut de Capacitor, afin que 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,
      },
    },
  });
}

Alternative plus courte : définir issuerUrl: OKTA_ISSUER et supprimer les URL de l'endpoint. Le plugin charge /.well-known/openid-configuration et les remplit. Les équipes qui migrent depuis Ionic Auth Connect peuvent utiliser SocialLoginAuthConnect avec le okta préréglage (issuer, clientId, redirectUrl), abordé dans la guide de migration.

Étape 5 : se connecter et lire 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 renvoyé par le /userinfo endpoint, afin d’obtenir le profil sans requête supplémentaire. Pour lire les claims du token ID à des fins d’affichage, utilisez SocialLogin.decodeIdToken({ idToken }). Cet appel ne vérifie pas la signature.

Options de connexion à connaître :

• loginHint préremplit le nom d’utilisateur.
• prompt: 'login' force la réauthentification, même avec une session Okta active.
• additionalParameters: { idp: '0oa...' } redirige directement vers un fournisseur d’identité spécifique configuré dans Okta.

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

Étape 6 : Valider les tokens 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
}

Retrouvez l’audience sur le serveur d’autorisation Paramètres onglet. Ne validez pas les access tokens du serveur d'autorisation de l'organisation dans votre API. Okta ne prend pas cela en charge.

Étape 7 : refresh tokens

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 refresh token est expiré ou révoqué, refresh rejette. Interceptez l'erreur et renvoyez l'utilisateur vers signInWithOkta().

Consultez la Token de rafraîchissement section de l'intégration de l'app. Avec Rotation du token après chaque utilisation, chaque refresh renvoie un nouveau refresh token et l'ancien cesse de fonctionner après une courte période de grâce. Le plugin remplace automatiquement sa copie stockée. Si vous conservez vous-même le refresh token (par exemple dans le Keychain via @capgo/capacitor-native-biometric setData), utilisez SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) et enregistrez la valeur renvoyée.

Étape 8 : Se déconnecter

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

Le plugin efface les tokens stockés, puis ouvre /v1/logout par id_token_hint et post_logout_redirect_uri. Okta met fin à 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.

Pour révoquer également le refresh token côté serveur, appelez l’ /v1/revoke endpoint d’Okta depuis votre backend ou l’application avant de vous déconnecter. Consultez notre guide de révocation de token pour le modèl’à suivre.

Troubleshooting

Activez logsEnabled: true dans la configuration du fournisseur pendant le débogage pour voir l’URL d’autorisation et les réponses du token dans les logs natifs.

Déploiement des modifications Okta

Les clients enterprise modifient souvent leurs politiques ou leurs claims après le lancement. Les modifications côté client, comme les scopes, le traitement des claims ou les écrans d’erreur, peuvent être déployées les live updates Capgo au lieu d’une revue complète sur le store. Les éléments natifs (filtre d’intent, nouveau schéma) nécessitent toujours un nouveau build.

Guides associés

• Comment se connecter avec Auth0 à l'aide de Capacitor
• Comment se connecter avec Microsoft Entra ID en utilisant Capacitor
• Comment ajouter l'authentification à une application Capacitor
• Documentation d'intégration Okta pour le plugin Social Login