Sign in with Microsoft.
Ten minutes. One app registration in Microsoft Entra ID lets people sign in with a personal Microsoft account (Outlook.com, Xbox), a work or school account, or both. You decide which, and Auth checks it on every sign-in.
1
Open the guided setup
In the console, open Auth, pick your app, then Settings. Under Federated sign-in providers, select Set up on the Microsoft row.
The page opens on Set up Microsoft sign-in: five numbered steps with your app's values filled in. Create the app registration, paste the redirect URI, scopes, paste the credentials and save, Try sign-in.
2
Register an app in Microsoft Entra ID
Step 1 links to App registrations in the Microsoft Entra admin center. Select New registration.
- Name: your product. Microsoft shows it on the consent screen.
- Supported account types: "Accounts in any organizational directory and personal Microsoft accounts" lets everyone in. Pick a narrower type if you only want work accounts, only personal accounts, or only your own organization; you set the same choice in Auth in step 3.
- Redirect URI: platform Web, and the URL from step 2 in the console. Use the Copy button. It looks like this, with your app's slug:
https://api.auth.productcraft.co/<your-app-slug>/v1/auth/oauth/microsoft/callbackSelect Register. On the app's Overview, copy the Application (client) ID. Then open Certificates & secrets, select New client secret and copy its Value (not the Secret ID). Microsoft shows the value once, and every secret has an expiry date: note it.
Scopes
Nothing to grant. Auth asks for openid, email and profile, the standard sign-in permissions every app registration already has.
3
Paste the credentials, choose who may sign in, save
Step 4 points at the form under the steps.
Paste the Application (client) ID and the secret value, then choose under Who can sign in:
- Everyone (
common): personal and work or school accounts. - Work or school accounts (
organizations): any organization, no personal accounts. - Personal accounts (
consumers). - One organization: its Directory (tenant) ID, or a domain verified in it such as
contoso.com. Auth looks up the directory of a domain when you save.
With Everyone or Work or school accounts you can also list Allowed organizations by directory ID: work accounts from any other organization are then refused. Auth checks the directory of every sign-in against these settings itself, so a broader app registration at Microsoft never widens who gets in.
When you save, Auth sends Microsoft's token endpoint a code that cannot work and reads the answer:
- Rejected:
invalid_clientmeans the secret is wrong or expired (paste a new Value);unauthorized_clientmeans Microsoft did not find the Application ID, often because Supported account types does not include the directory you chose. Sign-in stays blocked until this is fixed. - Could not check: Microsoft usually refuses the made-up code before it looks at the app, so it cannot confirm a correct ID and secret this way. Nothing is blocked; Try sign-in (next step) is the real proof.
The same settings over the API (the secret is write-only):
curl -X PUT https://api.auth.productcraft.co/v1/apps/<your-app-id>/auth-config/providers/microsoft \
-H "Authorization: Bearer <your-workspace-api-key>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"client_id": "<application-client-id>",
"client_secret": "<client-secret-value>",
"tenant": "common",
"allowed_tenant_ids": []
},
"enabled": false
}'4
Try sign-in, then switch it on
Step 5 runs the whole round trip in a small window and shows who would have signed in. No account is created and no token is issued.
A redirect URI that differs shows as redirect_uri_mismatch with the exact URL to paste. When the test passes, switch on Enabled and save, and make sure the site your users sign in from is under Allowed redirect origins on the app's Settings.
5
Add the button to your site
A link to Auth and one server-side call, as with every provider.
<a href="https://api.auth.productcraft.co/<your-app-slug>/v1/auth/oauth/microsoft/authorize?return_to=https%3A%2F%2Fapp.acme.com%2Flogin%2Fdone">
Sign in with Microsoft
</a>Microsoft always shows its account picker, so people signed in to several accounts choose the right one. They come back to your return_to with ?heimdall_code=…, which your backend swaps for tokens:
import { Auth, AuthenticationError } from "@productcraft/auth";
const consumer = new Auth().consumer("acme");
async function completeProviderSignIn(code: string) {
try {
// code: the heimdall_code query value
const { access_token, refresh_token, expires_in } =
await consumer.exchangeProviderCode({ code });
// Drop into your session cookie / store as you'd handle a sign-in.
return { access_token, refresh_token, expires_in };
} catch (err) {
// 401: unknown, expired or already used
if (err instanceof AuthenticationError) return null;
throw err;
}
}6
Emails from work accounts
Why a work account can sign in with its email marked unverified.
In a work or school directory, an administrator can type any address into a user's email field, so Microsoft does not vouch for it. Auth treats the email of a personal account as verified, and the email of a work account as verified only when Microsoft sends the xms_edov claim (the organization verified the email's domain). To get it, open Token configuration on the app registration, select Add optional claim, token type ID, and add xms_edov.
This matters for account linking: with the auto linking policy, only a verified email links to an existing account. The user's ID in Auth is Microsoft's sub, which stays the same for that person in your app whatever their email.
Native apps
An iOS, Android or desktop app that signs in with MSAL can send the ID token to POST /<your-app-slug>/v1/auth/oauth/microsoft with the raw nonce, the same way as Apple and Google. List the native app registrations' client IDs under Native apps first; without them the endpoint answers 400.