How API Gateways help to integrate with OAuth security models - part 2

How to call Microsoft Azure Marketplace APIs using API Gateways and OAuth security.

[This article continues the series of posts that describe different scenarios of building effective integration solutions that require support for OAuth security models]

In the previous article I have described two types of scenarios that are considered in the context of integration with OAuth security models by the API applications. Those are:

1. We build API services that have to be protected with OAuth-based security integrated with some OAuth server infrastructure. This scenario is called Service OAuth security (or Inbound OAuth security) because integration with OAuth is focused on building services/APIs. An API service application can be any kind of application, for example a complex BizTalk Server application that requires protection of its Receive ports with OAuth security.
2. We build API consumer applications that have to call external APIs using OAuth security required by API provider and its OAuth server infrastructure. This scenario is called Client OAuth security (or Outbound OAuth security) because integration with OAuth is focused on building API client applications. An API consumer application can be any kind of application, for example a complex BizTalk Server application (see the last section of this article).

I also described in the previous article the high-level concepts of how API Gateways enable applications with OAuth security models without making any changes to the applications themselves. I provided details of the demo use case setup for the Service OAuth security case, and the configuration details for the Gateway implemented in the Nevatech Sentinet product that enables a sample US Carrier Flight Delays API with the OAuth security integrated with Microsoft Azure Active Directory (see overview of that demo use case on the diagram below).

In the demo use case shown above Microsoft Azure Active Directory OAuth infrastructure was used only as a particular example of an OAuth server infrastructure that API-enabled applications can be integrated with.

In this article I will describe how to use Sentinet Node gateway in the Client OAuth security use case when we have to build an application that consumes external API that requires OAuth security. As a demo use case I will setup a call to the Microsoft Translator API which is available in the Microsoft Azure Marketplace as a public REST API. A browser client application will call the Gateway endpoint using just plain https calls, while the Gateway will take full responsibility to interact with the actual Microsoft Translator API using required OAuth security.

The use case setup will require few steps:

1. Setup your free Microsoft Azure Marketplace account
2. Register Microsoft Translator API in your Microsoft Azure Marketplace account
3. Register your application that can consume APIs available for your Microsoft Azure Marketplace account
4. Configure Sentinet Node (gateway) with the virtual service that interacts with the Microsoft Translator API
5. Build consumer application that calls Sentinet virtual service and test API calls

These steps are described below in more details.

Step 1. Setup your Microsoft Azure Marketplace account

Open browser with this link https://datamarket.azure.com/dataset/bing/microsofttranslator and click Sign In link to sign-in with existing account or to create a new Microsoft Azure Marketplace account using your Microsoft account (former Live ID).

Step 2. Register Microsoft Translator API in your Microsoft Azure Marketplace account

Once signed-in, click Sign Up link to sign up for the free use of the Microsoft Translator API (free use for 2,000,000 characters translated per month, or paid use otherwise).

On the next screen checkmark agreement terms to use Translator API and click Sign Up button.

If you click My Account tab and MY DATA link, you will see Microsoft Translator API registered with your Marketplace account:

Step 3. Register your application that can consume APIs available for your Microsoft Azure Marketplace account

Click My Account tab and select DEVELOPERS link.

Click Register applications button.

Provide Client ID for your application (that will have to be unique ID), application Name and Redirect URI. Redirect URI will not be actually used but has to be provided anyway, for example: https://someuri.com. Client ID and auto-generated Client secret will have to be used later by the API calling application to get OAuth token from Azure Marketplace OAuth server. Click Create button to create developer application:

The application is now listed as registered and active under your account DEVELOPERS link:

Step 4. Configure Sentinet Node with the virtual service that interacts with the Microsoft Translator API

In order to manage an API through the Sentinet Node gateway, the API has to be registered in the Sentinet services and API Repository.

Microsoft Translator API HTTP(S) endpoint address can be found in the Microsoft documentation here, while API methods are described here. For the sake of simplicity of this demo use case I registered this API in the Sentinet Repository with just two operations, DetectLanguage and Translate. Sentinet Console shows API registration below.

The API is registered with the HTTPS endpoint to make sure request messages with OAuth tokens will be transmitted securely:

For example, Translate operation must be called using the following syntax: https://api.microsofttranslator.com/v2/Http.svc/Translate?text={text}&from={from}&to={to}
where {text}, {from} and {to} are the placeholders for the actual input operations’ parameters for the text being translated and language codes to translate text from and to.

The most important endpoint’s configuration property shown above is the security Policy configuration which is called OAuth Client Policy. We register Microsoft Translator API with the https://api.microsofttranslator.com/v2/Http.svc endpoint configured with the Client OAuth security so that the virtual service hosted on the Sentinet Node gateway can automatically inherit this security configuration for its outbound (client) endpoint. The diagram below shows that relationship:

OAuth Client Policy configuration for the Microsoft Translator API is driven by the Microsoft documentation that describes communication with the Microsoft Azure Marketplace OAuth server infrastructure. The Marketplace OAuth security requires client credentials grant flow when the calling application must identify itself with the Client ID and Client secret. In the Sentinet console that security is expressed with the Policy XML configuration entered in the console as a custom WCF binding:

The binding is shown below:

<bindings>

  <customBinding>

    <binding name="WebOAuthSecurityBinding">

      <webOAuthSecurity>

        <clientSettings

          tokenEndpoint=https://datamarket.accesscontrol.windows.net/v2/OAuth2-13

          clientId="Sentinet45Avs"

          clientSecret="……………………"

          authenticationType="FormPost"

          authenticationFlow="ClientCredentials"

          scopes=https://api.microsofttranslator.com />

      </webOAuthSecurity>

      <webMessageEncoding />

      <httpsTransportmanualAddressing="true" />

    </binding>

  </customBinding>

</bindings>

There are only few attributes that drive the whole configuration:

1. tokenEndpoint - address of the Azure Marketplace OAuth server endpoint that accepts requests for OAuth token.
2. clientId – Id of the client application registered in the Marketplace portal in the Client ID field (described in the Step 3 above).
3. clientSecret – secret string value registered in the Marketplace portal in the Client secret field (described in the Step 3 above).
4. authenticationType – FormPost value that indicates that the clientId and clientSecret credentials must be transmitted in the request message as the HTTP POST Forms parameters.
5. authenticationFlow – ClientCredentials value that indicates that OAuth security policy should use client credentials grant flow as described by the Microsoft documentation.
6. scopes – scope of the intended OAuth token that should be issued by the Azure Marketplace OAuth server to the API caller application. The value is https://api.microsofttranslator.com as described by the Microsoft documentation.

Note that responses from Azure Marketplace OAuth server are known to have expiration time. That is why the XML binding for the Sentinet Policy configuration above does not explicitly specify any OAuth token caching time intervals – Sentinet Node will figure it out itself during the runtime by analyzing responses from the OAuth server (Sentinet can explicitly specify OAuth tokens caching time intervals, but in this case it is not needed). As a result, Sentinet will be making only few periodic calls to the OAuth server to get and refresh OAuth tokens.

Last part of this step is to create a virtual service hosted on the Sentinet Node (gateway) that virtualizes Microsoft Translator API registered in the Sentinet Repository. Virtual service (virtual REST API) is created using Sentinet virtual services Graphical Designer. Service outbound endpoint will be automatically configured with the OAuth Client Policy as described above, while inbound endpoint (that will be used by the actual consumer application) can be configured with its own independent security. In our case it is configured with a simple WebHttpBinding (Trasport Security) policy which is just a regular HTTPS endpoint security.

From the OAuth perspective, configuring Sentinet virtual service with the XML Policy listed above is all it takes to implement OAuth security with the Sentinet Node gateway.

Sentinet virtual API service in this demo case provides a one-to-one mapping of its operations to the physical API operations (Sentinet product in general allows for more complex mappings), so that the virtual Translate operation is defined as shown below:

Now we test the calls to the Microsoft Translator API by calling Sentinet virtual endpoint from a browser application:

We get back the result of translating text Monday from English (en) to French (fr), and it is Lundi.
Full monitoring of this message exchange can be seen on the Sentinet Console that shows message exchanges in real-time.

What is important here, is that browser application in this case does not know anything about OAuth security required by the Microsoft Translator API. Sentinet Node gateway helped to deal with this security in a completely configurable way with no coding involved.

Conclusions

Any application can be easily enabled with the capability to communicate with OAuth-protected APIs without making any changes to the application itself. On-premises or cloud Gateways help with integrations with OAuth security models.

The benefits of using Gateways are even higher when application direct enablement with OAuth security presents bigger challenges from the development, deployment and management perspectives. Consider a BizTalk application that has to call different external APIs where different APIs require integrations with different OAuth providers.

Configuring BizTalk application for this scenario requires quite some custom code development for each OAuth provider with the additional deployment and management of that code within the BizTalk infrastructure. By using Gateway as a generic security mediation broker, all BizTalk Send ports can be configured identically with some simple “internal” security (for example, Basic API Authentication or Windows integrated). The Gateway will make sure to forward messages using OAuth security required by each specific external API.