Connect Microsoft OAuth
Learn how to configure a connection to Microsoft via OAuth
Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.
To create a Microsoft OAuth Connection, you'll need three pieces of information: a Redirect URI, a Microsoft Client ID, and a Microsoft Client Secret.
Start by logging in to your WorkOS dashboard and browse to the “Organizations” tab on the left hand navigation bar.
Select the organization you'd like to configure a Microsoft OAuth Connection for, and add a connection under 'Single Sign-On Connections'.
You'll be prompted to enter the Organization's Domain and additionally you'll want to select "Microsoft OAuth" from the Identify Provider dropdown. Once this is filled out, click "Create Connection".
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. It's readily available in your Configuration Settings in the Developer Dashboard.
Simply open your Developer Dashboard, click the “Configuration” tab on the left hand nav bar. Scroll down to the “Microsoft OAuth”section and select “Setup Microsoft OAuth”. You'll then see the Redirect URI as well as the fields you'll populate later with information from Microsoft.
If you haven’t already, be sure to register an application with Microsoft following Microsoft's instructions here.
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".
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:
1Log In and Select Your Application
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.
2Enter WorkOS Redirect URI
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.
Under “Token configuration”, select “+ Add optional claim”. Select “email”, “family_name” and “given_name”.
NOTE: In order for the email claim to come through, the “Email” field for the user in Azure needs to be populated.
4Obtain Identity Provider Details
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”.
NOTE: 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 your new client secret to the clipboard in order to add it to the WorkOS Dashboard.
To obtain the Microsoft Client ID, navigate to the “Overview” tab of your application and copy the “Application (client) ID”.
Add the Microsoft Client ID and Microsoft Client Secret to the Microsoft OAuth section of your WorkOS Dashboard Configuration and click “Update configuration”.
5Associate a Domain with your Connection
Should you need to make any edits to the domains associated to your connection, like adding or removing, you can do this by clicking on the 'Domains' tab at the Organization level.
Since you've already configured the Global IdP settings for your Microsoft Connection, your Connection should be Linked. Your Connection's Linked status is indicated by the green badge next to the Connection name.
After that, you're now able to authenticate users from the listed domains using your Microsoft Connection.