API Security

API security involves controlling access to your APIs, guarding against malicious message content, accessing and masking sensitive encrypted data at runtime, protecting your backend services against direct access, and other important safeguards. To provide the API securely we need to understand these questions 

1. Who made the call or who is requesting access? – Authentication
2. Which Application?
3. What is the caller allowed to do or is that use or application allowed to do? – Authorization
4. What did you do? -- Auditing 

But now it’s not about Who can access What anymore, but also When, Where, Why and How?

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 (Confidentiality & Integrity), the ability to identify the calling systems and their end users is a prerequisite. 

Confidentiality

Confidentiality: the information they process is hidden from all users except those users who have been explicitly authorized to see it.

The key basic questions from the confidentiality perspective of security are 

1. Can this user perform this action?
2. Can this app perform this action on user’s behalf?
3. Can this app perform this action?

Integrity

When communicating over the Network, it can be desirable for a server or client to authenticate the sender of a particular message. It can also be desirable to ensure that the message was not tampered with during transit. This document describes a way for servers and clients to simultaneously add authentication and message integrity to messages by using a digital signature.

Integrity: the information they process is trustworthy because it is guaranteed to be correct and free from manipulation, malicious or otherwise, by a third party.

The key basic questions from the Integrity perspective of security are 

1. Is the message received by the API is verified being exactly sent by the App?
2. Is the client verified who it claims to be?
3. Is the Server verified who it claims to be?
4. Has the message been tampered?

API Security - Reference Architecture Design Principles

The following key principles need to be applied when designing the security framework which encapsulates all the aspects of security requirements listed above

1. Design with the objective that the API will eventually be accessible from the public internet
2. Use a common authentication and authorization pattern, preferably based on existing security components: avoid creating a bespoke solution for each API
3. Least Privilege - Access and authorization should be assigned to API consumers based on the minimal amount of access they need to carry out the functions required
4. Maximize entropy (randomness) of security credentials by using tokens rather than username and passwords for API authorization
5. Balance performance with security with reference to key life times and encryption / decryption overheads

App to API security

Every request of the microservice must include a security token that the microservice can easily authenticate and use for making authorization decisions. Hence selecting the format of the security token is one of the key design decision that needs to address the following business requirements/needs

• What should be the token format?

1. Is the token format standardized?
2. Can the token be used with any Protocol (Http and non-Http)?
3. Is the token easy to parse?
4. Can the token be included in the URL parameter?
5. Are there lot of libraries in lots of programming languages for working with the token?
6. Is the token format considered easy to work with?

• How are these tokens obtained?
• What information will these tokens carry?

What token format should be used to secure microservices?

If we observe there were a bunch of standard tokens that were standardized over the years. For example in 1993, we had Kerberos ticket, then in 2002 we had SAML token and in 2015 we had JWT (JSON Web Token). If we analyze these standard tokens, both Kerberos and SAML were protocol specific, Kerberos was in binary format & SAML was in XML format. If you carefully analyze the JWT (pronounced like the English word “jot”), it satisfies most of the above mentioned criteria. Lets delve a little more into JWT tokens

JWT tokens

JWT is not protocol specific, which is based on open standard RFC 7519, that asserts some number of claims. JWTs were designed to be light-weight and to be snuggly passed around in message headers and query strings. To this end, the JSON is split into different parts (header, body, signature) and base-64 encoded.The tokens are designed to be compact, URL safe. JWT claims can typically pass identity of the authenticated users between an identity provider and a service provider or any other types as claimed by the business process. JWT relies on other JSON-based standards: JWS (JSON Web Signature) RFC 7515 and JWE (JSON Web Encryption) RFC 7516

JWTs generally have three parts: a header, a payload, and a signature. The header identifies which algorithm is used to generate the signature, and looks something like this:

header = '{"alg":"HS256","typ":"JWT"}'

HS256 indicates that this token is signed using HMAC-SHA256.

The payload contains the claims to make:

payload = '{"loggedInAs":"admin","iat":1422779638}'

As suggested in the JWT spec, a timestamp called iat (issued at) is installed.

The signature is calculated by base64url encoding the header and payload and concatenating them with a period as a separator:

key           = 'secretkey'
unsignedToken = encodeBase64Url(header) + '.' + encodeBase64Url(payload)
signature     = HMAC-SHA256(key, unsignedToken) 

To put it all together, the signature is base64url encoded. The three separate parts are concatenated using periods:

token = encodeBase64Url(header) + '.' + encodeBase64Url(payload) + '.' + encodeBase64Url(signature) # token is now: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI 

The output is three Base64url strings separated by dots that can be easily passed in HTML and HTTP environments, while being more compact compared to XML-based standards such as SAML. Typical cryptographic algorithms used are HMAC with SHA-256 (HS256) and RSA signature with SHA-256 (RS256). JWA (JSON Web Algorithms) RFC 7518 introduces many more for both authentication and encryption

What information will these token carry?

The JSON data structure or payload will depend on the business needs and can add your claims, but some of the standard fields are

• The issuer
• The subject or the authenticated user (The Resource Owner)
• How the user is authenticated and when?
• Who the token is intended for (i.e. the audience)?

One of the key aspect is to design claims or entitlements. A claim is is a statement that one subject makes about itself or another subject. The statement can be about a name, identity, key, group, privilege, or capability. 

OpenID Connect (OIDC)

OpenID Connect builds on OAuth. OpenID Connect constrains the protocol, turning many of the specification’s SHOULDs to MUSTs. This profile also adds new endpoints, flows, kinds of tokens, scopes, and more. OpenID Connect (which is often abbreviated OIDC) are JWTs designed for low-bandwidth scenarios. By building on OAuth, you will gain both delegated access and federation capabilities with (typically) one product. This means less moving parts and reduced complexity. OpenId Connect defines a standard user identity token and rule for obtaining such tokens. Its much more opinionated

How to obtain these tokens?

As mentioned above the JWT claims can typically pass identity of the authenticated users between an identity provider and a service provider or any other types as claimed by the business process. So generally in an application (lets take a web application) we

1. Authenticate the User
2. When credentials are correct we allow him to log in to the application while creating a JWT token from the correct credential the user provided
3. We send the token to the user
4. The user saves the token in a cookie or in the header of every http request he sends
5. The user doesn t need to authenticate by explicitly giving his credentials, he just needs to send the jwt token in the header of his http request every time he logs in the application

Now the choice changes, whether we simply want some basic 'token authentication' or do we have some standards or protocols which helps the application to generate and use these tokens. We need to simplify from the implementers perspective to reduce the above complexity. Instead of attempting to be a monolithic protocol that solves all aspects of a security system, OAuth 2.0 protocol focuses on one thing and leaves room for other components to do their pieces where it makes more sense. It works on these two principles

1. Separation of concerns
2. Decoupling authentication from the web application, which usually serves business functions

OAuth is a widely used security standard that enables secure access to protected resources in a fashion that’s friendly to web APIs.

1. OAuth is a delegation protocol that provides authorization across systems
2. OAuth replaces the password-sharing anti-pattern with a delegation protocol that is simultaneously more secure and more usable
3. OAuth is focused on solving a small set of problems and solving them well, which makes it a suitable component within larger security systems

The OAuth protocol supports several different types of authentication and authorization (4 to be precise).

• Authorization Grant flow
• Implicit Grant flow
• Resource Owner password credentials
• Client credentials flow

Secondly, the OAuth protocol works by authenticating users via tokens. The idea here is this:

Instead of having your user send their actual credentials to your server on every single request (like they would with Basic Auth, where a user sends their username/password to the server for each request), with OAuth you first exchange your user credentials for a 'token', and then authenticate users based on this 'token'.

The idea of OAuth is that by requiring users to pass their confidential credentials over the network less frequently, less bad things can happen. (This is the idea, anyhow.)

Now, here's where tokens come into play: the OAuth 2.0 RFC 6749 was defined in Oct 2012 is built around the concept of tokens, but DOES NOT SPECIFY WHAT A TOKEN IS.

JWT standard basically provides a set of rules for creating tokens in a very specific way, which makes tokens more useful for you in general. So pretty much everyone in the development community has agreed that if you are using any sort of OAuth, then the tokens you are using should be JWT. The main point here is that tokens (JWTs) are generally useful, and don't NEED to be paired with the OAuth flow.

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts and would make much sense to use OAuth Server to obtain JWT tokens. OAuth2 is basically an authorization delegation protocol. OAuth specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

In security context, the resource owners are the users of the applications, Resource Servers are the data where we store about users (e.g. Account Information in Salesforce, Order Information in SAP, etc.) and Third Party are the application(Web or Mobile Front-End) in the landscape which performs actions on the user data.