Microsoft OAuth
Learn how to set up OAuth with Microsoft
The Microsoft OAuth integration allows your users to authenticate using their Microsoft credentials through the “Sign in with Microsoft” flow.
The configuration process involves creating or configuring an application in Microsoft Azure and setting up OAuth permissions with the client credentials in the WorkOS Dashboard.
WorkOS provides a default Microsoft Client ID and 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 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 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 Client Secret for the OAuth flow, you will have the opportunity to customize the app, including its name, logo, contact email, etc.
When setting up Microsoft OAuth, WorkOS provides one key piece of information that needs to be configured in your Microsoft Azure application:
- Redirect URI: The endpoint where Microsoft will send authentication responses after successful login
The Redirect URI is available in the WorkOS Dashboard. In the left navigation menu, select Authentication tab and the OAuth providers sub-tab. Locate the Microsoft section.
Click Manage. The Microsoft OAuth configuration dialog will open. Locate the Redirect URI.
The Redirect URI serves as the destination for authentication responses and must be configured in your Microsoft Azure application’s authentication settings.
You will need to obtain two pieces of information from a Microsoft Azure application:
- Microsoft Client ID: Application identifier from Microsoft Azure
- Microsoft Client Secret: Authentication secret for the application
The following sections will guide you through creating an application in your Microsoft Azure Portal and generating these credentials.
IMPORTANT: When registering your app, select Personal Microsoft accounts only for Supported Account Types.
Sign in to the Microsoft Azure Portal and navigate to Microsoft Entra ID from the left hand navigation.
If you don’t already have an application, click App registrations and then New registration to create one. When registering, you must select Personal Microsoft accounts only for Supported Account Types.
If you already have an application, select App registrations and then select your relevant application.
Select the Authentication option for the application. In the Redirect URIs section, add the Redirect URI from the WorkOS Dashboard.
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.
To get the Microsoft Client Secret, navigate to Certificates & secrets and click on New client secret. Give the 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.
Copy the new client secret as you’ll need it for the WorkOS configuration.
To obtain the Microsoft Client ID, navigate to the Overview tab of your application and copy the Application (client) ID.
Now that you have the Microsoft Client ID and Microsoft Client Secret from the previous steps, return to the WorkOS Dashboard.
In the Microsoft OAuth configuration dialog, select Your app’s credentials. Paste the credentials from Microsoft into their respective fields in the WorkOS Dashboard.
Click Save to complete the configuration.
After that, you’re now able to authenticate users with Microsoft OAuth. 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.
How is the WorkOS Microsoft OAuth integration different from implementing regular Microsoft OAuth flow?
It’s the same Microsoft OAuth flow as you could build yourself, but it’s encapsulated within WorkOS SSO. This means you don’t need to build it yourself. In addition to Microsoft OAuth, you can use WorkOS SSO to support other identity providers, all with a single integration.
What is the provider query parameter and how is it used in the Microsoft OAuth integration?
You can 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. This is necessary because Microsoft OAuth does not take a user’s domain into account when logging in with a “Sign in with Microsoft” button.
Why do I need to select “Personal Microsoft accounts only” for account types?
This setting is required for the WorkOS integration to function properly. It ensures that the OAuth flow works with personal Microsoft accounts rather than organizational accounts, which have different authentication requirements.
How long do Microsoft client secrets last?
Microsoft’s client secrets have an expiration date, with the maximum value being 24 months. You will need to track these and rotate them before the expiration time to maintain continuous authentication functionality.