There are different scenarios in which you might want to integrate with Microsoft Azure Active Directory (AD):

• You want to let users into your application from an Azure AD you or your organization controls (such as employees in your company).
• You want to let users coming from other companies' Azure ADs into your application. You may want to set up those external directories as different connections.

If you plan on allowing users to log in using a Microsoft Azure Active Directory account, either from your company or from external directories, you must register your application through the Microsoft Azure portal.

Create a New Application

Login to Microsoft Azure and choose Azure Active Directory from the sidebar.

Under MANAGE, select App registrations.

Click on the + ADD button to add a new application.

Enter a Name for the application, select Web app/API as the Application Type, and enter your application URL for Sign-on URL.

Configure the Permissions

Once the application has been created, configure the permissions. Click on the name of the application to open the Settings section. For example, see the "Test" application below.

Click Required permissions.

Then, click on Windows Azure Active Directory to change the access levels.

The next step is to modify permissions so your app can read the directory. Under DELEGATED PERMISSIONS, check next to Sign in and read user profile and Read directory data.

• Application Permissions: Read directory data
• Delegated Permissions: Access the directory as the signed-in user

Click the SAVE button at the top to save these changes.

Allow Access From External Organizations (Optional)

If you want to allow users from external organizations (such as other Azure directories) to log in, you will need to enable the Multi-Tenant flag for this application. In the Settings section, click Properties. Locate the Multi-tenanted toggle at the bottom and select Yes. Finally, click the SAVE button at the top to save these changes.

Create the Key

Next, you will need to create a key to be used as the Client Secret in the API Gateway connection. Click on Keys from the Settings menu.

Enter a name for the key and choose the desired duration.

Click Save and the key will be displayed. Make sure to copy the value of this key before leaving this screen, otherwise, you may need to create a new key. This value is used as the Client Secret in the next step.

Configure Reply URLs

Next, ensure that your API Gateway OAuth callback URL is listed in allowed reply URLs for the created application. Navigate to Azure Active Directory -> Apps registrations and select your app. Then click Settings -> Reply URLs and add:

https://YOUR_APIGATEWAY_OAUTH_DOMAIN/oauth2/callback

Without this step, the App consent page will return a "Bad request" error. The fine print in the footer of this error page can be used to identify the exact tenant name and missing callback URL.

Configure the App in API Manager

Now, you need to Login to API Manager to create an App and use the Azure Client Id.

Build the Azure Token Verification Policy in Policy Studio

It does the following:

1. Verify the JWT with the right X509 certificate (the certificate can be found in the FEDERATION METADATA DOCUMENT in Azure (App Registrations - Endpoints )
   Example - (https://login.microsoftonline.com/{your-azure-instance}/federationmetadata/2007-06/federationmetadata.xml )
2. If Valid — extract the token and check if the DateTime is Valid, the client id, scopes are valid. Return True.
3. If Invalid — Return False.

The policy is also attached to this document.

Add the Policy Under the OAuth Token Information Policies.

And then Deploy, so the Policy is available in API Manager.

Secure Your API in API Manager With the Policy

1. Import a backend API and virtualize as Frontend API
2. Select OAuth (External) as FrontEnd Authentication from the drop-down.
3. Select the policy previously created from the Token Information policy dropdown.
   
4. Since we are configuring Authorization Code as the Grant Type:
   
5. Publish the API, grant the API access to the right Organization (the Organization where the App was created)
   
6. Go to the App that was created and Grant API Access
   
7. The API is now ready to be tested.

Test the API via Postman

Next, configure Postman with all the right information required to make the call to Azure and get the JWT Token.

Click on Request Token and if everything is configured correctly, it will take you to the Azure Authentication Page where you will enter your credentials.

Once the credentials are validated, it will return back to Postman with the JWT Access Token.

Optionally, this Token can also be verified in jwt.io. Copy and paste it on the website to review the details like the expiry.

Now, use the JWT Access Token to test your API.

The Token is validated by the API Gateway and if Valid, the response is sent.

Finally, check the API Gateway to review the results.