Give me a JWT, I’ll give you an Access Token

January 4, 2013

One of the common misconceptions about OAuth is that it provides identity federation by itself. Although supporting OAuth with federated identities is a valid pattern and is essential to many API providers, it does require the combination of OAuth with an additional federated authentication mechanism. Note that I’m not talking about leveraging OAuth for federation (that’s OpenID Connect), but rather, an OAuth handshake in which the OAuth Authorization Server (AS) federates the authentication of the user.

There are different ways to federate the authentication of an end user as part of an OAuth handshake. One approach is to simply incorporate it as part of the authorization server’s interaction with the end user (handshake within handshake). This is only possible with grant types where the user is redirected to the authorization server in the first place, such as implicit or autz code. In that case, the user is redirected from the app, to the authorization server, to the idp, back to the authorization server and finally back to the application. The federated authentication is transparent to the client application participating in the OAuth handshake. The OAuth spec (which describes the interaction between the client application and the OAuth Authorization Server) does not get involved.

illustration1

Another approach is for the client application to request the access token using an existing proof of authentication in the form of a signed claims (handshake after handshake). In this type of OAuth handshake, the redirection of the user (if any) is outside the scope of the OAuth handshake and is driven by the application. However, the exchange of the existing claim for an OAuth access token is the subject of a number of extension grant types.

One such extension grant type is defined in SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 specification according to which a client application presents a SAML assertion to the OAuth authorization server in exchange for an OAuth access token. The Layer 7 OAuth Toolkit has implemented and provided samples for this extension grant type since its inception.

illustration2

Because of the prevalence of SAML in many environments and its support by many identity providers, this grant type has the potential to be leveraged in lots of ways in the Enterprise and across partners. There is however an alternative to bloated, verbose SAML assertions emerging, one that is more ‘API-friendly’, based on JSON: JSON Web Token (JWT). JWT allows the representation of claims in a compact, JSON format and the signing of such claims using JWS. For example, OpenID Connect’s ID Tokens are based on the JWT standard. The same way that a SAML assertion can be exchanged for an access token, a JWT can also be exchanged for an access token. The details of such a handshake is defined as part of another extension grant type defined as part of JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0.

Give me a JWT, I’ll give you an access token. Although I expect templates for this extension grant type to be featured as part of an upcoming revision of the OAuth Toolkit, the recent addition of JWT and JSON primitives enables me to extend the current OAuth authorization server template to support JWT Bearer Grants with the Layer 7 Gateway today.

The first thing I need for this exercise is to simulate an application getting a JWT claim issued on behalf of a user. For this, I create a simple endpoint on the Gateway that authenticates a user and issues a JWT returned as part of the response.

idppolicy

Pointing my browser to this endpoint produces the following output:

idoutput

Then, I extend the Authorization Server token endpoint policy to accept and support the JWT bearer grant type. The similarities between the SAML bearer and the JWT bearer grant types are most obvious in this step. I was able to copy the policy branch and substitute the SAML and XPath policy constructs for JWT and JSON path ones instead. I can also base trust on HMAC type signatures that involve a share secret instead of a PKI based signature validation if desired.

newAS

I can test this new grant type using REST client calling the OAuth Authorization Server’s token endpoint. I inject in this request the JWT issued by the JWT issuer endpoint and specify the correct grant type.

illustration5

I can now authorize an API call based on this new access token as I would any other access token. The original JWT claim is saved as part of the OAuth session and is available throughout the lifespan of this access token. This JWT can later be consulted at runtime when API calls are authorized inside the API runtime policy.


OAuth Client Broker Tooling

September 16, 2011

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.