Skip to end of metadata
Go to start of metadata

Introduction

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

This page shows how to configure and use Azure AD authentication with a Jitterbit Custom, OData, or Proxy API by following these steps:

  1. Configuring Azure AD as an Identity Provider
    Configure an OAuth 2.0 application and obtain the Client ID, Client Secret, and Directory ID that you will need to use as input for configuring a security profile in API Manager.
  2. Granting API Permissions to Jitterbit Harmony
    Grant Jitterbit Harmony permissions to use the Azure AD APIs with the OAuth 2.0 application you created in the previous step.
  3. Configuring a Security Profile in API Manager
    Configure and test Azure AD as the identity provider in API Manager. You will need to use the Client ID, Client Secret, and Directory ID obtained in the first step.
  4. Assigning a Security Profile in API Manager
    Assign the security profile to one or more Jitterbit Custom, OData, or Proxy APIs. 
  5. Accessing an API with Azure AD Authentication
    API consumers are able to use Azure AD authentication to consume Jitterbit Custom, OData, or Proxy APIs that the security profile is assigned to.

For additional information, see the Microsoft Azure documentation Configure an OpenID/OAuth application from the Azure AD app gallery.

Prerequisites

Microsoft Azure AD Premium P1 edition is required to set up and use Azure AD as an identity provider.

1. Configuring Azure AD 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 Azure AD 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:

    1. Enter a Name. For example, Jitterbit API Manager APIs.
    2. Under Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant).
    3. Under Redirect URI (optional), use the dropdown to select Web and enter the swagger-ui URI value appropriate for your region (see Finding My Region):
  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. On the Overview screen, click the link under Redirect URIs:

  6. The Authentication screen for the application is displayed. Follow these steps to add two additional redirect URI values appropriate for your Harmony organization and region:
    1. To obtain the additional URI values, in API Manager, open the security profile configuration screen and copy these values (the image below is cropped to show the relevant areas):

    2. On the Authentication screen for the application in the Microsoft Azure portal, under the Web section, click Add URI and enter each additional URI value obtained above. Then click Save:

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

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

  9. 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. Granting API Permissions to Jitterbit Harmony

Follow these steps to grant Jitterbit Harmony permissions to use the Azure AD APIs with the OAuth 2.0 application that you created in the section Configuring Azure AD 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 Configuring Azure AD as an Identity Provider (in the example, called Jitterbit API Manager APIs).
  3. Under the Manage category on the left, select API permissionsThen, 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 all 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:

3. Configuring a Security Profile in API Manager

Follow the instructions for Configuring a Security Profile in Security Profile Configuration.

CAUTION: The Profile Name must not contain any spaces. If the Profile Name contains spaces, you will receive an error when attempting to access an API using that security profile. Azure AD returns an error similar to this:

The reply URL specified in the request does not match the reply URLs configured for the application.

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

If you are using the setting 2-legged OAuth Flow, you must enter a value in the OAuth Scope field. Enter the value in this format:

<client_id>/.default

Where <client_id> is replaced with the Client ID obtained in the section Configuring Azure AD as an Identity Provider:

Edit the OAuth Authorization URL, OAuth Token URL, and User Info URL to replace the placeholder directory ID (yourDirectoryID) with that obtained in the section Configuring Azure AD as an Identity Provider. In the OAuth Token URL field, there is a known issue where the placeholder text incorrectly repeats the oauth2/v2.0 path. Remove the duplicate path to correct the URL:

Edit the OAuth Authorization URL, OAuth Token URL, and User Info URL to replace the placeholder directory ID (yourDirectoryID) with that obtained in the previous section, Configuring Azure AD as an Identity Provider. In the OAuth Token URL, there is a known issue where the placeholder text incorrectly repeats the oauth2/v2.0 path. Remove the duplicate path to correct the URL:

Click Test Client ID + Secret to verify connectivity with the identity provider using the configuration.

4. Assigning a Security Profile in API Manager

To use the security profile with an API, follow the instructions for configuring a Custom API, OData API, or Proxy API and select the security profile configured with Azure AD OAuth 2.0 authentication.

5. Accessing an API with Azure AD Authentication

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

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.

The resulting behavior depends on whether the setting 2-legged OAuth Flow is being used:

  • 2-legged OAuth: If 2-legged OAuth Flow is being used, the API Gateway fetches the access token and authentication takes place automatically.
  • 3-legged OAuth: If 2-legged OAuth Flow is not being used, the browser redirects to the native login interface for Okta. Provide your credentials to authenticate with Okta.

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

On This Page

 

  • No labels