Version: 0.21

Microsoft

Wasp supports Microsoft Authentication out of the box.

Microsoft Auth uses Microsoft Entra ID as the identity provider. This lets your users sign in with their Microsoft accounts — including personal Microsoft accounts, work/school (Microsoft 365) accounts, or both, depending on your configuration.

Let's walk through enabling Microsoft authentication, explain some of the default settings, and show how to override them.

Understanding tenants

When setting up Microsoft Authentication, you'll encounter the concept of "tenants". A tenant represents an organization in Microsoft Entra ID. Depending on the supported account types you choose during app registration, your app will be associated with a specific tenant, or be multi-tenant.

When planning out your Microsoft integration, you have to decide which kind of accounts will be able to sign in. This will determine the tenant ID you use in your configuration, and the users that can sign in to your app.

Supported Account Types	Tenant ID Value	Description	Best for
Tenant-specific	Your Tenant ID (generated by Microsoft)	Only users in your Microsoft Entra ID tenant can sign in.	Internal-only apps for a specific organization.
Organization accounts	`organizations`	Any user with a "work or school" Microsoft account can sign in, but not personal accounts.	B2B apps targeting users in other organizations.
Personal accounts	`consumers`	Only personal Microsoft accounts (e.g., Outlook.com, Hotmail, Xbox) can sign in.	Consumer-facing apps targeting individual users.
All of the above	`common`	Both organizational accounts and personal Microsoft accounts can sign in.	Apps that can be used by personal, work, and school accounts.

We recommend choosing the least-permissive option that fits your use case, as Microsoft might require you to submit to a verification process if you want to use the higher-privileged tenant types in production.

Setting up Microsoft Auth

Enabling Microsoft Authentication comes down to a series of steps:

Enabling Microsoft authentication in the Wasp file.
Adding the User entity.
Creating a Microsoft Entra ID app registration.
Adding the necessary Routes and Pages
Using Auth UI components in our Pages.

Here's a skeleton of how our main.wasp should look like after we're done:

main.wasp
// Configuring the social authentication
app myApp {
  auth: { ... }
}

// Defining routes and pages
route LoginRoute { ... }
page LoginPage { ... }

1. Adding Microsoft Auth to Your Wasp File

Let's start by properly configuring the Auth object:

main.wasp
app myApp {
  wasp: {
    version: "^0.21"
  },
  title: "My App",
  auth: {
    // 1. Specify the User entity (we'll define it next)
    userEntity: User,
    methods: {
      // 2. Enable Microsoft Auth
      microsoft: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

userEntity is explained in the social auth overview.

2. Adding the User Entity

Let's now define the app.auth.userEntity entity in the schema.prisma file:

schema.prisma
// 3. Define the user entity
model User {
  id Int @id @default(autoincrement())
  // Add your own fields below
  // ...
}

3. Creating a Microsoft Entra ID App Registration

To use Microsoft as an authentication method, you'll first need to register an application in the Microsoft Entra ID portal and provide Wasp with your client ID, client secret, and tenant ID.

Go to the Microsoft Entra ID portal. Login or sign up if necessary.
In the left sidebar, click on "App registrations" (1) and then "New registration" (2).
Fill out the form. These are the values for a typical Wasp application:

# Field Value
1 Name (your wasp app name)
1 Supported account types Read through Understanding tenants
3 Authorized redirect URIs Web: http://localhost:3001/auth/microsoft/callback

note
Once you know on which URL(s) your API server will be deployed, also add those URL(s) in the Authentication section.
For example: https://your-server-url.com/auth/microsoft/callback
You should now see your app registration's overview page. Take note of the Application (client) ID (1) and the Directory (tenant) ID (2), as you'll need them in the next steps.
Next, go to the "Certificates & secrets" (1) page from the left sidebar, and create a new client secret (2). You can fill out the name of your Wasp app as the client secret's name (3).
Finally, take note of the client secret's value, as you'll need it in the next steps. Make sure to copy it somewhere safe, as you won't be able to see it again!

#	Field	Value
1	Name	(your wasp app name)
1	Supported account types	Read through Understanding tenants
3	Authorized redirect URIs	Web: `http://localhost:3001/auth/microsoft/callback`

info

The keys you copied are the credentials your app will use to authenticate with Microsoft. Do not share them anywhere publicly, as anyone with these credentials can impersonate your app and access user data.

4. Adding Environment Variables

Add these environment variables to the .env.server file at the root of your project (take their values from the previous step):

.env.server
MICROSOFT_TENANT_ID=your-microsoft-tenant-id
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret

The MICROSOFT_TENANT_ID should be set based on the supported account types you chose, as described in the Understanding Tenant IDs section above.

5. Adding the Necessary Routes and Pages

Let's define the necessary authentication Routes and Pages.

Add the following code to your main.wasp file:

main.wasp
// ...

route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
  component: import { Login } from "@src/pages/auth"
}

We'll define the React components for these pages in the src/pages/auth.tsx file below.

6. Create the Client Pages

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's now create an auth.tsx file in the src/pages. It should have the following code:

JavaScript
TypeScript

src/pages/auth.jsx
import { LoginForm } from "wasp/client/auth";

export function Login() {
  return (
    <Layout>
      <LoginForm />
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }) {
  return (
    <div className="h-full w-full bg-white">
      <div className="flex min-h-[75vh] min-w-full items-center justify-center">
        <div className="h-full w-full max-w-sm bg-white p-5">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

src/pages/auth.tsx
import type { ReactNode } from "react";
import { LoginForm } from "wasp/client/auth";

export function Login() {
  return (
    <Layout>
      <LoginForm />
    </Layout>
  );
}

// A layout component to center the content
export function Layout({ children }: { children: ReactNode }) {
  return (
    <div className="h-full w-full bg-white">
      <div className="flex min-h-[75vh] min-w-full items-center justify-center">
        <div className="h-full w-full max-w-sm bg-white p-5">
          <div>{children}</div>
        </div>
      </div>
    </div>
  );
}

Auth UI

Our pages use an automatically generated Auth UI component. Read more about Auth UI components here.

Conclusion

Yay, we've successfully set up Microsoft Auth! 🎉

Microsoft Auth

Running wasp db migrate-dev and wasp start should now give you a working app with authentication. To see how to protect specific pages (i.e., hide them from non-authenticated users), read the docs on using auth.

Default Behaviour

Add microsoft: {} to the auth.methods dictionary to use it with default settings:

main.wasp
app myApp {
  wasp: {
    version: "^0.21"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      microsoft: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

When a user signs in for the first time, Wasp creates a new user account and links it to the chosen auth provider account for future logins.

Overrides

By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider.

There are two mechanisms used for overriding the default behavior:

userSignupFields
configFn

Let's explore them in more detail.

Data Received From Microsoft

We are using Microsoft's Graph API and its /oidc/userinfo endpoint to fetch the user's data.

The data received from Microsoft is an object which can contain the following fields:

{
  "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
  "name": "Mikah Ollenburg", // all names require the “profile” scope.
  "family_name": " Ollenburg",
  "given_name": "Mikah",
  "picture": "https://graph.microsoft.com/v1.0/me/photo/$value",
  "email": "[email protected]" // requires the “email” scope.
}

The fields you receive depend on the scopes you request. The default scopes are set to openid, profile, and email.

For up-to-date info about the data received from Microsoft, please refer to the Microsoft Graph API documentation.

Using the Data Received From Microsoft

When a user logs in using a social login provider, the backend receives some data about the user. Wasp lets you access this data inside the userSignupFields getters.

For example, the User entity can include a displayName field which you can set based on the details received from the provider.

Wasp also lets you customize the configuration of the providers' settings using the configFn function.

Let's use this example to show both fields in action:

main.wasp
app myApp {
  wasp: {
    version: "^0.21"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      microsoft: {
        configFn: import { getConfig } from "@src/auth/microsoft",
        userSignupFields: import { userSignupFields } from "@src/auth/microsoft"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

schema.prisma
model User {
  id          Int    @id @default(autoincrement())
  username    String @unique
  displayName String
}

// ...

JavaScript
TypeScript

src/auth/microsoft.js
import { defineUserSignupFields } from "wasp/server/auth";

export const userSignupFields = defineUserSignupFields({
  username: () => "hardcoded-username",
  displayName: (data) => data.profile.name,
});

export function getConfig() {
  return {
    scopes: ["openid", "profile", "email"],
  };
}

src/auth/microsoft.ts
import { defineUserSignupFields } from "wasp/server/auth";

export const userSignupFields = defineUserSignupFields({
  username: () => "hardcoded-username",
  displayName: (data: any) => data.profile.name,
});

export function getConfig() {
  return {
    scopes: ["openid", "profile", "email"],
  };
}

Wasp automatically generates the defineUserSignupFields function to help you correctly type your userSignupFields object.

Using Auth

To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on using auth.

When you receive the user object on the client or the server, you'll be able to access the user's Microsoft ID like this:

const microsoftIdentity = user.identities.microsoft

// Microsoft User ID for example "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
microsoftIdentity.id

Read more about accessing the user data in the Accessing User Data section of the docs.

API Reference

Provider-specific behavior comes down to implementing two functions.

configFn
userSignupFields

The reference shows how to define both.

For behavior common to all providers, check the general API Reference.

main.wasp
app myApp {
  wasp: {
    version: "^0.21"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      microsoft: {
        configFn: import { getConfig } from "@src/auth/microsoft",
        userSignupFields: import { userSignupFields } from "@src/auth/microsoft"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

The microsoft dict has the following properties:

`configFn: ExtImport`

This function must return an object with the scopes for the OAuth provider.

JavaScript
TypeScript

src/auth/microsoft.js
export function getConfig() {
  return {
    scopes: ["openid", "profile", "email"],
  };
}

src/auth/microsoft.ts
export function getConfig() {
  return {
    scopes: ["openid", "profile", "email"],
  };
}

`userSignupFields: ExtImport`

userSignupFields defines all the extra fields that need to be set on the User during the sign-up process. For example, if you have address and phone fields on your User entity, you can set them by defining the userSignupFields like this:

JavaScript
TypeScript

src/auth.js
import { defineUserSignupFields } from "wasp/server/auth";

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error("Address is required");
    }
    return data.address;
  },
  phone: (data) => data.phone,
});

src/auth.ts
import { defineUserSignupFields } from "wasp/server/auth";

export const userSignupFields = defineUserSignupFields({
  address: (data) => {
    if (!data.address) {
      throw new Error("Address is required");
    }
    return data.address;
  },
  phone: (data) => data.phone,
});

Read more about the userSignupFields function here.

Understanding tenants​

Setting up Microsoft Auth​

1. Adding Microsoft Auth to Your Wasp File​

2. Adding the User Entity​

3. Creating a Microsoft Entra ID App Registration​

4. Adding Environment Variables​

5. Adding the Necessary Routes and Pages​

6. Create the Client Pages​

Conclusion​

Default Behaviour​

Overrides​

Data Received From Microsoft​

Using the Data Received From Microsoft​

Using Auth​

API Reference​

configFn: ExtImport​

userSignupFields: ExtImport​