WorkOS Docs Homepage
Integrations

Microsoft OAuth

Learn how to set up OAuth with Microsoft.

To configure your global Microsoft OAuth setup, you’ll need three pieces of information: a Redirect URI, a Microsoft Client ID, and a Microsoft Client Secret.

WorkOS provides the Redirect URI, an allowlisted callback URL. It indicates the location to return an authorized user to after both an authorization code is granted, and the authentication process is complete.

Open your WorkOS Dashboard, and browse to the “Configuration” tab on the left hand nav bar. Scroll down to the “Microsoft OAuth” section, click "Edit Microsoft OAuth", and you’ll see the Redirect URI as well as the fields you’ll populate later with information from Microsoft. If you are in the Staging environment, you'll see demo values for the Client ID and Client Secret.

A screenshot showing where to find the Microsoft OAuth Redirect URI field in the WorkOS Dashboard.

WorkOS provides a default Microsoft Client ID/Microsoft Client Secret combination, which allows you to quickly enable and test Microsoft OAuth. Use the WorkOS API to initiate SSO, setting the provider parameter to MicrosoftOAuth, and WorkOS will automatically use the default credentials, until you add your own Microsoft Client ID and Microsoft Client Secret to the Configuration in the WorkOS Dashboard.

The default credentials are only intended for testing and therefore only available in the Staging environment. For your production environment, please follow the steps below to create and specify your own Microsoft Client ID and Microsoft Client Secret.

Please note that when you are using WorkOS default credentials, Microsoft's authentication flow will display WorkOS' name, logo, and other information to users. Once you register your own application and use its Microsoft Client ID and Microsoft Client Secret for the OAuth flow, you will have the opportunity to customize the app, including its name, logo, contact email, etc.

If you haven’t already, be sure to register an application with Microsoft following their documentation.

IMPORTANT: When registering your app, select “Accounts in any organizational directory (Any Azure AD directory – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)” for “Supported Account Types”.

A screenshot showing the "Supported Account Types" setting in the Microsoft Azure Dashboard.

Then, you’ll provide the Microsoft Client ID and the Microsoft Client Secret to the WorkOS Dashboard Configuration. These are a pair of credentials provided by Microsoft that you’ll use to authenticate your application via Microsoft’s OAuth protocol. To obtain them:

Log in to the Microsoft Azure Portal. Select “Azure Active Directory” from the left hand navigation. Then select “App registrations” and select your relevant application.

A screenshot showing where to select an application in the Azure Portal.

Select the “Authentication” option for the application. In the “Redirect URIs” section, add the Redirect URI provided for you in the Microsoft OAuth section of the WorkOS Dashboard Configuration.

A screenshot showing where to enter the Redirect URI in the Azure App Settings.

Under “Token configuration”, select “Add optional claim”. Select email, family_name and given_name.

In order for the email claim to come through, the “Email” field for the user in Azure needs to be populated.

A screenshot showing where to add claims in the Azure App Settings.

You’ll need to add your Microsoft Client ID and Microsoft Client Secret to their respective fields in your Microsoft OAuth settings.

To get your Microsoft Client Secret, navigate to “Certificates & secrets” and click on “New client secret”. Give your client secret a Description and select “Add”.

Microsoft’s client secrets have an expiration date, with the highest value being 24 months. You will need to track these and rotate them before the expiration time.

A screenshot showing where to create a client cecret in the Azure AD App Settings.

Copy your new client secret to the clipboard in order to add it to the WorkOS Dashboard.

A screenshot showing where to copy the Azure AD Client Secret.

To obtain the Microsoft Client ID, navigate to the “Overview” tab of your application and copy the “Application (client) ID”.

A screenshot showing where to copy the Azure AD Client ID.

In the Microsoft OAuth section of your WorkOS Dashboard Configuration, click “Edit Microsoft OAuth”.

A screenshot showing the "Edit Microsoft OAuth" button in the WorkOS Dashboard

Add the Microsoft Client ID and Microsoft Client Secret and click “Save Microsoft OAuth”.

A screenshot showing where to enter Microsoft OAuth client credentials into the WorkOS Dashboard.

After that, you’re now able to authenticate users with Microsoft OAuth. Provide the provider parameter when authenticating Microsoft OAuth users, because Microsoft OAuth does not take a user’s domain into account when logging in with a “Sign in with Microsoft” button. You will use the provider query parameter in the Get Authorization URL API endpoint to support global Microsoft OAuth for any domain. The provider query parameter should be set to MicrosoftOAuth.