# Microsoft Entra ID Emulator (service host)

Create an instance:
curl -s -X POST https://microsoft.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# Microsoft Entra ID Emulator

Stateful Microsoft Entra ID emulator for OAuth 2.0, OpenID Connect, client credentials, and a curated Microsoft Graph subset covering users, mail, calendar, and OneDrive.

Provider base URL: https://microsoft.your-instance.emulators.dev
Control base URL: https://microsoft.your-instance.emulators.dev/_emulate

Supported surfaces:
- Microsoft Graph (subset): partial at /v1.0
- Microsoft OAuth 2.0: supported at /oauth2/v2.0
- OpenID Connect: supported at /.well-known

Control endpoints:
- https://microsoft.your-instance.emulators.dev/_emulate/manifest
- https://microsoft.your-instance.emulators.dev/_emulate/coverage
- https://microsoft.your-instance.emulators.dev/_emulate/connections
- https://microsoft.your-instance.emulators.dev/_emulate/state
- https://microsoft.your-instance.emulators.dev/_emulate/ledger
- https://microsoft.your-instance.emulators.dev/_emulate/faults
- POST https://microsoft.your-instance.emulators.dev/_emulate/credentials
- POST https://microsoft.your-instance.emulators.dev/_emulate/seed
- POST https://microsoft.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://microsoft.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## MSAL Node (TypeScript)
import { ConfidentialClientApplication } from "@azure/msal-node";

const app = new ConfidentialClientApplication({
  auth: {
    clientId: "<client_id>",
    clientSecret: "<client_secret>",
    authority: "https://microsoft.your-instance.emulators.dev/common/v2.0",
  },
});

const token = await app.acquireTokenByClientCredential({
  scopes: ["https://graph.microsoft.com/.default"],
});

## Microsoft Graph client (fetch)
const res = await fetch("https://microsoft.your-instance.emulators.dev/v1.0/me/messages", {
  headers: { authorization: "Bearer <token>" },
});
const messages = await res.json();

## Entra ID environment (env)
AZURE_AUTHORITY_HOST=https://microsoft.your-instance.emulators.dev
AZURE_TENANT_ID=common
AZURE_CLIENT_ID=<client_id>
AZURE_CLIENT_SECRET=<client_secret>
MICROSOFT_GRAPH_ENDPOINT=https://microsoft.your-instance.emulators.dev/v1.0

## curl (OIDC discovery)
curl -s https://microsoft.your-instance.emulators.dev/.well-known/openid-configuration

## curl (Graph /me)
curl -s https://microsoft.your-instance.emulators.dev/v1.0/me -H "authorization: Bearer <token>"

## Base URL (env)
MICROSOFT_BASE_URL=https://microsoft.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://microsoft.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"oauth-authorization-code"}'

## Inspect requests
curl -s https://microsoft.your-instance.emulators.dev/_emulate/ledger