Microsoft

import useBaseUrl from '@docusaurus/useBaseUrl'; import DefaultBehaviour from './_default-behaviour.md'; import OverrideIntro from './_override-intro.md'; import OverrideExampleIntro from './_override-example-intro.md'; import UsingAuthNote from './_using-auth-note.md'; import WaspFileStructureNote from './_wasp-file-structure-note.md'; import GetUserFieldsType from './_getuserfields-type.md'; import ApiReferenceIntro from './_api-reference-intro.md'; import UserSignupFieldsExplainer from '../_user-signup-fields-explainer.md'; import MicrosoftData from '../entities/_microsoft-data.md'; import AccessingUserDataNote from '../_accessing-user-data-note.md'; import SocialLoginClientPages from './_social-login-client-pages.md';

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 {#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.

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:

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

1. Adding Microsoft Auth to Your Wasp File

Let's start by properly configuring the Auth object:

app myApp {
  wasp: {
    version: "{latestWaspVersion}"
  },
  title: "My App",
  auth: {
    // 1. Specify the User entity (we'll define it next)
    // highlight-next-line
    userEntity: User,
    methods: {
      // 2. Enable Microsoft Auth
      // highlight-next-line
      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:

// 3. Define the user entity
model User {
  // highlight-next-line
  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.

1. Go to the Microsoft Entra ID portal. Login or sign up if necessary.

2. In the left sidebar, click on "App registrations" (1) and then "New registration" (2).

3. 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 :::

4. 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.

5. 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).

6. 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!

:::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):

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:

// ...

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.{jsx,tsx} file below.

6. Create the Client Pages

Conclusion

Yay, we've successfully set up 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:

app myApp {
  wasp: {
    version: "{latestWaspVersion}"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      // highlight-next-line
      microsoft: {}
    },
    onAuthFailedRedirectTo: "/login"
  },
}

Overrides

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.

Using the Data Received From Microsoft

app myApp {
  wasp: {
    version: "{latestWaspVersion}"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      microsoft: {
        // highlight-next-line
        configFn: import { getConfig } from "@src/auth/microsoft",
        // highlight-next-line
        userSignupFields: import { userSignupFields } from "@src/auth/microsoft"
      }
    },
    onAuthFailedRedirectTo: "/login"
  },
}

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

// ...

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'],
  }
}

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:

API Reference

app myApp {
  wasp: {
    version: "{latestWaspVersion}"
  },
  title: "My App",
  auth: {
    userEntity: User,
    methods: {
      microsoft: {
        // highlight-next-line
        configFn: import { getConfig } from "@src/auth/microsoft",
        // highlight-next-line
        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.

  tsCopy

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

• userSignupFields: ExtImport

  <UserSignupFieldsExplainer />

  Read more about the userSignupFields function here.