Azure AD and OpenID Connect with webMethods API Gateway

Authors: Vivek Kumar, Srikanth Prathipati


Security, in information technology (IT), is the defense of digital information and IT assets against internal and external, malicious and accidental threats. Security is critical for enterprises and organizations of all sizes and in all industries. Weak security can result in compromised systems or data, either by a malicious threat actor or an unintentional internal threat.

Information security encompasses a broad set of strategies for managing the process, tools and policies that aim to prevent, detect and respond to threats to both digital and non-digital information assets.

This includes several specialized categories, including the below.

Access Control

Access to protected information must be restricted to people, entities (systems) that are authorized to access the information. In many cases the enterprises encompass heterogeneous systems that process the protected information, must also be authorized. This requires that mechanisms be in place to control the access to protected information.

Access Control generally considered in below three steps:

This document describes the OpenID Connect based Identification of an API with Azure AD and webMethods API Gateway.

What is OpenID Connect?

OpenID Connect rides on top of OAuth 2.0

  • User Identity is asserted by means of JSON Web Tokens (JWT).
  • Clients use standard OAuth2.0 flows to obtain tokens.
  • Supports optional OpenID Provider discovery, dynamic client registration and session management.
    • Azure AD does not support dynamic client registration as of today

A sample JWT token looks as below

Register Client Applications in Azure AD

Azure Active Directory (Azure AD) is a cloud identity service that allows developers to build apps that securely sign in users with a Microsoft work or school account.

Your app is integrated with the Microsoft identity platform by registering it with an Azure Active Directory tenant. Enterprise developers and software-as-a-service (SaaS) providers can develop commercial cloud services or line-of-business applications that can be integrated with the Microsoft identity platform. The integration provides secure sign-in and authorization for such services.

To register Application in Azure AD:

Please refer below link to register Application in Azure AD.

Please refer below few screenshots for reference:

After successful Application registration in Azure AD. The below parameters should be handy to make a call to get an access token.

  1. TenantID
  2. ClientID
  3. Client Secret
  4. Scope
  5. Grant_Type=client_credentials


To retrieve access token from Azure AD:

  • Target endpoint to retrieve access token from Azure AD, POST method.{tenant-id}/oauth2/v2.0/token

Replace with your tenant-id.

  • Set the below HTTP request header

Content-Type – Must be set to: application/x-www-form-urlencoded

  • Configuring the request payload

grant_type: client_credentials

client_id: xxxx

client_secret: xxxx

scope: xxxx

Consuming the above endpoint with required parameters will result in access token as response.

Please refer below sample request/response



Access Token retrieved in above step will be used to consume the API OrderStatus exposed from API Gateway. Please refer below screenshot

Steps to extract “appid“ and “audience“ from access token (JWT Token)

  • Open in web browser.
  • Place the access token retrieved in the above step in the box in the website. Token will be decoded and shown below. Please refer below screenshot

Register Azure AD with API Gateway

As an alternative to using API Gateway as the authorization server, you can use a third-party server as the authorization server. To use an external authorization server, you must configure your third-party authorization server.

To add External Authorization Server;

  • Go to menu options icon in the title bar > Administration > Security > JWT/Oauth/OpenID > External authorization servers > Add authorization server. Please refer below screenshot.

  • Provide Name, Description and Discovery URL and click on Discover. API Gateway fetches data from the URL response and auto-populates the fields with required values.
  • Refer below for Discovery URL from Azure AD.{tenant-id}/v2.0/.well-known/openid-configuration

Note: Please replace {tenant-id} with the azure portal tenantId.

Please refer below screenshot:

  • Expand Introspection and verify fields under Local introspection are auto populated.

Issuer: Token issuer.

JWKS URI: JSON Web Key Signature endpoint to fetch the corresponding public certificates.

Please refer below screenshot

  • Expand Metadata and verify fields are auto populated.

Authorize URL: The endpoint URL on the authorization server through which the client application exchanges the authorization code, client ID, and client secret, for an access token.

Access token URL: The endpoint URL on the authorization server through which the end user authenticates and grants authorization to the client application.

Refresh token URL: The endpoint URL on the authorization server through which the client application refreshes an expired access token.

Please refer below screenshot:

  • Expand scopes and verify default scopes are auto populated. You can also add custom scopes. Provide Scope, Scope description and Add it.

Please refer below screenshot:

Protect API with Identification Policy

The Identify and Authorize Application policy is used to identify the application, authenticate the request based on policy configured and authorizes it against all applications registered in API Gateway. This policy authorizes and allows access to the applications that are trying to access the APIs.

To apply JWT Identification type:

  • Go to the APIs in the title navigation bar > Click on the required API > Click on the Policies tab > Click on the Identify & Access and use Identify & Authorize Application.
  • Select JWT as Application Identification condition and Registered applications as Application Lookup condition and save it. Please refer below screenshot:

Why to select JWT in Application Idetification condition instead of OpenID Connect?

Azure AD does not send scope in the access token (JWT Token).

Sample decoded JWT token here to verify “scope“ or “scp“ is not present in the payload claims. Please refer below screenshot

Register Applications on API Gateway

An application defines the precise identifiers by which messages from a particular application is recognized at run time. The identifiers can be, for example, user name in HTTP headers, a range of IP addresses, such that API Gateway can identify or authenticate the applications that are requesting an API.

The ability of API Gateway to relate a message to a specific application enables it to:

  • Control access to an API at run time.
  • Monitor an API for violations of a Service-Level Agreement (SLA) for a specified application.
  • Indicate the application to which a logged transaction event belongs.

An application can be configured with attribute Claims set for specifying the identifiers, which specifies one or more claims that identify requests from a particular application.

To create an Application:

  • Go to Applications in the title navigation bar > Click on Create Application.

Please refer below screenshot


  • Provide the following information in the Basic information section:

Name: Specify name of the Application.

Version: Specify version of the Application.

Team: Team to which Application to be assigned.

Description: Specify the description of the Application.

  • Continue to Identifiers > Click on Add claims set.

Provide a set of claims for the JWT and OpenID clients, appid will be retrieved after decoding the access token in 

Please refer below screenshot

  • Continue to APIs > Search the required API.

Click Add to add the API. Adding an API to the application enables the application to access the API. Consumer while invoking the API at runtime, has to provide the access token or identification token for API Gateway to identify the application.

Please refer below screenshot:

Define API Scope Mapping

  • Map OAuth or OpenID Scopes

Map the scope that you have defined in the authorization server with the APIs in API Gateway to authorize the access tokens to be used to access the protected resources. You can map either a complete API or parts (resources or methods) of an API to the scope.

To map the scope:

Go to menu options icon in the title bar > Oauth/OpenID scopes > Map scope.

  • Select the authorization server scope and provide the audience value. Audience value can be extracted from the access token (JWT Token) from

  • Click on API scopes and Specify an API scope that is to be linked with the Authorization server and click on Save. This maps the authorization server scope to the selected API scopes and lists the authorization scope in the scopes list.

Consuming API from Postman

Consuming the API OrderStatus exposed from API Gateway with access token(JWT token)

1 Like

There is some miscommunication here with regards to the Azure AD issued tokens. The article says that Azure AD tokens do not have scope (“scp”) claim within them which is inaccurate.

Azure AD does include “scp” claim within its token but only for user tokens. It replaces this scp claim with the roles claim for app-only tokens it issues.

Also, the tutorial is missing step to include a JWT auth strategy within the application to use the Azure AD external auth provider.
The scope mapping is only required if the external authorization server provides a scp claim in the token. In case of above tutorial, since there is no scope claim in the JWT, is scope mapping required?

@vsingal : Nice comments! How are the scopes in roles claim mapped to API Gateway scopes?

Very well-documented steps for Azure AD and Open ID connect with webMethods API Gateway .
This has helped me implement them in my project as well.

How you implement Azure AD to your API Gateway.