Choosing API Security Options Fostering API Ecosystems

Choosing appropriate API security options will help you gain developer trust, increase API adoption, and build an effective API ecosystem.  While APIs are the ‘coolest’ and most effective mechanism to expose business functionalities out towards the outside world and inward to other teams, API security requires learning new technologies (i.e. OAuth, MAC token profiles, and JSON Web Token [JWT]) and retrofitting existing identity management architecture with token chaining and identity brokering.


Many mobile application developers and architects find API security and identity options are arcane, jargon-filled, and confusing.   They frequently ask whether selecting one choice over another is appropriate – and you need to cautiously identify and isolate  tradeoffs.  A robust API security platform can help guide you in the right direction.

API Security Basics

Security is not an afterthought. Incorporate security as an integral part of any application development project. The same approach applies to API development as well. API security has evolved significantly in the past five years. The recent standards growth has been exponential. OAuth and bearer tokens are the most widely adopted standard, and are possibly now the de-facto standard for API security.

What API security decisions should you consider?

A few common API security decisions include:

  • How to pass a token used to authorize the API request
  • How to assert user identity to the API
  • How to propagate token revocation actions
  • How to transform (chain) access credentials


Securing Access with OAuth

Two divergent flavors of OAuth exist, 1.0 and 2.0.  OAuth 1.0 is a standard built for identity delegation. OAuth 2.0 is a highly extensible authorization framework, which is a significant attribute and selling point.

OAuth 2.0 exposes three major authorization process phases:

  1. Requesting an Authorization Grant
  2. Exchanging the Authorization Grant for an Access Token
  3. Access the resource with the Access Token

Access Tokens and Profiles

A security architecture must specify a token format that communicates identity and entitlement assertions. The access token contains the information required to successfully make a request to the protected resource (along with type-specific attributes).  Access tokens are associated with profiles that specify how to communicate and interpret access token requests, access token responses, and interactions with protected resources.

The OAuth 2.0 core specification does not mandate a specific access token type. The authorization server (who grants authorization) chooses an acceptable token type, and the requester or client does not dictate the token type. The Authorization Server decides which token type is to be returned during Phase 2 when crafting the Access Token response.

An access token type definition may specify additional attributes (if any) sent to the client together with the “access_token” response parameter. The type also defines the HTTP authentication method used to include the access token when making a request to the protected resource.

Bearer Token Profile

Web applications commonly rely on SAML tokens or proprietary session cookies.  Most API security implementations today rely on Bearer Token Profiles. A Bearer token is a randomly generated string created by the authorization server and returned as a response to the client in Phase 2. Any client in possession of the token can use the token to access a secured API.

The underlying token transport channel (e.g. TLS) enforces token integrity and privacy.  TLS only provides the security while in transit. The OAuth Token Issuer (or the Authorization Server) and  OAuth client are responsible to protect the access token while the token is at rest (stored in memory or on disk). In most cases, the access token needs to be encrypted. Moreover, the token issuer needs to guarantee the randomness of the generated access token, and the encryption has to be sufficient enough to exhaust any brute-force attacks.

MAC Token Profile

Rather than rely on a static random string known by both the client, authorization server, and resource server, the MAC token profile does not directly pass the  access token to the resource server.  The profile relies on client-side code to sign the resource request with a shared session key, and the resource server checks the signature. The client uses the signature algorithm, access token and the MAC key to calculate the request token passed to the resource server.

The OAuth authorization server will issue a MAC key along with the signature algorithm, session key,  nonce and an access token.  The access token  can be used as an identifier for the MAC key. The client signs a normalized string derived from request attributes. Unlike in Bearer token, the MAC access token will never be shared between the client and the resource server. The MAC access token is only known to the authorization server and the client.

The MAC token profile is more complex than the Bearer token profile, and requires both the client and resource server to perform more sophisticated processing logic.

Making the Assertion 

Sending a access token (e.g. Bearer, MAC) to pass an authorization gate is just one piece of the security puzzle.

A partner employee can login to a web application using SAML2 SSO (you have to trust the partner’s SAML2 IdP) and  the web application can then access a secured API on behalf of the logged in user. The web application will use the SAML2 assertion  provided by the identity provider, and exchange the SAMl2 assertion for an OAuth access token via SAML2 grant type.

The SAML 2.0 Bearer Assertion Profile, which is built on top of OAuth 2.0 Assertion Profile, defines SAML 2.0 Bearer Assertion requests for an OAuth 2.0 access token in addition to authenticating the client. Under OAuth 2.0,  requesting an access token is known as a grant type.

JSON Web Token (JWT) Assertions

JSON Web Token (JWT) Bearer Profile is almost the same as the SAML2 Assertion Profile. Instead of SAML tokens, JWT uses JSON Web Tokens.

Linking Tokens with Associated Data

The Internet draft OAuth Token Introspection, which is currently being discussed under the IETF OAuth working group, defines a method for a client or a protected resource (resource server) to query an OAuth authorization server and determine metadata about an OAuth token. The resource server sends the access token and the resource id (which is going to be accessed) to the authorization server’s introspection endpoint. The authorization server can check the validity of the token, evaluate any access control rules around it, and send back the appropriate response to the resource server. In addition to  token validity information, the response will detail token scopes, client_id, and any additional metadata associated with the token.

Link Tokens with Identity

When using OAuth 2.0, the client application is not required to know the end user (only exception is resource owner credentials grant type). The client simply obtains an access token to access a resource on behalf of a user. How does the application obtain an identity that can be asserted to the resource provider?

OpenID Connect is a profile built on top OAuth 2.0. OAuth talks about access delegation while OpenID Connect talks about authentication. In other words, OpenID Connect builds an identity layer on top of OAuth 2.0.   With OpenID Connect, the client will get an ID Token in addition to the access token. ID Token represents the end user’s identity.

In-depth API Security

To learn more about  security specifications and how to implement API security, check out the following resources:

API Security Ecosystem White Paper

An Ecosystem for API Security Presentation: OAuth 2.0, OpenID Connect, UMA, SAML, SCIM, and XACML

Best Practices in Building an API Security Ecosystem