Mithilfe von Microsoft Entra ID (Azure AD) in Capacitor anmelden

Um sich mit Microsoft Entra ID (früher Azure Active Directory) in einer Capacitor-Anwendung anzumelden, müssen Sie eine öffentliche Client-Anwendung im Entra-Admin-Zentrum registrieren, eine Mobile und Desktop-Anwendungen eine Redirect-URI wie com.example.app://oauth/azure, and run the OpenID Connect authorization code flow with PKCE through the system browser. With @capgo/capacitor-social-login das bedeutet, eine initialize Aufruf mit den Microsoft-Identitätsplattform-Endpunkten v2.0 und SocialLogin.login({ provider: 'oauth2', options: { providerId: 'azure' } }).

Diese Anleitung umfasst die Anwendungsbewerbung, die Auswahl der richtigen Autorität, Graph und benutzerdefinierte API-Berechtigungen, Token-Validierung, bedingte Zugriffsberechtigungen, Abmeldung und die AADSTS-Fehler, die Sie sehen werden. Sie zielt auf Capacitor 8 im Oktober 2026 ab.

Was Sie benötigen

• Ein Microsoft Entra-Konto und eine Rolle, die App-Registrierungen erstellen kann (Application Developer oder höher).
• Ein Capacitor 8-App und seine appId, die Sie als Redirect-Scheme wieder verwenden.
• Optional, ein Backend API , das Entra-Tokens akzeptiert.

Warum nicht MSAL.js im WebView

MSAL.js ist für Browser entwickelt, die ihren Ursprung besitzen und Pop-ups öffnen können. In einem Capacitor WebView ist der Ursprung capacitor://localhost auf iOS und https://localhost auf Android, werden Pop-ups blockiert, und eine vollständige Seite-Redirect würde Ihre App von ihrem eigenen Bundle wegleiten. Microsofts Richtlinie für native Apps ist der Systembrowser mit PKCE (RFC 8252), was der Plugin auch tut:

Bei Android aktivieren Sie Custom Tabs. Die Standard-Webview kann nicht mit Microsoft Authenticator, Passwörtern oder dem Unternehmensportal kommunizieren, auf die Conditional Access häufig angewiesen ist.

Schritt 1: Registrieren Sie die App bei Entra ID

1. Öffnen Sie das Microsoft Entra-Verwaltungszentrum und gehen Sie zu Entra ID > Anwendungsregistrierungen > Neuanmeldung.
2. Ein Namen, wie z.B. "Beispiel-Mobil" eingeben.
3. Wählen Sie Unterstützte Kontotypen. Dies bestimmt die Autorität, die Sie später verwenden.
4. Die Umleitung-URI für den Moment überspringen und auf Registrieren.
5. On AufÜbersicht , kopieren Sie das und Directory (Mandanten) ID.

Wählen Sie die Autorität

Verwenden Sie die Mandanten-ID, wenn immer möglich. Sie erzeugt vorhersehbare Aussteller und vermeidet ungewollte Anmeldungen von anderen Mandanten.

Hinzufügen von Redirect-URIs

Gehe zu Authentifizierung > Plattform hinzufügen:

• Mobile und Desktop-Anwendungen: fügen Sie com.example.app://oauth/azure zurück, wenn Sie einen Post-Logout-Redirect wünschen. com.example.app://oauth/logout Wenn Sie eine Post-Logout-Weiterleitung wünschen.
• Einseitige Anwendung (falls Sie ein Web-Build bereitstellen): hinzufügen https://app.example.com/auth/callback.

Melden Sie die mobile URI nicht unter WebWeb Plattform-Redirects sind vertrauliche Clients und erfordern ein Geheimnis am Token-Endpunkt.

API Berechtigungen

API Berechtigungen enthält bereits Microsoft Graph > User.Read. Add offline_access, openid, profile und email wenn sie nicht aufgelistet sind. Einige Mandanten blockieren die Benutzerzustimmung. In diesem Fall muss ein Administrator auf Zustimmung des Administrators erteilen, andernfalls sehen die Benutzer AADSTS65001 oder eine "Benutzerzustimmung benötigen"-Anzeige.

Ermöglichen Sie einen Umfang für Ihren eigenen API (optional)

Wenn Ihr Backend den Token akzeptieren soll:

1. Open Melden Sie einen API und setzen Sie die Anwendungs-ID-URI, typischerweise api://<client-id>.
2. Fügen Sie einen Bereich mit dem Namen access_as_userWer zustimmen kann: Administratoren und Benutzer.
3. In Manifest, setzen Sie "requestedAccessTokenVersion": 2 , so dass Zugriffstoken den v2.0-Ausstellerformat verwenden.

Schritt 2: Installieren Sie das Plugin und fügen Sie die Intent-Filter hinzu

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

In android/app/src/main/AndroidManifest.xmlFügen Sie es MainActivity:

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

Behalten Sie android:launchMode="singleTask" auf MainActivity (die Capacitor-Standardwerte). Wenn Sie Google, Apple oder Facebook-Login nicht verwenden, deaktivieren Sie sie unter plugins.SocialLogin.providers auf capacitor.config.ts damit ihre SDKs aus dem Build herausgehalten werden.

Schritt 3: Initialisierung des Entra ID-Anbieters

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

const TENANT = 'YOUR_TENANT_ID'; // or organizations / common
const AUTHORITY = `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0`;
const isWeb = Capacitor.getPlatform() === 'web';

export async function initAuth() {
  await SocialLogin.initialize({
    oauth2: {
      azure: {
        appId: 'YOUR_CLIENT_ID',
        authorizationBaseUrl: `${AUTHORITY}/authorize`,
        accessTokenEndpoint: `${AUTHORITY}/token`,
        redirectUrl: isWeb
          ? 'https://app.example.com/auth/callback'
          : 'com.example.app://oauth/azure',
        scope: 'openid profile email offline_access User.Read',
        pkceEnabled: true,
        resourceUrl: 'https://graph.microsoft.com/v1.0/me',
        logoutUrl: `${AUTHORITY}/logout`,
        postLogoutRedirectUrl: isWeb ? 'https://app.example.com/' : 'com.example.app://oauth/logout',
        androidUseCustomTabs: true,
      },
    },
  });
}

Mit resourceUrl Zeiger auf Graph /mezurück, ruft der Plugin Graph direkt nach der Anmeldung auf und gibt das Profil in resourceData.

Wenn Sie von Ionic Auth Connect migrieren SocialLoginAuthConnect hat eine azure vordefinierte Einstellung, die nur tenantId, clientId und redirectUrl. Siehe die Entra ID-Integration-Seite.

Schritt 4: Anmeldung

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

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

    const me = result.resourceData as {
      id: string;
      displayName?: string;
      mail?: string | null;
      userPrincipalName?: string;
    } | null;

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

Zu nützliche Optionen:

• loginHint: 'jane@contoso.com' vorab die Kontodaten einträgt und die Kontoauswahl für diesen Benutzer überspringt.
• prompt: 'select_account' zeigt immer die Kontoauswahl an, nützlich für geteilte Geräte.
• additionalParameters: { domain_hint: 'contoso.com' } Benutzer direkt zu ihrem federierten IdP weiterleitet.

mail ist oft null für Konten ohne Postfach. Fällt zurück auf userPrincipalName oder den preferred_username Angabe des Anspruchs im ID-Token.

Schritt 5: Aufrufen von Microsoft Graph

export async function getMyPhotoBlob(graphToken: string) {
  const res = await fetch('https://graph.microsoft.com/v1.0/me/photo/$value', {
    headers: { Authorization: `Bearer ${graphToken}` },
  });
  if (res.status === 404) return null; // no photo set
  if (!res.ok) throw new Error(`Graph error ${res.status}`);
  return res.blob();
}

Adden Sie jeden Graph-Bereich, den Sie benötigen (z. B. Calendars.Readbeide in API Berechtigungen und in der scope Zeichenfolge.

Step 6: Get a token for your own API

Ein Zugriffstoken richtet sich auf einen Ressourcen. Um Ihren Backend aufzurufen, fügen Sie eine zweite Eintrag neben azure in der gleichen oauth2 Map Ihres initialize Aufrufs, Ihren API Bereich anstelle von Graph anfordern:

await SocialLogin.initialize({
  oauth2: {
    azure: graphConfig, // the object from step 3, moved into a const
    azureApi: {
      appId: 'YOUR_CLIENT_ID',
      authorizationBaseUrl: `${AUTHORITY}/authorize`,
      accessTokenEndpoint: `${AUTHORITY}/token`,
      redirectUrl: 'com.example.app://oauth/azure-api', // register this URI too
      scope: 'openid profile offline_access api://YOUR_CLIENT_ID/access_as_user',
      pkceEnabled: true,
      androidUseCustomTabs: true,
    },
  },
});

Der Benutzer hat bereits eine Microsoft-Sitzung, sodass der zweite Login normalerweise ohne Aufforderung abgeschlossen wird. Validieren Sie das Token auf dem Server:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const TENANT_ID = 'YOUR_TENANT_ID';
const jwks = createRemoteJWKSet(
  new URL(`https://login.microsoftonline.com/${TENANT_ID}/discovery/v2.0/keys`),
);

export async function verifyEntraToken(token: string) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: `https://login.microsoftonline.com/${TENANT_ID}/v2.0`,
    audience: 'YOUR_CLIENT_ID', // v2 tokens use the client ID as aud
  });
  if (!String(payload.scp ?? '').split(' ').includes('access_as_user')) {
    throw new Error('Missing scope');
  }
  return payload; // payload.oid is the stable user object ID
}

Für multitenant-Anwendungen enthält der Aussteller jede Kunden-Tenant-ID. Validieren Sie die tid Geltung gegen die Liste der von Ihnen akzeptierten Mieter anstelle eines festen Ausstellers. Schlüsselbenutzer auf oid plus tid, nicht per E-Mail.

Schritt 7: Aktualisierung und Abmeldung

// Get a valid Graph token, refreshing it when it has expired
export async function getGraphToken() {
  const { isLoggedIn } = await SocialLogin.isLoggedIn({ provider: 'oauth2', providerId: 'azure' });
  if (!isLoggedIn) {
    try {
      await SocialLogin.refresh({ provider: 'oauth2', options: { providerId: 'azure' } });
    } catch {
      // no session, or the refresh token expired or was revoked
      const loginResult = await signInWithMicrosoft();
      if (!loginResult) throw new Error('Sign-in cancelled');
    }
  }
  const { accessToken } = await SocialLogin.getAuthorizationCode({ provider: 'oauth2', providerId: 'azure' });
  return accessToken;
}

// Sign out
await SocialLogin.logout({ provider: 'oauth2', providerId: 'azure' });

Kontext: Seite/ Bereich: Über Capgo-Seite. Rolle: Benutzerschnittstelle-Label. Gesehen in: Seite über about.astro. Nachrichtenschlüssel `about_how_step_label` (Über wie Schritt-Label). NativeBiometric.setData from @capgo/capacitor-native-biometrisch@__CAPGO_BEWAHREN_0__/__CAPGO_BEWAHREN_1__-native-biometrisch SocialLogin.refreshToken.

logout clears local tokens and opens the v2.0 logout endpoint in the system browser. Microsoft sometimes shows a “You signed out of your account” page instead of redirecting to a custom scheme, so the user may have to close it. If you only need a local logout, drop logoutUrl und weitergeben prompt: 'select_account' und übergeben Sie

zur nächsten Anmeldung.

Browser-basierte OIDC funktioniert mit MFA, Passwortlosigkeit und den meisten Bedingungen für die Zugriffsberechtigung. Zwei Fälle benötigen mehr:

• Require compliant or hybrid-joined device: Entra muss das Gerätezustand sehen. Auf Android funktioniert dies über Custom Tabs, wenn das Unternehmen oder der Authenticator installiert ist. Auf verwalteten iOS-Geräten stellt der von Ihrem MDM bereitgestellte Microsoft Enterprise SSO-Plug-in es bereit. Testen Sie dies frühzeitig mit einer realen Richtlinie.
• Intune-App-Schutzrichtlinien (MAM): Diese erfordern die Intune-App SDK innerhalb der nativen App. OIDC reicht allein nicht aus, um die „Anforderung einer App-Schutzrichtlinie“ zu erfüllen.

Schadensbegrenzung

Das Entra-Verwaltungszentrum Anmeldeprotokolle zeigt die genaue Fehlerursache für jeden Versuch an und logsEnabled: true in der Plugin-Konfiguration werden die Autorisierungs-URL und der Token-Antwort auf dem Gerät ausgegeben.

Versandaktualisierungen

Änderungen der Richtlinien auf der Entra-Seite sind sofort wirksam, aber Client-Seiten-Fixes müssen noch auf Geräten ankommen. TypeScript-Änderungen wie Berechtigungen oder Fehlerbehandlung können über Capgo Live-UpdatesNative Änderungen (Intent-Filter, neue Schemes) benötigen eine neue Store-Build, die Capgo Build kann ohne einen lokalen Mac erstellt werden.

Verwandte Anleitungen

• How to sign in with Okta using Capacitor
• How to sign in with Auth0 using Capacitor
• Wie man Authentifizierung in eine Capacitor-Anwendung hinzufügt
• Allgemeiner OAuth2-Anbieterverweis