OAuth 2.0 is rich –different token types to accommodate different styles. The ‘bearer’ token type provides the simplicity of cookies, the ‘mac’ token type provides the security of hmac signatures. OAuth 2.0 also defines many different flows to accommodate different situations, involving either two or three parties.

Because this rising standard addresses so many use cases, the infrastructure supporting it must remain flexible to cover all of the benefits.

Let’s talk OAuth, see you @RSAConference London, Oct 13 2011 STAR-305.

Another challenge relating to consuming these external APIs is that OAuth handshakes are geared towards a client application driven by a user. The protocol involves a redirection of that user to the API provider in order to authenticate and express authorization. Many enterprise integration (EI) applications do not function in this way. Instead their behavior follows a machine-to-machine transaction type; they operate at runtime without being driven by a user. Wouldn’t it be great if these EI apps could benefit from the OAuth capabilities of the APIs and still operate in headless mode? The so-called ‘two-legged’ OAuth pattern provides a work around for this challenge but requires the client app to hold resource owner credentials, which is problematic, especially when replicated across every client app.

To illustrate how an enterprise API management solution can help manage this challenge, I demonstrate an OAuth tooling geared towards brokering a client-side OAuth session with the Salesforce API using the Layer 7 Gateway. By proxying the Salesforce API at the perimeter using the Layer 7 Gateway, my EI apps do not have to worry about the API provider OAuth handshake. Instead, these EI apps can be authenticated and authorized locally using the Enterprise identity solution of choice and the Layer 7 Gateway manages the OAuth session on behalf of these applications. The benefits of this outbound API proxy are numerous. First, the OAuth handshake is completely abstracted out of the EI apps. In addition, the enterprise now has an easy way to manage control of which applications and enterprise identities can consume the external API, control of the rates of consumption and monitor usage over time. The API can itself be abstracted and the proxy can transform API calls at runtime to protect the consuming apps from version changes at the hosted API side.

To set this up on the Layer 7 Gateway, you first need to register a remote access to your Salesforce instance. Log into your Salesforce instance and navigate to Setup -> App Setup -> Develop -> Remote Access. From there, you define your remote access application. The callback URL must match the URL used by the Layer 7 Gateway administrator at setup time in the Layer 7 Gateway. Make sure you note the Consumer Key and Consumer Secret as they will be used during the OAuth handshake setup; these values will be used by your Layer 7 OAuth broker setup policy.

Using the Layer 7 Policy Manager, you publish your broker setup policies to manage the OAuth handshake between the Gateway and your Salesforce instance. Note that the OAuth callback handling must listen at a URL matching the URL defined in Salesforce. These policies use the consumer key and consumer secret associated with the registered remote access in your Salesforce instance. The secret should be stored in the Gateway’s secure password store for added security. Use templates from Layer 7 to simplify the process of setting up these policies.

Once these two policies are in place, you are ready to initiate the OAuth handshake between the Layer 7 Gateway and the Salesforce instance. Using your favorite browser, navigate to the entry point defined in the admin policy above. Click the ‘Reset Handshake’ button. This will redirect you to your Salesforce instance. If you do not have a session in place on this browser, you will be asked to authenticate to the instance, then you are asked to authorize the client app (in this case, your Layer 7 Gateway). Finally, you are redirected back to the Layer 7 Gateway admin policy which now shows the current OAuth handshake in place. The admin policy stores the OAuth access token so that it can be used by the api proxy at runtime.

Your Layer 7 Gateway is now ready to act as an OAuth broker for your EI apps consuming the Salesforce API. You can publish a simple policy to act as this proxy. This policy should authenticate and authorize the EI app and inject the stored OAuth access token on the way out. Note that this policy can be enhanced to perform additional tasks such as transformation, rate limiting, caching, etc.

Although this use case focuses on the Salesforce API, it is generally applicable to any external API you consume. You can maintain an OAuth session for each API you want to proxy in this Gateway as well as perform identity mapping for other external access control mechanism, for example AWS HMAC signatures.

A key component of this methodology is the AXG migration utility, a policy-based module which interprets an incoming AXG export file in PPF format and automatically populates a Layer 7 Gateway instance with corresponding service proxies and runtime policies. When we first considered the possibility of such a migration utility, we were skeptical about the amount of automation that could be reached due to the differences between both solutions. In the end, what made this possible was the flexibility of the Layer 7 Gateway design and our Gateway Management API facilitating programmatic provisioning. The migration utility uses a customizable stylesheet which can be tailored to the specific AXG setup in order to maximize automation and optimize resulting policy organization. By organizing policies in logical tree structures and grouping similar logic in imported fragments, the resulting configuration in the Layer 7 Gateway reduces the management overhead moving forward.

See this utility in action in the following video.

With its runtime policy enforcement and application level awareness, the Layer 7 Gateway is becoming a preferred component of your PCI-DSS compliant infrastructure. Acting at the perimeter of a service zone, the Layer 7 Gateway authenticates, authorizes and encrypts communications with external entities. Through various pattern recognition mechanisms, the Layer 7 Gateway inspects outgoing messages to filter out unwanted cardholder information leaking from internal systems.

With version 6.0 of the Layer 7 Gateway, Layer 7 Technologies goes beyond encryption and information scrubbing to provide PCI-DSS specific functionality such as a new auditing subsystem which facilitates the obfuscation of card holder information from system logs and audit traces. Version 6.0 of the Layer 7 Gateway also now includes a PCI-DSS Secure Implementation Guide (SIG) manual which covers all the PCI-DSS compliance related settings (you can find this manual from our support portal).

http://apis.acme.com/resources/blah/foo?app_id=myid&app_key=mykey

The term ‘key’ in this case can be misleading. A key is normally used to perform some sort of crypto operation, typically a signature. The use of the API key above is the same as using a password in clear such as in:

http://apis.acme.com/resources/blah/foo?login=mylogin&password=mypassword

In both cases, nothing is signed, and the shared secret is sent alongside each call. If the request is somehow sniffed by a malicious intermediate (think MITM), the malicious user can now impersonate the legitimate requester. A secure channel to send such messages is needed. Even on a secure channel, this type of approach causes a number of security issues. For example, you want to avoid these shared secrets showing up in your traffic logs or being rendered to web pages for a browser based portal.

Other well known API service providers (such as AWS, Azure) use an HMAC signature based authentication model. HMAC (Hash-based Message Authentication Code) uses a hash function combined with a symmetric key. It still uses a shared secret but in this case, the secret is not included in the requests. Instead, the request includes an HMAC signature added to the Authorization HTTP header (the RESTful location for such signatures, tokens). This HMAC covers essential parameters such as the HTTP VERB, the payload, the payload type, a date, etc. Even if the request can be intercepted, the HMAC cannot be re-used beyond a short period of time and cannot be used if any of these critical aspects of the request are altered in any way. Using the same shared secret, the recipient can verify the authenticity of the message and the identity of the requester. Authentication and integrity are both achieved.

Below, an example HMAC construct as used by AWS:

Authorization: AWS + KeyId + : + base64(hmac-sha1(VERB + CONTENT-MD5 + CONTENT-TYPE + DATE + …))

Using the Layer 7 API Proxy, you can use such HMAC signatures to authenticate incoming requests on behalf of a protected API and to add signatures on the way out using the Generate Security Hash Assertion as illustrated below.

Layer 7 Gateway Hashing Assertion

The Generate Security Hash Assertion lets you calculate an HMAC based on the key and data to sign. The data to sign is something that must be agreed upon in advance, as is the way to incorporate the HMAC in the request. When working with an existing system which already defines this (such as AWS), you simply set the variable ${hash.dataToSign} to reflect the same order and contents. If you have the freedom to define this yourself for your own environment, make sure it covers key aspects of a request so that an HMAC cannot be reused if it falls in the wrong hands. For a RESTful web service for example, it makes sense to cover the HTTP verb (method), the request URI, query parameters and payload if any. Adding either a timestamp or a validity period is also good practice.

Once you calculated an HMAC in your policy using this assertion, you can inject it to an outgoing message by adding it to the Authorization HTTP header directly as illustrated below. Note that you can include this HMAC in any desired header.

Injecting an HMAC downstream

For verifying an incoming HMAC, construct your policy to calculate the hash based on the input and compare this value against the incoming HMAC value using a simple comparison assertion.

Validating an incoming HMAC

SOA Gateways gained popularity in recent years as a lightweight ESB that can span departmental boundaries. Like software ESBs, SOA Gateways can translate data formats, route content, service-enable data sources and switch between transport protocols. But SOA Gateways have a number of significant advantages over traditional software ESBs. For example, they scale easily and accommodate high volume traffic environments owing to their specialized acceleration of message validation, routing and translation. Also, SOA Gateways offer comprehensive security and identity federation features built in so they can be deployed at the service zone perimeter (think DMZ).

Looking back, the pattern of using an SOA Gateway to integrate and service-enable existing IT assets has been a large success. Because of the appliance form factor and the configure, not code approach, the cost of integration and the time to react to new requirements both shrunk considerably. And with a focus increasingly shifting towards cloud computing, this ability to quickly accommodate new integration mechanisms has already paid off for those who invested in the lightweight, agile solution. This is especially the case for those who opted for the virtual appliance form factor.

I like to refer to this pattern as the Enterprise Service Gateway (ESG). That is, the ability to execute integration, transformation and security using a specialized gateway appliance as opposed to coding using traditional software ESB frameworks.

About a year ago, I was proposing a simple approach for enabling RESTful web service requesters with SAML-based tokens for authentication/authorization. The pattern enabling a REST client to access a service using a SAML token is illustrated below.

SAML for REST

The fact that there are still no definitive SAML bindings targeting RESTful web services today does not seem to deter developers from leveraging SAML to control access to their RESTful web services. We encountered this again recently in the field in the form of a proof of technology project in which the main objective was to demonstrate the Layer 7 Gateway acting both as the token issuer for a REST client as well as an API proxy which controls access based on those very tokens. Two token formats were requested: SAML and OAuth.

For our gateway to authenticate RESTful requesters and issue tokens is a very common and straightforward process. In order for the REST client to be able to use this token however, it must be able to insert it in an Authorization header (the RESTful location for this token). In the case where the token is a SAML assertion, it can exceed in size the practical limit of what can be used as an HTTP header value (a rich SAML assertion with an XML digital signature can be quite verbose). This is where the Layer 7 Gateway policy language flexibility shines. By simply declaring the compression (gzip assertion) of the resulting SAML before sending it back to the client, the token has now been shrunk to a manageable size for the client. The reverse decompression at reception is just as straightforward using the reverse operation in our policy language.

SAML idp for REST with token compression

Note that although we could just as well create a session on the Gateway and return a cookie back to the requester, we are interacting with a REST client here; this is not a browser-driven interaction. Besides, server side sessions are not RESTful. If the client re-sends the token at each call, the authorization of the requester is validated each time through the evaluation of the SAML statements and this does not require any server-side session.

When implementing the same use case, but with a token format based on OAuth instead of SAML, this compression/decompression step is no longer needed. The rest of the configuration using our Gateway policy language is very similar. This compression is one of the technical tradeoffs when choosing between such token formats and relates to the so-called “open” vs “enterprise” identity camps. On one hand, you have a rich and standardized token format (SAML), which can be used to express a variety of statements about an identity. On the other hand you have a simple and lean token format but less standardized. On that last point, what constitutes an OAuth token format in this particular context is a bit of a moving target and various interpretations are not necessarily compatible.

In the end, choosing a token format should consider the requirements around authorization and the technical capabilites of the parties involved. Better yet, don’t narrow your support on a single format. Support and enable different token formats instead if that is what is needed.

When selecting supporting infrastructure to manage APIs and broker with cloud or partners, keep in mind this need to accommodate arbitrary authentication approaches. Although rich standard support provides value, the essential ingredient of an agile service gateway is its flexibility and its extensibility.

Register for this webinar here.

In an upcoming service pack for version 5.4 of our SOA Gateway and subsequent releases, we are introducing a number of additional controls pertaining to service resolution. One of them lets the administrator change the default behavior of the Gateway so that resolution paths are matched ignoring case. This simplifies the process of accommodating requesters that are not URL “case-aware”, and mediating between services which respect this aspect of URLs and services which do not.

What I find most interesting however, is how our users, support team and field engineers have been using our technology until now to accommodate such requirements. Using our sophisticated and fine-grained resolution subsystem, some users register a “/*” endpoint to catch all messages that do not get explicitly resolved to other published services (for example because of character case mismatch). Once in this “/*” policy, you can feed the incoming URL into a simple XSLT which produces a lowercase version of the URL, then circle the request back to the Gateway using the resulting URL so that the intended service gets invoked. This is pretty straightforward.

A catch-all policy is great at processing traffic which is not expected at design time and doing something useful with it. However, the use of wildcard characters in service resolution parameters is not limited to setting up a catch-all policy. You can publish services with such resolution patters to handle in a single policy, requests following a common pattern. For RESTful web services, such resolution parameters are essential such as illustrated in this tutorial.

Flexible and customizable service resolution patterns have always been a key ingredient in sophisticated service mediation and complex routing rules. Look for advancements in this area and more in v5.4 service pack 1 of the Layer 7 Gateway solution.

Recent use cases for these types of devices largely focused on B2B interactions and internal enterprise integration. Many enterprise architects realized the benefits of using the lightweight ESB-in-a-box deployment model and gateway-based integration. I don’t think we’ve hit the peak of this type of use case. I expect the demand for quickly deployed integration, and a preference for “configure, not code” to continue to accelerate in 2011. The cost and complexity involved in deploying full-blown software-based ESB stacks is becoming well known and the alternative provided by best of breed SOA gateways with their out of box support for existing enterprise standards will continue to gain popularity.

Another source of momentum for SOA gateways is the enterprise adoption of cloud computing. As the enterprise gradually moves some of its IT assets from on-premise to a cloud-based deployment model (SAAS, PAAS or IAAS), the requirement for integration between these IT assets does not simply vanish. Integrating your IT assets is as important in 2011 as it was back when they were all deployed in your own domain. Cloud computing adoption is currently limited by the ability of the enterprise to securely integrate on-premise and off-premise. And what better way is there to enable this secure integration than perimeter deployed SOA gateways? The SOA gateway acts as the glue between your on-premise IT assets and external services that they interact with. Concretely, this means support for federation and trust management. Your SOA gateway at the perimeter is enabling the trust management for the various external domains you interact with and presents a homogenous identity authority on behalf of your existing services. Utilizing the federation capabilities of SOA gateways with support for SAML, OAuth and other relevant standards is increasingly recognized as a winning pattern for integrating enterprise and cloud.