Authentication and Authorization of API Calls

APIs are widely used, and theoretically anyone can call any API. However, it is the job of the API provider to make sure every caller has the necessary rights to access their APIs and will do no harm to the underlying system or misuse the data provided by the API. Therefore, it is critical to know who is calling and for what purpose. Specific mechanisms for the authentication and authorization of API calls guarantee the legitimacy of callers. Here’s how these mechanisms work.

Authorization vs Authentication

API authentication and authorization are two terms that are often mixed up and misused. The abbreviation Auth (n/z) refers to the combination of authentication and authorization. The separation of authentication and authorization can be easily reconciled by two questions:

1. Who is the person?
2. What is the person allowed to do?

The first question refers to the authentication of the user. This asks who the calling instance is and whether it really is that instance.

Authorization deals with the second question: What is the right of the caller, and does he or she have the right to do the desired action?

If you look at the image above, you could say that authentication deals with who people are, so that when they enter through a door, they can identify themselves so they are no longer blank or anonymous. Authorization of people indicates whether the person in question is allowed to use the entrance at all.

There are many methods and mechanisms available for authentication and authorization. One of these is the access token.

Authorization Framework OAuth 2.0

RFC 6749 is the OAuth 2.0 authorization framework. With OAuth 2.0, a 3rd party application is granted limited access to selected user resources. This means that the application is authorized to access these specific contents.

The logical process flow of OAuth 2.0 is as follows:

• The client asks the resource owner for permission to access the resources on their behalf. The client represents the calling application. The resource owner allows the client to make the request.
• With the resource owner’s permission, the client receives an access token from the authorization server. The authorization server knows the rights, and the actual user, and can create the access token with the specific rights necessary for the request.
• With the help of the access token and the rights defined with it the client is authorized to request the actual resource and gets access to it.

Detailed information regarding OAuth 2.0 terms and procedures can be found in RFC 6749.

Authorization and Access Tokens – JWT

JSON Web Tokens (JWTs) are access tokens which are often used in the OAuth 2.0 authorization framework described above. A JWT is standardized according to RFC 7519. The API caller provides the access token either as a string in the header or as a request parameter. An API gateway, like the BIS API Gateway, checks the authorization part of the supplied JWT, and grants or refuses access.

The token represents an encrypted string consisting of three parts (red, purple and blue), separated by a dot. The basic structure of the authorization token JWT is always the same: Header.Payload.Signature. Each of the three parts consist of several key-value pairs that represent the actual content.

Let’s have a closer look at the three JWT parts:

• Header: The header should have at least the two key value pairs “alg” and “typ”. “alg” shows the encryption mechanism for signing the token, in this case HMAC SHA256. Other possibilities are RSA with SHA256 or ECDSA with SHA256. Although it is theoretically possible not to use encryption, it is strongly discouraged. An unencrypted token or a token without “alg” is usually strictly rejected. “typ” declares the media type, which is usually JWT.
• Payload: The payload contains the actual information to be transmitted, e. the rights that are checked for the actual authorization. The key value pairs of the payload are called claims. There are three types of claims. Registered claims are defined in the JSON Web Token Claim Register and have a defined purpose. Thus, “iss” stands for the issuer or “exp” for the expiration time of the token. Public claims are freely definable, but to avoid collisions they should also be specified in the JSON Web Token Claim Register. Commonly used public claims are email or name. Private claims contain information to be exchanged specifically for the interchange between the JWT producer and the JWT consumer.
• Signature: The signature is created using a secret key. The signature shows that the JWT has not been changed on the way. For this purpose, header and payload are signed with HMAC or RSA with a secret key.
  HMACSHA256(base64UrlEncode(header) + “.” + base64UrlEncode(payload), secret)

If the token is valid and contains the necessary claims, i.e. authorization of the API call was successful, the API call is forwarded.

Do you want to learn more about APIs? Read our blogs What is API integation, What is API management and the next blog in this series “API Gateway Security” or our survival guide APIs – from API Management to API Solution.