OAuth Token Management

Tokens are at the center of API access control in the Enterprise. Token management, the process through which the lifecycle of these tokens is governed emerges as an important aspect of Enterprise API Management.

OAuth access tokens, for example, can have a lot of session information associated to them:

• scope;
• client id;
• subscriber id;
• grant type;
• associated refresh token;
• a saml assertion or other token the oauth token was mapped from;
• how often it’s been used, from where.

While some of this information is created during OAuth handshakes, some of it continues to evolve throughout the lifespan of the token. Token management is used during handshakes to capture all relevant information pertaining to granting access to an API and makes this information available to other relevant API management components at runtime.

During runtime API access, applications present OAuth access tokens issued during a handshake. The resource server component of your API management infrastructure, the gateway controlling access to your APIs, consults the Token management system to assess whether or not the token is still valid and to retrieve information associated to it which is essential to deciding whether or not access should be granted. A valid token in itself is not sufficient, does the scope associated to it grant access to the particular API being invoked? Does the identity (sometimes identities) associated with it also grant access to the particular resource requested? The Token management system also updates the runtime token usage for later reporting and monitoring purposes.

The ability to consult live tokens is important not only to API providers but also to owners of applications to which they are assigned. A Token management system must be able to deliver live token information such as statistics to external systems. An open API based integration is necessary for maximum flexibility. For example, an application developer may access this information through an API Developer Portal whereas a API publisher may get this information through a BI system or ops type console. Feeding such information into a BI system also opens the possibility of detecting potential threats from unusual token usage (frequency, location-based, etc). Monitoring and BI around tokens therefore relates to token revocation.

As one of the main drivers of API consumption in the enterprise is mobile applications, the ability to easily revoke a token when, for example, a mobile device is lost or compromised is crucial to the enterprise. The challenge around providing token revocation for an enterprise API comes from the fact that it can be triggered from so many sources. Obviously, the API provider itself needs to be able to easily revoke any tokens if a suspicious usage is detected or if it is made aware of an application being compromised. Application providers may need the ability to revoke access from their side and, obviously, service subscribers need the ability to do so as well. The instruction to revoke a token may come from Enterprise governance solutions, developer portals, subscriber portals, etc.

Finally, the revocation information is essential at runtime. The resource server authorizing access to APIs needs to be aware of whether or not a token has been revoked.

The management of API access tokens is an essential component of Enterprise API management. This token management must integrate with other key enterprise assets, ideally through open APIs. At the same time, token data must be protected and its access secured.

API management – Infrastructure VS SaaS

The Enterprise is buzzing with API initiatives these days. APIs not only serve mobile applications, they are increasingly redefining how the enterprise does B2B and integration in general. API management as a category follows different models. On one hand, certain technology vendors offer specialized infrastructure to handle the many aspects of API management. On the other, an increasing number of SaaS vendors offer a service which you subscribe to, providing a pre-installed, hosted, basic API management system. Hybrid models are emerging, but that’s a topic for a future post.

Before opting for a pure SaaS-based API management solution offering, consider these below.

The Cloud Advantage
One can realize the benefits of cloud computing from an API management solution without losing the ability to control its underlying infrastructure. For example, IaaS solutions let you host your own API management infrastructure. Private clouds are also ideal to host API management infrastructure and provide the added benefit of running ‘closer’ to key enterprise it assets. Through any of these SaaS alternatives, an API management infrastructure optimizes computing resources utilization. IaaS and private cloud based API management infrastructure also provide elasticity and can scale on-demand. Look for API management solutions that offer a virtual appliance form factor to maximize the benefits of cloud.

Return on investment
The advantage of a lower initial investment from SaaS delivered API management solutions quickly becomes irrelevant when the ongoing cost of a per-hit billing structure increases exponentially. With your own API management infrastructure in place, you leverage an initial investment over as many APIs as you want to deliver, no matter how popular the APIs become. Many early adopters, which originally opted for the SaaS model, (notably the more successful APIs) are currently making the switch to the infrastructure model in order to remedy a monthly cost that has grown to unmanageable levels. Unfortunately, such transitions are sometimes proving more costly than any initial costs savings.

Agility, Integration
SaaS solutions provide easy-to-use system isolated in their own silo. This isolation from the rest of your enterprise IT assets creates a challenge when you attempt to integrate the API management solution with other key systems. Do you have an existing web portal? How about existing identity, business intelligence, billing systems? If your API management solution is infrastructure based, you have access to all the low level controls and tooling that are required to integrate all these systems together. Integrating your API management with existing identity infrastructure can be important to achieve runtime access control. Integrating with billing systems is crucial to monetize your APIs. Feeding metrics from an API management infrastructure into an existing BI infrastructure provides better visibility, etc.

Security
Depending on the audience for your APIs, various regulations and security standards may apply. Sensitive information travelling through a SaaS is outside of your control. Are any of your APIs potentially dealing with cardholder information? Does PCI-DSS certification matter? If so, a SaaS-based API management solution is likely to be problematic. In addition to the off-premise security issue, SaaS based API management solutions offer limited security and access control options. For example, the ability to decide which versions of OAuth you choose to implement matters if you need to cater to a specific breed of developers.

Performance
Detours increase latency. By routing API traffic through a hosted system before getting to the source of the data, you introduce detours. By contrast, if you architect an API management infrastructure in such a way that the runtime controls happen in direct path of transaction, you minimize latencies. For example, using the infrastructure approach, you can deploy everything in a DMZ. Also, by owning the infrastructure, you have complete control over the computing resources allocated to it.

Let’s talk OAuth @RSAConference

A lot has changed about the state of OAuth since I last presented at RSA Conference. Last year, the enterprise was screaming for standardized mechanics to provide access control to their APIs. Back then, OAuth was merely on the Enterprise Architect’s radar. It’s now safe to say that OAuth 2.0 is poised to fill this gap.

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.

OAuth Client Broker Tooling

In terms of OAuth enterprise tooling, a lot of focus is given to OAuth-enabling APIs exposed by the enterprise itself. Naturally, the demand for this reflects today’s reality where the enterprise is increasingly playing the role of an api provider. However, many enterprise integration use cases involving cloud-based services puts the enterprise in the role of API consumer, rather than provider. And as the number of enterprise applications consuming these external APIs grows, and the number of such external APIs themselves grows, point-to-point OAuth handshakes become problematic.

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.

AXG migration made easy

The Cisco Ace XML Gateway (AXG) product is quickly nearing its end of life. Last year, Layer 7’s field team completed a number of successful AXG replacement projects and the rate of such projects has since picked up considerably. Layer 7 is now releasing the Cisco ACE XML Gateway Migration Guide. This guide includes a step-by-step methodology, which builds on our experience in AXG migration type projects.

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.

PCI-DSS Compliant Service Oriented Infrastructure

The payment card industry data security standards (PCI-DSS) requires increased controls of cardholder information to minimize credit card fraud. Although PCI-DSS compliance is specific to the payment industry, the principles of securing user or subscriber information from leaks or cyber attacks apply to most service providers, enterprises and governments. Such principles have been core to the Layer 7 Gateway solution since its inception.

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).

Using API keys effectively

A common use of API keys for authentication of web api consumption is to ask the requester to just include the key directly in the URI parameters of the web API call as illustrated below:

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

The ESG pattern

Are you still considering rolling out a major Enterprise Service Bus (ESB) stack — you know, the kind that involves a massive initial investment and takes 8+ months to deploy? This wasteful approach was a major factor in doomed corporate SOA initiatives that were common between 2003 and 2009. During this same period, clever architects ignored large vendor promises and realized that you simply cannot buy your way into an agile enterprise SOA. They instead focused on the tasks at hand, integrating existing IT assets, following SOA principles, using existing tools and adding lightweight strategic and specialized infrastructure to help them along the way. The winning enterprise SOA initiatives are the ones who made sure that the SOA was operational as it evolved.

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.

Selecting a token format for your Web APIs, RESTful web services

The most important token format that you need to support for your web apis and RESTful web services these days is: anything. So many platforms define their own authentication/authorization mechanism with what seems to be little concern for standardized formats: API keys here, HMAC signatures there, various OAuth interpretation, etc. Simple does trump standards. For the integration-focused enterprise architect, this reality creates a need for flexible infrastructure supporting arbitrary token formats.

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.

Choosing an XML Gateway

Two weeks ago, I posted about SOA Gateway trends that have been emerging lately. If you are interested in this topic or if you are in the process of setting up an SOA infrastructure, you will not want to miss tomorrow’s (Jan 27, 2011) webinar : “How to Choose a SOA Gateway: Lessons from the Field”. This will cover topics such as Portability Considerations, Scalability Risks, Extensibility and Upgradeability, Global Management Implications and Hidden Operation Costs.

Register for this webinar here.