# Set up Sign in with Microsoft Put a Microsoft button on your sign-in page. Register an app in Microsoft Entra, choose whose accounts may sign in, and paste its ID and secret into BuildBase. 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. > **Note:** - A Microsoft account that can register apps in a Microsoft Entra directory (the [Azure portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) or the Microsoft Entra admin center). A free Azure account has one. - An app in the BuildBase console, on the **Settings** tab of **Authentication**. Here it is **Acme Analytics**. - Room on your plan. Microsoft counts toward your plan's limit of social sign-in providers. ## What goes where | Copy this | From | Paste it into | | --------------------------------- | ------------------------------------------ | ---------------------------------------------------- | | Application (client) ID | Entra, the app registration's **Overview** | BuildBase, **Client ID** | | Client secret **Value** | Entra, **Certificates & secrets** | BuildBase, **Client secret** | | Directory (tenant) ID, or nothing | Entra, the app registration's **Overview** | BuildBase, **Tenant** (`common` unless you limit it) | | Redirect URL | BuildBase, after you press **Create** | Entra, **Authentication**, as a **Web** redirect URI | 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: | You want | Supported account types in Entra | **Tenant** in BuildBase | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Anyone with a Microsoft account: personal, work or school | The choice for accounts in any organizational directory **and** personal Microsoft accounts | `common` (the default) | | Only people in your own organization, such as Acme's Microsoft 365 | Accounts in this organizational directory only (single tenant) | Your **Directory (tenant) ID**, or your domain, such as `acme.example` | 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](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) (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. ![The Add new method dialog with Microsoft chosen, and the open guide How to get your Microsoft keys, ending with a reminder that Microsoft client secrets expire](/images/sign-in-setup/microsoft/console-choose.webp) 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 Microsoft form filled in: Title Microsoft, Client ID 11111111-2222-4333-8444-555555555555, Client secret hidden as dots, Tenant common, and the default scopes openid profile email User.Read](/images/sign-in-setup/microsoft/console-form.webp) The **?** beside **Tenant** sums up the choice: ![The note behind the question mark beside Tenant: leave it as common for any Microsoft account, or paste your directory ID or domain to let in only your own organization](/images/sign-in-setup/microsoft/console-field-help.webp) 4. Press **Create**. The dialog says **One step left** and shows the **Redirect URL**. Press **Copy**, then **Done**. ![After Create: One step left, and the Redirect URL box with the address to add as a Web redirect URI in Azure](/images/sign-in-setup/microsoft/console-redirect-url.webp) 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: ```text https://api.console.buildbase.app/api/v1/auth/social/microsoft///callback ``` It starts with your BuildBase server, https://api.console.buildbase.app on BuildBase's cloud. Add it as a **Web** redirect URI, not a single-page application one. It never changes while the method exists. > **Note:** Microsoft client secrets expire. Before the date Entra shows beside yours, add a new secret there, paste its **Value** into the Microsoft method in BuildBase (edit it from its row on the **Methods** tab), and save. Until you do, every Microsoft sign-in fails. ## 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**. ![The Edit auth setting sheet for Acme Analytics, at Methods: Microsoft ticked beside Email and password](/images/sign-in-setup/microsoft/console-attach.webp) ## 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. ![The Preview on the Sign-in page tab, with the button Open the live page for Acme Analytics, and a sample sign-in card whose social buttons are always GitHub and Google](/images/sign-in-setup/google/console-preview.webp) ## 5. What people see The hosted sign-in and register pages now have a **Microsoft** button. ![The hosted sign-in page Sign in to Acme, with the email and password form and, under or, a Microsoft button](/images/sign-in-setup/microsoft/hosted-button.webp) 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](/sign-in-setup/two-step) 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](/sign-in-setup/sign-up-access). - **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](/sign-in-setup/importing-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](/sign-in-setup/account-security-screens). ```tsx import { useSaaSAuth } from '@buildbase/sdk/react'; export function SecurityButton() { const { openWorkspaceSettings } = useSaaSAuth(); return ( ); } ``` ## 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 `jordan@acme.onmicrosoft.com`, 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 | What you see | Why | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Microsoft's page shows an error starting `AADSTS50011` (the redirect URI does not match) | The redirect URL is missing from **Authentication**, or not a **Web** one | Add the URL from the console as a **Web** redirect URI. | | Microsoft's page says the app is not a multi-tenant app (`AADSTS50194`) | The app registration is single tenant, but **Tenant** is `common` | Put your Directory (tenant) ID in **Tenant**, or change **Supported account types**. | | Microsoft's page says the person's account does not exist in the tenant, or they need admin approval | They are outside the directory you allow, or their organization needs an administrator to approve the app | Check **Supported account types** and **Tenant**; ask their administrator to approve the app. | | Sign-in with that provider failed. Please try again. | Microsoft sent the person back, but the code could not be exchanged: most often an expired secret, or the **Secret ID** pasted instead of the **Value** (`provider_failed`) | Add a new client secret and paste its **Value**. | | Sign-in with that provider did not finish. Please try again. | The person cancelled at Microsoft, or Microsoft answered with an error (`provider_error`) | Try again. | | This email is already registered. Sign in the way you did before, then connect this provider from your account's security settings. | An account has this address, and Microsoft did not vouch for it, as with many work accounts (`email_unverified`) | The person signs in as before, then connects Microsoft from the Security screen. | | This provider did not share an email address, so an account cannot be created. Allow access to your email address and try again. | The scopes no longer reach the address (`email_missing`) | Clear the **Scopes** box to go back to the defaults. | | Sign-up is invite-only here, and there is no account for that address yet. Ask the team for an invitation, or sign in with an account you already have. | Public sign-up is off (`signup_disabled`) | Invite the person, or open sign-up. | | Sign-up isn't available for this address. | The address is blocked or not on your allowlist (`signup_restricted`) | Change the lists in **Who may sign up**. | | Join the waitlist, and you can sign up once you're approved. | Sign-up is by waitlist (`waitlist_required`) | Approve them on the waitlist. | | This app is not taking new sign-ups right now. | Your plan's end-user limit is reached (`signup_unavailable`) | Upgrade, or remove users you no longer need. | | Your account has been blocked. Please contact support for assistance. | The account is blocked (`blocked`) | Unblock the user in the console if that was a mistake. | | In the console: Your plan includes 2 social sign-in providers. Upgrade for more, or remove one. | Your plan's social provider limit is reached; the number is your plan's | Upgrade, or delete a provider you no longer use. | This is the page when BuildBase cannot finish with Microsoft, as after a secret has expired: ![The sign-in page back from Microsoft with the message Sign-in with that provider failed. Please try again. above the form, which is still there to try again](/images/sign-in-setup/microsoft/hosted-refused.webp) ## Next steps - [Social providers](/authentication/social-providers#microsoft) - the reference for every provider. - [Two-step sign-in](/sign-in-setup/two-step) - ask Microsoft sign-ins for a code as well. - [Account security screens](/sign-in-setup/account-security-screens) - connected accounts inside your app. - [Set up sign-in, step by step](/sign-in-setup/overview) - every sign-in guide, and the order to set them up in.