Microsoft Entra ID 2-legged OAuth 2.0 API security profile in Jitterbit API Manager

Introduction

This page provides the prerequisites for using Microsoft Entra ID 2-legged OAuth 2.0 with a Jitterbit custom, OData, or proxy API. (For 3-legged OAuth, see Microsoft Entra ID 3-legged OAuth 2.0 API security profile.)

Within a security profile, you can configure Microsoft Entra ID (Azure AD) as an OAuth 2.0 identity provider to provide API consumers access to an API using Microsoft Entra ID authentication.

For additional information, see Microsoft's Configure an OpenID Connect OAuth application from Microsoft Entra app gallery documentation.

Azure AD Graph deprecation

The Azure AD Graph is deprecated and will be fully retired on June 30, 2025. If you previously configured your app registration with Azure AD Graph, you must migrate the app registration to Microsoft Graph before February 1, 2025. App registrations that have not been migrated by February 1, 2025 will receive an error when making requests.

Once the app registration has been migrated to Microsoft Graph, you must update the app manifest (as described in step 12 under Grant API permissions to Harmony).

Prerequisites

Microsoft Entra ID P1 edition is required to set up and use Microsoft Entra ID as an identity provider.

1. Configure Microsoft Entra ID as an identity provider

Follow these steps to configure an OAuth 2.0 application in the Microsoft Azure portal and obtain the client ID, client secret, and directory ID needed for configuring Microsoft Entra ID as an identity provider for a security profile:

1. Log in to the Microsoft Azure portal.

2. In the Microsoft Azure portal, go to App registrations and click New registration:

   

3. On the Register an application screen, specify the initial details of the application:

   

   • Enter a Name. For example, Jitterbit API Manager APIs.
   • Under Supported account types, select the appropriate option for your situation.

4. After clicking Register, on the Overview screen for the new application, the Application (client) ID and Directory (tenant) ID are displayed. Retain these for later use, as they will be required when configuring the security profile in API Manager:

   

5. Under the Manage category on the left, select Certificates & secrets. Then, under Client secrets, click New client secret:

   

6. Provide a Description and set the secret to Never expire. Then click Add:

   

7. Use the Copy to clipboard icon to copy the new client secret. Retain this for later use, as it will be required when configuring the security profile in API Manager.

   

2. Grant API permissions to Harmony

Follow these steps to grant Harmony permissions to use the Microsoft Entra ID APIs with the OAuth 2.0 application that you created in the section Configure Microsoft Entra ID as an identity provider. If continuing from the previous section, you can start at step 3 below.

1. Log in to the Microsoft Azure portal.

2. In the Microsoft Azure portal, go to App registrations and select the OAuth 2.0 application that you created in the section Configure Microsoft Entra ID as an identity provider (in the example, called Jitterbit API Manager APIs).

3. Under the Manage category on the left, select API permissions. Then, under Configured permissions, click Add a permission:

   

4. On the Request API permissions screen, under the Microsoft APIs tab, select the Microsoft Graph API:

   

5. On the Request API permissions screen, select Delegated permissions:

   

6. The section Select permissions is now displayed. Within it, select these permissions:

   • Under OpenId permissions, select offline_access, openid, and profile:

     

   • Under User, select User.Read:

     

7. Once these permissions have been selected, at the bottom of the Request API permissions screen, click Add permissions.

8. You are returned to the API permissions screen for the application. Under Configured permissions, click Grant admin consent for \<Directory>:

   

9. Acknowledge the dialog to grant consent for the directory:

   

10. Under Configured permissions, the Status column should now show that consent has been granted for each added permission:

    

11. Follow these additional steps to create a custom scope:

    1. Navigate to Expose an API and click Add a scope.

    2. In the Add a scope dialog, enter a Scope name, Admin consent display name, Admin consent description, and complete the optional fields as desired. Click Add scope:

       

12. Under the Manage category on the left, select Manifest. Ensure that requestedAccessTokenVersion is set to 2 and click Save:

    

    Note

    Your authentication token will not validate if requestedAccessTokenVersion is not set to 2.

3. Configure a security profile in API Manager

Follow the instructions for Configure a security profile in Security profile configuration.

During configuration, select OAuth 2.0 as the authentication Type and Azure AD as the OAuth provider:

Enter the scope in the OAuth scope field. The scope name is <client_id>/.default. The client ID was obtained above in step 1.

The Authorized domains field must be empty:

Optionally, enter the OAuth client ID and OAuth client secret (for testing purposes) obtained above in step 1:

Enter the audience, which is your app's Application ID (client ID), assigned to your app in the Azure portal as described above in step 1.

Edit the OpenID discovery URL, the OAuth authorization URL, the OAuth token URL, and the User info URL to replace the placeholder directory ID (yourDirectoryID) with the Directory ID obtained above in step 1.

Once the above fields have been populated, click Test to validate the authentication token.

4. Assign a security profile in API Manager

To use the security profile with an API, follow the instructions for configuring a custom API, OData service, or proxy API and select the security profile configured with Microsoft Entra ID OAuth 2.0 authentication.

5. Access an API with Microsoft Entra ID authentication

Once you have saved and published a custom API, OData service, or proxy API, its API is accessible by URL in the application calling the API using the configured authentication method.

Using 2-legged OAuth 2.0 is a two-step process:

1. Generate an OAuth token either by passing the Azure client ID and client secret obtained above in step 1 in an RFC6749 Client Credentials Access Token Request to the new 2-legged OAuth Token URL link displayed on the Security Profiles page or by obtaining the OAuth token directly from Microsoft Entra ID.
2. Send the OAuth token in the API header using the "bearer" token type defined in RFC6750.

To consume the API, use the link to Copy URL and use it within the calling application:

If the API supports GET, you can also paste the URL into a web browser to consume the API manually.

When 2-legged OAuth Flow is being used, the API gateway fetches the access token and authentication takes place automatically.

If the authentication is successful, the expected payload is displayed in the web browser.