Introduction
This guide helps you set up OAuth2 authentication step by step between the Workspace 365 Integration Builder and the Microsoft Graph API. OAuth2 is a secure standard for authorising access to APIs, allowing you to integrate specific data and functionalities from Microsoft 365 into Workspace 365.
With the Integration Builder, you can create custom integrations tailored to your organisation's needs, such as retrieving data from SharePoint, Teams, or other Microsoft 365 applications. This guide walks you through the process of configuring API permissions and setting up authentication so you can get started quickly.
Follow this guide carefully to ensure that the connection is set up securely and correctly.
Steps
Step 1: Navigate to the Integration Builder in Workspace 365
Log in to Workspace 365.
Go to the Integration Builder via the menu or the settings page.
Click on the Authentication tab at the top of the page.
Then click the New button to create a new authentication.
Step 2: Select the OAuth2 type and enter a name
After clicking New, a window will appear to configure the authentication.
In the Type field, select the OAuth2 option from the available choices.
In the Name field, enter a recognisable name. For this guide, we will use:
OAuth2 Microsoft Graph API Authentication.
After this step, an App registration in Microsoft Entra ID must be created. This is necessary to generate the required information for the New Authentication tab in the Workspace 365 Integration Builder.
Step 3: Navigate to App Registrations in Microsoft Entra ID
Log in to the Microsoft Entra admin centre via portal.azure.com.
In the left-hand menu, click on Microsoft Entra ID.
Select App Registrations from the submenu.
This is where you can register and configure a new app to use OAuth2 authentication with the Microsoft Graph API.
Step 4: Click on 'New Registration'
Once in the App Registrations menu, click the + New Registration button at the top of the page.
This initiates the process to register a new application in Microsoft Entra ID.
Step 5: Name the app, select the account type, and configure the Redirect URI
In the Name field, enter a name for your app. In this guide, we use:
OAuth2 Workspace 365 Integration Builder App.
However, you can choose any name that fits your situation.Under Support account type, select the account type. The most common choice is:
Accounts in this organizational directory only (Single-tenant).
This means that only accounts within your organisation can access the application. Verify if this is the correct choice for your situation and adjust it if necessary.Configure the Redirect URI:
Return to the New Authentication window in Workspace 365.
Locate the value for the Redirect URI. This is a unique URL generated by Workspace 365.
Copy this Redirect URI.
Go back to the Redirect URI field in the App registration in Microsoft Entra ID.
In the drop-down menu, select Web as the type.
Paste the copied Redirect URI into the field.
Click Register to complete the configuration.
Step 6: Navigate to API Permissions and add a permission
Open the newly registered app (OAuth2 Workspace 365 Integration Builder App) in Microsoft Entra ID.
In the left-hand menu, click on API Permissions.
At the top of the page, click the Add a permission button to add a new access permission.
This allows you to grant specific rights to the app, enabling access to the necessary data and functionalities within the Microsoft Graph API.
Step 7: Record the generated Client Secret Value and Secret ID
After creating the Client Secret, you will see a Value and a Secret ID generated.
Important: Immediately record the Value in a secure location and save it. This value is only displayed once.
If you cannot retrieve the value later, you will need to create a new Client Secret. This may cause existing authentications in the Workspace 365 Authentication tab that use the same SSO to stop working.
The Value is essential for configuring the authentication within Workspace 365. Ensure these details are stored securely.
Step 8: Copy the Secret ID and Value to Workspace 365
In Workspace 365, open the New Authentication window in the Authentication tab.
Use the Application (client) ID from the Overview page of Microsoft Entra ID as the value for the ClientId field in Workspace 365.
Copy the Value of the generated client secret from Microsoft Entra ID and paste it into the Client Secret field in Workspace 365.
These values securely link the integration between Microsoft Entra ID and Workspace 365. Carefully verify that you have entered the correct values to avoid authentication errors.
Step 9: Retrieve the Authorization Endpoint URL and Token Endpoint URL
Return to the Overview page of the app (OAuth2 Workspace 365 Integration Builder App) in Microsoft Entra ID.
Click on Endpoints to view the available URLs.
Select the following URLs:
OAuth 2.0 authorization endpoint (v2) for the Authorization Endpoint URL.
OAuth 2.0 token endpoint (v2) for the Token Endpoint URL.
Copy both URLs.
Make sure to specifically select the v2 versions, as they are compatible with the OAuth2 configuration in Workspace 365. Paste these URLs into the appropriate fields within the Authentication tab in Workspace 365.
Step 10: Verify all information is entered correctly
Return to the New Authentication window in the Authentication tab of Workspace 365.
Ensure the following fields are correctly filled in:
ClientId: This should be the Application (client) ID from the Overview page of the app registration in Microsoft Entra ID.
Client Secret: The copied Value from the generated client secret in Microsoft Entra ID.
Authorization Endpoint URL: The OAuth 2.0 authorization endpoint (v2) URL.
Token Endpoint URL: The OAuth 2.0 token endpoint (v2) URL.
Scope: The required scope depends on the integration you want to create. Refer to the specific integration's documentation to determine which scopes are required.
Step 11: Save the new authentication and test it
At the bottom of the New Authentication window, click the Save button.
After saving, a pop-up will appear with the option to test the authentication.
Click on Authenticate in the pop-up.
Step 12: Log in with your Microsoft credentials to complete the authentication
After clicking Authenticate in the pop-up (Step 11), you will be redirected to a Microsoft login screen.
Log in with your Microsoft credentials that have the appropriate permissions to validate the configuration.
If the authentication is successful, you will see a confirmation screen in Workspace 365, indicating that the OAuth2 authentication has been successfully set up.
Note: If an error message appears, verify that all information (such as the ClientId, Client Secret, and Endpoints) is entered correctly, and try again.
Step 13: Complete the authentication
After a successful authentication, you will see another pop-up in Workspace 365.
In this pop-up, click Finish to complete the process.
The Microsoft Graph API OAuth2 authentication is now fully configured and ready to use within Workspace 365. You can now link this authentication to integrations or use it as described in the relevant guide.