Iniciar sesión con Microsoft Entra ID (Azure AD) en Capacitor

Para iniciar sesión con Microsoft Entra ID (anteriormente Azure Active Directory) en una Capacitor aplicación, regístrese en la central de administración de Entra, agregue un Aplicaciones móviles y de escritorio una URI de redirección como com.example.app://oauth/azure, y ejecutar el flujo de autorización OpenID Connect code con PKCE a través del navegador del sistema. Con @capgo/capacitor-social-login que significa una initialize llamada con los puntos finales de la plataforma de identidad de Microsoft v2.0 y SocialLogin.login({ provider: 'oauth2', options: { providerId: 'azure' } }).

Esta guía cubre la inscripción de la aplicación, la elección de la autoridad correcta, el Gráfico y los ámbitos de API personalizados, la validación de tokens, el acceso condicional, la salida, y los errores AADSTS que verá. Se dirige a Capacitor 8 en octubre de 2026.

¿Qué necesitas?

• Un inquilino de Microsoft Entra y un rol que pueda crear inscripciones de aplicaciones (Desarrollador de aplicaciones o superior).
• Una aplicación Capacitor 8 y sus appId, que reutilizará como esquema de redirección.
• Opcionalmente, un backend API que deba aceptar tokens de Entra.

No MSAL.js dentro del WebView

MSAL.js está diseñado para navegadores que poseen su origen y pueden abrir ventanas emergentes. En un WebView Capacitor el origen es capacitor://localhost en iOS y https://localhost en Android, los pop-ups están bloqueados, y un redireccionamiento de página completa te llevaría a tu aplicación fuera de su propio paquete. La guía de Microsoft para aplicaciones nativas es el navegador del sistema con PKCE (RFC 8252), lo que hace el plugin:

On Android, active Custom Tabs. El navegador incorporado por defecto no puede comunicarse con Microsoft Authenticator, claves de acceso o el Portal de la empresa, que a menudo se basa en el acceso condicional.

Step 1: Registra la aplicación en Entra ID

1. Abre el Centro de administración de Microsoft Entra y ve a Entra ID > Registros de aplicaciones > Nueva registro.
2. Introduce un nombre, como “Ejemplo móvil”.
3. Elige Tipos de cuentas admitidas. Esto decide la autoridad que usarás más tarde.
4. Skip the redirect URI for now and click Registra.
5. On Resumen, copie los ID de la aplicación (cliente) y ID de directorio (inquilino).

Seleccione la autoridad

Utiliza el ID de inquilino siempre que puedas. Produce emisores predecibles y evita ingresos accidentales desde otros inquilinos.

Agregar direcciones de redireccionamiento

Ir a Autenticación > Agregar una plataforma:

• Aplicaciones móviles y de escritorio: agregar com.example.app://oauth/azure como una dirección de redireccionamiento personalizada. Agregar com.example.app://oauth/logout si quieres una redirección después de cerrar sesión
• Aplicación de una sola página (solo si envías una compilación web): agregar https://app.example.com/auth/callback.

Do no registre la URI móvil bajo Web. Las plataformas web redirigen a clientes confidenciales y requieren un secreto en el punto de conexión de tokens.

API permisos

API permisos already contains Microsoft Graph > User.Read. Agregar offline_access, openid, profile y email si no están listados. Algunos inquilinos bloquean el consentimiento del usuario. En ese caso, un administrador debe hacer clic en Conceder consentimiento de administrador, de lo contrario, los usuarios ven una pantalla de "AADSTS65001" o "Need admin approval".

Exponer un alcance para su propio API (opcional)

Si su backend debe aceptar el token:

1. Abrir Exponga un API y establezca la URI de la aplicación, típicamente api://<client-id>.
2. Agregar un ámbito denominado access_as_user, who can consent: Admins and users.
3. En Manifiestoestablezca "requestedAccessTokenVersion": 2 Los tokens de acceso utilizan el formato de emisor v2.0.

Paso 2: Instale el complemento y agregue el filtro de intención

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

En android/app/src/main/AndroidManifest.xml, dentro de 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>

Sigue android:launchMode="singleTask" en MainActivity (si no utilizas Google, Apple o Facebook para iniciar sesión, desactiva estos en el Capacitor) plugins.SocialLogin.providers en capacitor.config.ts para mantener sus SDKs fuera de la compilación.

Paso 3: Inicialice el proveedor de Entra ID

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

With resourceUrl puntando a Graph /medespués de la autenticación, el plugin llama a Graph y devuelve el perfil en resourceData.

Si está migrando desde Ionic Auth Connect, SocialLoginAuthConnect tiene azure preset que solo necesita tenantId, clientId y redirectUrlver el página de integración de Entra ID.

Paso 4: Iniciar sesión

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

Opciones útiles:

• loginHint: 'jane@contoso.com' rellena automáticamente la cuenta y salta al selector de cuenta para ese usuario.
• prompt: 'select_account' siempre muestra el selector de cuenta, útil para dispositivos compartidos.
• additionalParameters: { domain_hint: 'contoso.com' } envía a los usuarios directamente a su IdP federado.

mail es a menudo null para cuentas sin bandeja de entrada. Recurso a userPrincipalName o el preferred_username afirmación del token de ID.

Paso 5: Llamar a 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();
}

Agregar cada ámbito de Graph que necesites (por ejemplo) Calendars.Read) ambos en API permisos y en la scope cadena.

Paso 6: Obtener un token para tu propio API

Un token de acceso apunta a un recurso. Para llamar a tu backend, agrega una segunda entrada junto a azure en el mismo oauth2 mapa de tu initialize llamada, solicitando tu API ámbito en lugar de Graph:

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

El usuario ya tiene una sesión de Microsoft, por lo que la segunda autenticación suele completarse sin una solicitud. Verificar el token en el servidor:

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
}

Para aplicaciones multitenant, el emisor contiene el ID de inquilino de cada cliente. Valida el tid reclamo contra la lista de inquilinos que aceptas en lugar de un emisor fijo. Los usuarios clave están en oid plus tid, no en correo electrónico.

Paso 7: Refrescar y salir

// 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' });

Los tokens de refresco de Entra para clientes públicos duran hasta 90 días con una ventana deslizante y se reemplazan en cada uso. El plugin almacena el nuevo. Si almacenas tokens tú mismo, utiliza la Keychain o Keystore, por ejemplo NativeBiometric.setData desde @capgo/capacitor-nativo-biometria, and pass them to SocialLogin.refreshToken.

logout elimina tokens locales y abre el punto de conexión de salida v2.0 en el navegador del sistema. Microsoft a veces muestra una página de "Has cerrado sesión en tu cuenta" en lugar de redirigir a un esquema personalizado, por lo que el usuario puede tener que cerrarla. Si solo necesitas una salida local, elimina logoutUrl y pasa prompt: 'select_account' en el próximo inicio de sesión.

Acceso condicional e Intune

Funciona con autenticación multifactor, sin contraseñas y la mayoría de las políticas de acceso condicional. Dos casos requieren más:

• Requiere dispositivo compatible o unido de forma híbrida: Entra debe ver el estado del dispositivo. En Android esto funciona a través de Custom Tabs cuando se instala el Portal de la empresa o el Autenticador. En dispositivos iOS gestionados, el complemento de inicio de sesión empresarial de Microsoft proporcionado por su MDM lo proporciona. Pruebe esto temprano con una política real.
• Políticas de protección de aplicaciones Intune (MAM): estas requieren la aplicación de Intune SDK dentro de la aplicación nativa. El OIDC solo no satisface las

Troubleshooting

Centro de administración de Entra Registros de inicio de sesión muestre la razón exacta de falla para cada intento, y logsEnabled: true imprime la URL de autorización y la respuesta del token en el dispositivo.

Actualizaciones de envío

Los cambios de política en el lado de Entra son instantáneos, pero las correcciones en el lado del cliente todavía necesitan llegar a los dispositivos. Los cambios de TypeScript como ámbitos o manejo de errores pueden enviarse a través de actualizaciones en vivo CapgoNative cambios (filtros de intención, nuevos esquemas) requieren una nueva compilación de la tienda, que Capgo Construcción puede producir sin un Mac local.

Guías relacionadas

• Cómo iniciar sesión con Okta utilizando Capacitor
• Cómo iniciar sesión con Auth0 utilizando Capacitor
• Cómo agregar autenticación a una aplicación Capacitor
• Referencia del proveedor de OAuth2 genérico