Set up Sign in with Microsoft

Sign in with Microsoft puts a Microsoft button on your hosted sign-in page. The person signs in on Microsoft's own page with a personal account (Outlook, Hotmail) or a work or school account (Microsoft 365), and comes back to your app signed in. It suits business apps whose users work in Microsoft 365. You register an app in Microsoft Entra, the Azure portal's identity service, decide whose accounts it lets in, and swap three values with BuildBase.

What goes where

An application (client) ID looks like 11111111-2222-4333-8444-555555555555. It is not secret. The client secret is, and it expires on the date Microsoft shows beside it.

Whose accounts may sign in

Entra asks this as Supported account types when you register the app. BuildBase's Tenant field must say the same thing:

When the two disagree, Microsoft refuses on its own page, before the person reaches BuildBase.

1. Register the app in Microsoft Entra

These are the steps the console shows under How to get your Microsoft keys.

1. Open App registrations in the Azure portal (it is also in the Microsoft Entra admin center) and choose New registration.
2. Give it your app's name, such as Acme Analytics. Under Supported account types, choose who may sign in, as in the table above. Leave the redirect URI empty for now.
3. Click Register. On the Overview page, copy the Application (client) ID. For a single-tenant app, copy the Directory (tenant) ID too.
4. Open Certificates & secrets and add a New client secret. Microsoft asks how long it lasts. Copy its Value at once (not the Secret ID): it is shown only once.

2. Add Microsoft in the BuildBase console

1. In the console, open User management, then Authentication under Access, and the Methods tab.
2. Press Add auth method and choose Microsoft. The dialog opens How to get your Microsoft keys, the steps above, ending with a reminder that the secret expires.

3. Fill in the form:
   • Title: your own name for the method, shown in the console only. The button always says Microsoft.
   • Client ID: the Application (client) ID.
   • Client secret: the secret's Value.
   • Tenant: leave common, or paste your Directory (tenant) ID or domain for a single-tenant app.
   • Scopes: keep openid profile email User.Read.

The ? beside Tenant sums up the choice:

4. Press Create. The dialog says One step left and shows the Redirect URL. Press Copy, then Done.

5. In Entra, open the same app registration, then Authentication. Add a platform of type Web if there is none, paste the URL as a Redirect URI, and save.

The redirect URL has this shape:

https://api.console.buildbase.app/api/v1/auth/social/microsoft/<orgId>/<methodId>/callback

It starts with your BuildBase server, https://api.console.buildbase.app{/* @endstat */} on BuildBase's cloud. Add it as a Web redirect URI, not a single-page application one. It never changes while the method exists.

3. Attach it to your app

1. Open the Settings tab and press Edit on Acme Analytics.
2. Under Methods, tick Microsoft and press Update.

4. Check the preview

The Preview on the Sign-in page tab shows your look with sample GitHub and Google buttons, whatever your app offers. Press Open the live page for Acme Analytics above it to see the real page with the Microsoft button.

5. What people see

The hosted sign-in and register pages now have a Microsoft button.

Pressing it opens Microsoft's sign-in page. The first time, Microsoft asks the person to accept the permissions your app asks for. Some organizations let only their administrator accept them; then Microsoft says the app needs admin approval, and the administrator grants it for everyone in Entra. Then Microsoft sends the person back, and the sign-in page carries on as after any sign-in: a second step if your two-step policy asks social sign-ins for one, Trust this device?, and the passkey offer if your app offers passkeys.

The first sign-in

• Finding the account: by the person's Microsoft user ID first, then by a verified email address, then as a new account if sign-up is open to them and your plan has room. See who can sign up.
• Personal accounts have verified addresses, so a new account needs no code, and an account made another way with the same address gets Microsoft connected to it.
• Work and school accounts count as verified only when Microsoft's token says so, with the xms_edov or email_verified claim. A directory's administrator can set any address on an account, so BuildBase does not trust one Microsoft has not checked. Without the claim, a new account is asked to type a code emailed to its address at the first sign-in, and someone who already has an account with that address is told to sign in as before and connect Microsoft from the Security screen. Microsoft documents xms_edov as an optional claim you can add under Token configuration on the app registration.
• The ID is per app registration. Microsoft gives the same person a different user ID in each app registration. If you import users with their Microsoft sign-ins, keep the same app registration, or they are found by email instead.

In your app

Nothing changes in your code. People connect Microsoft to an account they made another way, and remove it, on the SDK's Security screen: see Account security screens.

import { useSaaSAuth } from '@buildbase/sdk/react';

export function SecurityButton() {
  const { openWorkspaceSettings } = useSaaSAuth();
  return (
    <button onClick={() => openWorkspaceSettings('security')}>Security</button>
  );
}

Check it works

• Microsoft is in the Login methods list, with the right Tenant.
• The redirect URL is a Web redirect URI on the app registration.
• Microsoft is ticked on your app, and Open the live page shows the button.
• A personal account and a work account (whichever you allow) can each sign in.
• The secret's expiry date is in your calendar.

Things to watch out for

• Tenant and Supported account types must agree. common lets in work, school and personal accounts and needs an app registration that allows all of them. A single-tenant registration with Tenant left on common fails on Microsoft's page with AADSTS50194.
• The secret expires, and nobody warns you. Microsoft allows at most 24 months and recommends less than 12. When it runs out, every Microsoft sign-in fails. Put the date in your calendar and add the new secret before it.
• A work account without an email address on its token signs in with its Microsoft user name. That is often shaped like an address, such as [email protected], but Microsoft says it may not be one, and it does not vouch for it. For a new account, the first sign-in then sends a code to it, which works only if mail reaches that address.
• Work accounts are trusted only with Microsoft's verified claim. Without xms_edov or email_verified on the token, a work account cannot sign in to an account made another way with the same address. The person signs in as before and connects Microsoft from the Security screen.
• Some organizations need their administrator to approve your app. Microsoft then says the app needs admin approval, and the administrator grants it for everyone in Entra.
• User IDs belong to one app registration. Microsoft gives the same person a different ID in each registration. Replace the secret, never the registration: with a new one, people are found only by a verified address.
• Finish at Microsoft within 10 minutes. A sign-in left open on Microsoft's page for more than 10 minutes cannot finish: BuildBase sends the browser to your sign-in page, with a note that the sign-in expired. Start again from your app's Sign in button.

If something goes wrong

This is the page when BuildBase cannot finish with Microsoft, as after a secret has expired:

Next steps

• Social providers - the reference for every provider.
• Two-step sign-in - ask Microsoft sign-ins for a code as well.
• Account security screens - connected accounts inside your app.
• Set up sign-in, step by step - every sign-in guide, and the order to set them up in.