So meldest du dich mit Okta über Capacitor an

Um sich in einer Capacitor-App mit Okta anzumelden, erstelle eine OIDC Native Application im Okta Admin Console, registriere eine Sign-in-Redirect-URI wie z. B. com.example.app://oauth/okta, und führe den Authorization-code-Flow mit PKCE in einem Systembrowser aus. Mit @capgo/capacitor-social-login Sie konfigurieren Okta einmalig mit Ihrem Issuer und Client ID und rufen dann auf SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Dieser Leitfaden behandelt die Okta-App-Integration, Authorization-Server-Policies, das Plugin code für iOS, Android und Web, Token-Refresh, User-Profil, Logout und die häufigsten Okta-Fehler. Er richtet sich an Capacitor 8 (Stand Oktober 2026).

Voraussetzungen

• Ein Okta-Organisation (Workforce Identity oder Customer Identity) mit Admin-Zugriff zur Erstellung von App-Integrationen.
• Eine Capacitor 8-App.
• Ihr Capacitor appId, den Sie als Redirect-Schema wiederverwenden.
• Optional ein Backend-API, das Okta-Access-Tokens validiert.

So funktioniert der Okta-Login in einer Capacitor-App

Ihre App zeigt niemals ein Passwort-Formular an. Sie öffnet die Okta-Anmeldeseite in einem sicheren Browser, Okta übernimmt MFA und Policies und leitet dann mit einem code zurück zu Ihrer App. Die App tauscht den code plus den PKCE-Verifier gegen Tokens ein.

Nutze Custom Tabs unter Android. Okta Verify, FastPass und Passkeys verhalten sich im Systembrowser besser als in einer eingebetteten WebView, und SSO-Cookies werden mit Chrome geteilt.

Schritt 1: Okta-App-Integration erstellen

1. Gehe in der Okta Admin Console zu Applications > Applications > App-Integration erstellen.
2. Wähle OIDC – OpenID Connect und Native-Anwendung.
3. Gib einen Namen ein, dann unter Grant-Typ beibehalten Autorisierung Code und anhaken Refresh-Token ob Nutzer angemeldet bleiben sollen.
4. Anmelde-Redirect-URIs: com.example.app://oauth/okta. Füge hinzu https://app.example.com/auth/callback falls du einen Web-Build auslieferst.
5. Abmelde-Redirect-URIs: com.example.app://oauth/logout (und die Web-URL, falls nötig).
6. Zuweisungen: Lege fest, wer die App nutzen darf. Nicht zugewiesene Nutzer erhalten bei der Anmeldung eine Fehlermeldung.
7. Speichern, dann den Client-ID. Unter Client-Credentials, sollte die Client-Authentifizierung Keine und PKCE erzwingen aktiviert sein.

Okta erfordert native Redirect-URIs, die ein privates Scheme im Reverse-Domain-Format verwenden. Deine Bundle ID oder Application ID ist dafür geeignet.

Authorization Server prüfen

Gehe zu Sicherheit > API > Authorization Server. Die meisten Setups nutzen den default Benutzerdefinierter Authorization Server, Issuer https://your-org.okta.com/oauth2/default.

Öffne den Tab Zugriffsrichtlinien Tab. Deiner App (oder „All clients“) muss eine Policy zugewiesen sein, die eine Regel enthält, welche den Autorisierung Code Grant erlaubt, und Refresh-Token falls du es verwendest. Eine fehlende Regel führt zu „Policy evaluation failed for this request“.

Trusted Origins für Web

Wenn du dasselbe code im Web ausführst, füge deine Web-Origin unter Security > API > Trusted Origins hinzu mit CORS aktiviert. Ohne dies blockiert der Browser die Token-Anfrage.

Schritt 2: Plugin installieren

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

Wenn Okta der einzige Provider ist, deaktiviere die mitgelieferten Social SDKs in capacitor.config.ts:

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

Schritt 3: Android Redirect Intent Filter hinzufügen

Unter android/app/src/main/AndroidManifest.xml, innerhalb der 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 muss bleiben android:launchMode="singleTask", was der Capacitor-Standard ist, damit der Redirect in der laufenden Activity ankommt.

Schritt 4: Okta initialisieren

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

Kürzere Alternative: setze issuerUrl: OKTA_ISSUER und lasse die Endpoint-URLs weg. Das Plugin lädt /.well-known/openid-configuration und füllt sie aus. Teams, die von Ionic Auth Connect migrieren, können SocialLoginAuthConnect mit dem okta Preset (issuer, clientId, redirectUrl), beschrieben im Migrationsleitfaden.

Schritt 5: Anmelden und Profil auslesen

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 holds the JSON returned by the /userinfo Endpoint zurückgegeben wird, sodass du das Profil ohne weiteren Request erhältst. Um die ID-Token-Claims anzuzeigen, nutze SocialLogin.decodeIdToken({ idToken }). Dieser Aufruf verifiziert die Signatur nicht.

Wichtige Login-Optionen:

• loginHint füllt den Benutzernamen automatisch aus.
• prompt: 'login' erzwingt eine Re-Authentifizierung, selbst bei aktiver Okta-Session.
• additionalParameters: { idp: '0oa...' } leitet direkt zu einem in Okta konfigurierten Identity Provider weiter.

Im Web mit flow: 'redirect', rufe SocialLogin.handleRedirectCallback() auf der Callback-Seite, um den Austausch abzuschließen.

Schritt 6: Okta-Token auf deinem API validieren

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
}

Finde das Audience auf dem Autorisierungsserver Einstellungen Validieren Sie keine Access-Token des Organisations-Authorization-Servers in Ihrem API. Okta unterstützt dies nicht.

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

Wenn das Refresh Token abgelaufen oder widerrufen ist, refresh ablehnt. Fange das ab und leite den Benutzer zurück zu signInWithOkta().

Schau in die Refresh-Token Bereich der App-Integration. Mit Token nach jeder Nutzung rotieren, liefert jeder Refresh ein neues Refresh Token, und das alte funktioniert nach einer kurzen Grace Period nicht mehr. Das Plugin ersetzt die gespeicherte Kopie automatisch. Falls du das Refresh Token selbst verwaltest (z. B. im Keychain über @capgo/capacitor-native-biometric setData), nutze SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) und speichere den Rückgabewert.

Schritt 8: Abmelden

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

Das Plugin löscht die gespeicherten Token und öffnet /v1/logout mit id_token_hint und post_logout_redirect_uri. Okta beendet die Session und leitet zur Sign-out-URI weiter, die in der App-Integration hinterlegt sein muss. Auf Mobilgeräten öffnet sich die Logout-Seite im Systembrowser.

Um auch das Refresh-Token serverseitig zu widerrufen, rufe den Okta- /v1/revoke Endpoint von deinem Backend oder der App aus auf, bevor du dich abmeldest. Siehe unseren Token-Revocation-Guide für das Pattern.

Fehlerbehebung

Einschalten logsEnabled: true in der Provider-Konfiguration beim Debugging, um die authorize-URL und Token-Antworten in den nativen Logs zu sehen.

Rollout von Okta-Änderungen

Enterprise-Kunden ändern oft Policies oder Claims nach dem Launch. Client-seitige Änderungen wie Scopes, Claim-Handling oder Fehlerbildschirme können mit Capgo Live Updates statt einer vollständigen Store-Prüfung. Die nativen Teile (Intent-Filter, neues Schema) erfordern weiterhin einen neuen Build.

Verwandte Guides

• So melden Sie sich mit Auth0 über Capacitor an
• So melden Sie sich mit Microsoft Entra ID über Capacitor an
• So fügen Sie einer Capacitor-App Authentifizierung hinzu
• Okta-Integrationsdokumentation für das Social Login-Plugin