[This article starts the series of posts that describe different scenarios of building effective API integration solutions that require support for OAuth security models]
The OAuth 2.0 protocol and its OpenID Connect extension build an industry-standard framework that enables applications to outsource user authentication to a centralized service and to provide access to a remote resource on behalf of the user. Both protocols are getting a lot of popularity in the modern IT and Applications Integration landscape due to the benefits the protocols provide in the space of the universal identify management, authentication, authorization and single-sign-on (SSO). At the same time, both protocols may not be easy to implement, especially when applications that require integration with OAuth protocols are somewhat more complex, like BizTalk Server applications. API Gateways as generic “brokers” can significantly help to simplify support for OAuth security models by your custom applications and APIs.
Introduction. OAuth requirements for API applications.
There are two types of requirements that we consider in the context of integration with OAuth security models. These requirements differ only by the perspective from which we are looking at the OAuth security. Specifically, do we have to implement an API that is secured with OAuth, or do we have to implement a consumer application that has to call OAuth-protected API? Of course we might have requirements to implement OAuth at both sides, an API itself and a consumer application. Here is a brief description of these two requirements:
- We need to secure our API with OAuth protocol. An API in this case has to be implemented with the security model that integrates with some external or internal OAuth server infrastructure. This may be called Inbound or Service OAuth security because our API will be receiving messages with OAuth tokens issued by some OAuth server. For example, you might need to develop a custom API application (lets’ say a BizTalk application’s Receive Port configured as a REST API) that has to be protected with OAuth security integrated with the Microsoft Azure Active Directory infrastructure. What we see surrounded by dashed lines on the figure below is the focus of this requirement.
2. We need to implement OAuth security in our custom application that calls some external or internal API protected with OAuth security. This may be called Outbound or Client OAuth security because our application will have to be responsible for acquiring OAuth tokens from OAuth server and sending its outbound messages to a custom API. For example, you might need to develop an application (for example BizTalk Server application) that calls Salesforce.com API, or a Twitter API or some other API protected with OAuth security. What we see surrounded by dashed lines on the figure below is the focus of this requirement.
API Gateways for OAuth security
An API Gateway is a specialized proxy application that mediates communications between consumer applications and API services. Effectively Gateways “virtualize” APIs by exposing them to consumer applications via endpoints hosted by the gateway itself, while forwarding received messages to the backend business APIs. One of the most important benefits of the Gateways is the capability to broker (or mediate) security. In regards to OAuth specifically:
- Gateway can receive messages from the consumer applications where messages are sent with OAuth tokens issued by OAuth server. This is what is called above Service OAuth security because Gateway implements OAuth on its inbound side as an API service.
Gateway will take full responsibility for accepting and validating OAuth tokens. If a token is a JWT token (JSON Web Token), it will be immediately validated. If it is what’s called a Reference token, Gateway will take responsibility to “consult” with OAuth server for the ultimate validation (step 3 on the diagram above). What’s really important is that Gateway can forward messages to the actual backend business API service using whatever security the API itself requires (for example Basic Authentication, Windows Integrated or custom API Security Keys). That means that your actual API service does not have to know anything about OAuth, and yet it becomes protected with OAuth security “indirectly” by means of being virtualized through the Gateway. You can think of this as your API enablement with OAuth without making any changes to your backend business API. - Gateway can receive messages from the applications over standard or custom security protocols (for example Basic Authentication, Windows Integrated or custom API Security Keys) and forward them to the OAuth-enabled APIs using OAuth security models. This is what’s called above Client OAuth security because Gateway implements OAuth on its outbound side as an API client.
Gateway will take full responsibility for requesting OAuth token from the OAuth server, and attaching received OAuth token to its outbound message that is sent to the backend business API. Your API consumer application does not have to know anything about OAuth, and yet it gets capability to communicate with OAuth-enabled API by means of calling virtual API hosted on the Gateway. You can think of this as your consumer application’s enablement with OAuth without making any changes to the application itself.
In both Service and Client OAuth security cases, Gateways take responsibility to deal with OAuth security on behalf of the custom applications and APIs, and ultimately Gateways decouple developers and operations people from dealing with OAuth directly. Most importantly, this OAuth security delegation does not involve any coding - it is all about configuration only.
In order to be practically effective in providing OAuth security mediation, Gateways have to:
- Support simple configuration of the OAuth security models. A simple User Interface should be provided by the Gateway infrastructure to allow configuration of the desired OAuth security model(s).
- Support remote and secure configuration of the Gateway. A simple User Interface should be provided by the Gateway infrastructure to support remote configuration of the Gateway itself, along with its virtual services and their OAuth security models.
- Support any OAuth provider infrastructure as long as the infrastructure is implemented using standards-based OAuth and OpenID Connect protocols. A good Gateway does not have to have specific “connectors” for specific OAuth providers, rather it should provide a single OAuth configuration that supports integration with any OAuth provider.
Service OAuth security - what you need to know about OAuth server
In order for the Gateway to validate OAuth tokens received from the consumer application, the Gateway has to be configured with the some knowledge of the OAuth server that issues the tokens. At minimum that knowledge must include information about OAuth server’s security keys that OAuth server uses to sign the tokens it issues. Knowing these keys allows Gateways to implement minimum required validation of the OAuth tokens received. This means that in order to configure the Gateway, a developer has to consult with the OAuth provider documentation to learn about OAuth server security keys that are used to sign OAuth tokens.
OAuth server security keys may come in different forms:
- X.509 certificate
- RSA keys
- Symmetric keys
Gateway configuration should allow to specify these keys in two ways:
- Direct configuration. In this case known OAuth server’s X.509 certificate(s), RSA or symmetric keys can be directly entered into the Gateway configuration.
- Indirect configuration. In this case Gateway can be configured with the OAuth server public metadata endpoint that serves OAuth server metadata document. Metadata document describes OAuth server configuration (including it security keys) in the standard OpenID Connect discovery format or in the WS-Federation format. Knowing metadata endpoint address allows Gateways to dynamically “discover” OAuth server security keys from the metadata document. This second option of configuring just the metadata endpoint alone, not only simplifies the whole process of the Gateway configuration, but also provides configuration with the flexibility to dynamically handle cases when OAuth server security keys change (Gateway can learn about security keys change from the OAuth server updated metadata document which can be checked by the Gateway periodically).
Using Sentinet to implement Service OAuth security
Last part of this article describes how Nevatech Sentinet product supports Service OAuth security by its Microsoft .NET-based Gateway implementation called Sentinet Node.
Sentinet provides a single unified configuration for all communication and security protocols (including OAuth) that is called Policy configuration. A policy configuration is described by a simple XML fragment that uses exact same syntax as a standard or a custom WCF binding XML configuration.
Microsoft WCF technology does not provide build-in bindings for OAuth and OpenID Connect security models. So Sentinet extends WCF binding configuration system by offering generic custom binding element called <webOAuthSecurity> that can be used as part of any <customBinding> in place of the standard WCF <security> binding element. For example:
<customBinding>
<binding name="WebOAuthSecurityBinding">
<webOAuthSecurity>
....
</webOAuthSecurity>
<webMessageEncoding />
<httpsTransport />
</binding>
</customBinding>
Interestingly enough, the binding itself is not directly connected with the Sentinet infrastructure, and it can be considered as a stand-alone WCF binding that can be used in any WCF .NET application to support OAuth and OpenID Connect protocols (of course given the fact you have license to use Sentinet .NET libraries that are part of the Sentinet product).
In this article I will show how to configure a demo use case when a business API (a Microsoft US Air Carrier Flight Delays API in this case) is accessed by the Gateway using Basic Authentication security, while the Gateway makes this service available to consumer applications using OAuth security integrated with Microsoft Azure Active Directory OAuth infrastructure.
In the Sentinet Services and API Repository a Microsoft US Air Carrier Flight Delays API is registered with its endpoint address and classical Basic Authentication security policy. Sentinet User Interface Console shows this registered API below:
API resource (On-Time-Performance service operation) is defined with /On_Time_Performance Uri template according to the API documentation.
Now the Gateway (Sentinet Node) has to be configured with the Air Carrier Delays virtual service that virtualizes physical Air Carrier Delays API. Gateway virtual service has to be configured with the Username/Password for Basic Authentication on its outbound side, and with OAuth security policy on its inbound side. Below is the Sentinet Console screenshot that shows virtual service Design User Interface with the outbound endpoint that is configured with the Basic Authentication and Username/Password for the outbound client identity.
The most interesting step here is configuration of the virtual service’s inbound endpoint with the OAuth security policy as shown on the screenshot below.
The configuration is quite simple and represented by the WCF custom binding:
<bindings>
<customBinding>
<binding name="WebOAuthSecurityBinding">
<webOAuthSecurity metadataEndpoint=https://login.microsoftonline.com/avsad.onmicrosoft.com/.well-known/openid-configuration>
<serviceSettings tokenType="Jwt" />
</webOAuthSecurity>
<webMessageEncoding />
<httpTransport manualAddressing="true" />
</binding>
</customBinding>
</bindings>
There are really only two attributes that drive the whole configuration:
- The metadataEndpoint attribute which is the address of the OAuth server’s endpoint that provides public metadata document in the standard OpenID Connect discovery format as described above. The endpoint address is the “standard” Azure Active Directory address that must have your AD tenant name embedded into the address (in my case it is avsad). Screenshot below shows where you can find AD tenant name on the Microsoft Azure portal.
- The tokenType attribute that configures security policy to expect JWT token.
Sentinet allows to specify many more OAuth security configuration attributes that provide more detailed and fine-grained OAuth configuration (for example, OAuth server’s issuer identity IDs and intended OAuth token audiences). But for the sake of simplicity it is sufficient to configure just these two above. Note that for Sentinet specifically, lack of additional security configuration details does not necessarily compromise security because Sentinet can be later configured with the separate Access Rules configuration that will validate JWT token’s claims about the consumer application against expected claim values.
The next step is to configure Azure Active directory itself. In this step you will have to:
- Register the API itself (virtual service hosted on the Sentinet Node gateway in this case) that can be called by the consumer applications.
- Register Consumer application that can call this registered API.
Register the API
- Sign in to the Azure management portal.
- Click on Active Directory in the left hand navigation pane.
- Click the directory tenant where you wish to register the API.
- Click the Applications tab.
- In the drawer, click Add.
- Click "Add an application my organization is developing".
- Enter a friendly name for the application, for example "AirCarrierAPI ", select "Web Application and/or Web API", and click next.
- For the sign-on URL, enter the base URL for example https://AirCarrier/SignIn. Note in this case this does not have to be any real URL.
- For the App ID URI, enter some URI, for example: https://AirCarrier/API. Click OK to complete the registration.
- While still in the Azure portal, click the Configure tab of your application.
Register Consumer application
- Sign in to the Azure management portal.
- Click on Active Directory in the left hand navigation pane.
- Click the directory tenant where you wish to register the sample application.
- Click the Applications tab.
- In the drawer, click Add.
- Click "Add an application my organization is developing".
- Enter a friendly name for the application, for example "AirCarrierAPIClient ", select "Native Client Application", and click next.
- For the Redirect URI, enter https://AirCarrier/Redirect. Note this does not have to be any real URL. Click finish.
- Click the Configure tab of the application.
- Find the Client ID value and copy it aside, you will need this later.
- In "Permissions to Other Applications", click "Add Application." Select "All Apps" in the "Show" dropdown, and click the upper check mark. Locate & click on the AirCarrierAPI, and click the bottom check mark to add the application. Select "Access AirCarrier" from the "Delegated Permissions" dropdown, and save the configuration.
OAuth Consumer application
The last step in the use case setup is to build the actual API consumer test application. In my case I have built a simple Windows desktop application that is created from the ToDoListClient application published here. My simple version of the GetAirCarrierDelaysClient application can be downloaded with source codes from here. What’s good about this sample application is that it can be easily turned into an application that tests your own OAuth APIs integrated with Azure Active Directory. The sample consumer application uses Microsoft.IdentityModel.Clients.ActiveDirectory.dll and Microsoft.IdentityModel.Clients.ActiveDirectory.WindowsForms.dll that provide built-in User Interface capabilities to implement a sign-in to the Azure Active Directory using Windows account (former Live ID).
Before you run sample consumer application you have to configure its .config file with the settings derived from the Azure Active Directory tenant’s configuration described above. Specifically:
<appSettings>
<add key="aad:Tenant" value="avsad.onmicrosoft.com" />
<add key="aad:AADInstance" value="https://login.microsoftonline.com/{0}" />
<add key="api:ClientId" value="[ClientID-GUID]" />
<add key="api:RedirectUri" value="https://AirCarrier/Redirect" />
<add key="api:ApiResourceId" value="https://AirCarrier/API" />
<add key="api:ApiBaseAddress" value=https://sentinet/SentinetNodeHttp/AirCarrierDelays />
</appSettings>
[ClientID-GUID] must be replaced with the Client ID value captured from the Azure portal during Register Consumer application step described above. The api:RedirectUri value is the Redirect URI from the same step. The api:AirCarrierResourceId value is the App ID URI from the Register the API step. The api:AirCarrierBaseAddress value is the base address of the virtual service hosted on the Sentinet Node.
Make sure you actually add one or more Windows accounts to your Azure Active Directory tenant before running sample consumer application.
When you start sample application you are presented with a single screen where you have to Sign in using Windows account before making a call to Get Air Carrier Delays.
Once you make a call you will see XML ATOM response coming back from the Air Carrier Delay virtual service that called Air Carrier Delay physical API. Monitoring of this message exchange in the Sentinet Console (see screenshot below) shows all the details of the call including all the claims there were issued for the signed-in Windows account by the Azure Active Directory.
Conclusions
Any business API or API customer application can be enabled with the Single-Signed-On and integrations with OAuth servers’ infrastructure with no modification to the API or application itself. On-premises or cloud API Gateways help with such integrations with OAuth security.