Reading Time: 26 minutes

This post will be part 1 of 3 for my ultimate guide to API security best practices series. In this post, I will be discussing the current concerns IT decision makers have in regards to their current digital assets.

Part 2 – API security: Keeping data private but accessible will address the need for keeping data private and protecting it from being compromised while making it accessible at all times.

latest report
Learn why we are the Leaders in API management and iPaaS

Part 3 – API security: Platform capabilities and API-led Connectivity example will present a fictitious scenario that shows you how Anypoint platform can form part of the fabric of a secure API-led architecture.

Current state of APIs

APIs have become a strategic necessity for your business. They facilitate agility and innovation. However, the financial incentive associated with this agility is often tempered with the fear of undue exposure of the valuable information that these APIs expose. With data breaches now costing $400M or more, senior IT decision makers are right to be concerned about API security.

A secure API is one that can guarantee the confidentiality of the information it processes by making it visible only to the Users, Apps, and Servers that are authorized to consume it. Likewise, it must be able to guarantee the integrity of the information it receives from the Clients and Servers with which it collaborates so that it will only process such information if it knows that it has not been modified by a third party. To guarantee these two security qualities, the ability to identify the calling systems and their end-users is a prerequisite. What we have stated also apply to those calls that the API makes to third party Servers. An API must never lose information so it must be available to handle requests and process them in a reliable fashion.

users apps clients servers

1. Identity

Identity is core to the world of security. You must be able to recognize the Apps that consume your API, the Users of the same and the Servers that your API calls out to. Likewise, your API should be able to identify itself to both Apps and Servers. You need an Identity Store to which you can refer to verify your recognition of Apps and Users. The Identity Store could be a database, but an LDAP server is the most popular solution. Active Directory is a popular LDAP implementation. In an LDAP server, you typically store usernames, passwords, digital certificates, some personal details and the organization groups to which Users belong. App IDs can also be stored here. An Identity Provider is software which is dedicated to managing the interaction with the Identity Store(s) for authentication and authorization purposes. Your API can function in this role though it is much more preferable to delegate this responsibility to the Identity Provider.

identity provider and identity store

1.1 User and App Authentication

When you are presented with an App ID or a User’s username (claim) in a call to your API, you must be able to verify the authenticity of the claim. This is done with some form of a shared secret. When your API acts as Identity Provider, it typically authenticates the claim by passing the same credentials to the LDAP server.

1.1.1 Username and Password Credentials

This is the simplest form of authentication. When it is exposed to Users, it places the burden of memorizing the password on them. When it is realized with system-to-system authentication, then a password to a Server may end up being shared by multiple other APIs. The use of username / password pairs as credentials is a very common practice but it is not recommended from two perspectives: Passwords have a level of predictability whereas the ideal is to maximize on randomness or entropy. Username / password pairs are a low entropy form of authentication. The maintenance of passwords is difficult. If you need to change a password, then you immediately affect all Apps that make use of that password. Until each of these has been reconfigured you have broken communication with them. As a consequence, there is no way you can block access to one App in particular without blocking all the Apps that use the same username and password.

1.1.2 Multi-factor Authentication

Recognizing the weakness of username and password credentials, an App using Multi-factor Authentication (MFA) demands from the User a one-time usage token she receives after authenticating with her credentials. This token may be delivered to her through SMS when the App requests a Multi-factor Authentication (MFA) Provider to do so. The User may also have a digital key which provides her with a token that the App can validate. An RSA SecurID is an example of this. When the App receives the token which it validates with the MFA Provider, it proceeds to consume your API.

1.1.3 Token based credentials

A better alternative to Username Password Credentials are token based credentials, which provide higher entropy and a more secure form of authentication and authorization. The idea is for the Identity Provider to issue tokens based on an initial authentication request with username / password credentials. From then on the App only has to send the token, so the net result is a great reduction in username / password credentials going to and fro over the network. Also, tokens are usually issued with an expiration period and can be revoked. Furthermore, because they are issued uniquely to each App, when you choose to revoke a particular token or if it expires, all the other Apps can continue to use their tokens independently.

token based credential
In Figure 3, Janet signs into her App. The App authenticates her and requests a token from the Identity Provider. This authenticates her with the Identity Store and then responds to the App with a token. The App proceeds to call the API with the token.

1.2 API and Server Authentication

Your API must be able to authenticate itself to the Apps which consume it. Likewise when your API interacts with Servers, they must authenticate themselves to the API. In both cases you strive to avoid man-in-the-middle attacks which sometimes take the form of malicious software pretending to be a Server or indeed your API.

1.3 User and App Authorization

1.3.1 Role Based Access Control Typically, every business, enterprise or organization is divided into groups of employees around related business functions. For example, think of the Nursing team and the Medical doctor team and the catering team in a hospital. The employees working within an organization have a static function defined by these group boundaries.

This group information can be used when software Users interact with an App and you need to restrict their access according to the authorization or access control rule in place for that software. You can use the group they belong to in order to identify their role when using the App. Groups are role and App agnostic. They are purely business level divisions. LDAP servers use the concept of groups for this purpose. Identity Providers are responsible for retrieving this group information from the Identity Store. A role is an App specific definition of access control. A User will typically adopt multiple roles defined by each App she uses.

Role based Access Control (RBAC) represents a very simple access control mechanism. An App need not keep a record of each User’s level of access to its functions and data. Rather it uses roles to abstract away from those details and assign degrees of access to groups of Users which the role represents.

1.3.2 Attribute-based Access Control

Going beyond the static assignment of roles to Users based on the organizational groups to which they belong, Attribute based Access Control (ABAC) aims to facilitate the dynamic determination of access control based on some sort of circumstantial information available at the time of the API call. Things like the time of day, the role, the location of the API, the location of the App and combinations of conditions contribute to the determination of the degree of access. XACML is a standard which defines the rules that must be executed in order to evaluate the level of access at the time of the API call. The understanding is that this may change from call to call. ABAC often dictates the requirement that your API will respond with subsets of data according to the access control decisions related to the User.

1.3.3 Delegated Access Control with OAuth 2.0

The HTTP based OAuth 2.0 framework allows an App to obtain access to a resource exposed by your API either on its own behalf or on behalf of the User who owns the resource. Thus it allows Users to delegate access control to third party Apps. To facilitate this, your API must collaborate with an OAuth 2.0 Authorization Server, checking each incoming call for an access token which it must validate with the Authorization Server. The response from the Authorization Server will indicate whether the access token is valid (it was issued by the OAuth Provider and it hasn’t expired) as well as the scope of access for which the token was issued.

1.4 Federated Identity

The token based approach to authentication allows for the separation of the issuing of tokens from their validation and thus facilitates the centralization of Identity Management. The developer of each API need only concern herself with incorporating validation logic within the API so that upon invocation, it looks for the token in the request and then validates it with the centralized Identity Provider. If the token is deemed to be valid (the user or App to whom the token was issued have sufficient authorization for this call), then the API should proceed to process the call. The parties involved in this call form part of a single security context. In other words, the Identity Provider is able to recognize and authenticate the App, the User and the API because their identity and shared secret password are in its Identity Store. However, your API will not always be exposed to an App and User which the Identity Provider can possibly recognize. What if you wish to expose your API to an App in the hands of a User from another company or even from another Business Unit within your own company? Large companies can have many security contexts with separate Identity Stores and Providers. Federated Identity solves this problem and federated Identity Providers collaborate to facilitate the authentication and authorization of Users who belong to different security contexts.

federated identity
In Figure 4, Janet signs into her App. The App authenticates her and requests a token from the Orders Identity Provider. This authenticates her with the Orders Identity Store and then responds to the App with a token. The App proceeds to call either the Orders API or the Shipping API. In both cases the Orders Identity Provider validates the token. The Orders Identity Provider and the Shipping Identity Provider are federated. The Shipping Identity Provider knows that the token has been signed by the Orders Identity Provider to which it delegates the token validation.

1.4.1 Single Sign-on Multi Experience

The Security Assertion Markup Language (SAML) is an industry standard which has become a defacto standard for Enterprise level Identity Federation. It allows Identity Providers to communicate authentication and authorization information about Users to Service Providers in a standard way.

A SAML Assertion can be issued by an Identity Provider in one security context and be inherently understandable by an Identity Provider in another context. SAML assertions typically convey information about the User including the organizational groups to which the User belongs, together with the expiry period of the assertion. No password information is provided. The Identity Provider which issues the assertion signs it. The Identity Provider which has to validate the assertion must have a trust relationship with the issuing Identity Provider (see Digital Signatures 2.1.1). The primary driver for the use of SAML for use within the Enterprise is Single Sign-on (SSO). Users don’t have to keep separate identities for every application software that they use. Rather they sign on once with an Identity Provider and 8 from then on any links to applications allow them to bypass the login page of each of these. Such a setup ultimately delivers the desired User experience of not having to maintain multiple sets of username and password credentials and of signing in once and subsequently bypassing login pages to all of the applications within the enterprise. This SSO experience is usually delivered with a UI Portal which has links to all relevant applications that eliminate the need for any further authentication by the User.

SAML can also be used within the context of APIs. We explore this next.

1.4.2 Single Sign-on Single Experience

The expectation that an Identity Provider in one security context will understand a token issued by an Identity Provider in another security context may very well be reasonable within the boundaries of a particular Enterprise. However, this may not be so for external company acquisition scenarios and for dealings with partners and SaaS. The industrial standards which we will explore next facilitate the necessary interoperability which allows for any API to deliver its service to Apps while relying upon a federated Identity Provider for the authentication and authorization of the Users which are outside of its security context.

1.4.2.1 WS-Security with SAML Assertions

WS-Security (in particular WS-Trust) allows Identity Providers to expose SOAP Web Services that will issue identity tokens to requesting Apps. A SAML Assertion is one such possible token. The same App can then invoke a SOAP Web Service with the SAML Assertion in the header.

WS-Security also caters for the general needs of Integrity and Confidentiality through XML Signature and XML Encryption (see Message Integrity and Message Confidentiality below).

1.4.2.2 OpenID Connect with JWT ID Tokens

OpenID Connect is built on top of OAuth 2.0 to provide a Federated Identity mechanism that allows you to secure your API in a way similar to what you would get were you to exploit WS-Security with SAML. It was designed to support native and mobile apps while also catering for the enterprise federation cases. It is an attractive and much more lightweight approach to achieving SSO within the Enterprise than the corresponding WS-Security with SAML. Its simple JSON / REST based protocol has resulted in its accelerating adoption.

Apart from OAuth 2.0 access tokens, OpenID Connect uses JWT (jot) ID tokens, which contain information about the authenticated User in a standardized format. Your API can make an access control decision by calling out to a UserInfo endpoint on the Identity Provider to verify if the User pertains to a certain role. Just like SAML Assertions, JWT ID tokens are digitally signed (see Digital Signatures 2.1.1) so a federated Identity Provider can decide to accept them based on its trust relationship with the Identity Provider that issued them.

What’s next for API Security?

In this series, I’ll continue to show how MuleSoft’s Anypoint Platform can ensure that your API is highly available to respond to clients and can guarantee the integrity and confidentiality of the information it processes. We explore in depth the main security concerns and look at how the IT industry has responded to those concerns with different types of methods. We present Anypoint Platform as fully capable of managing and hosting APIs that are secure according to the highest industry standards.

If you want to read ahead and learn more in detail about API Security, you can download the full Protect Your APIs whitepaper.