This is a template that can be used when writing technical specifications for development requirements. Keep in mind that this is a flexible template which can be adapted to the type of requirement. Here, an example has been used to illustrate how to fill in the template.

1.             Requirement

1.1           Goals/Scope

The scope of this RFC is to increase the security of the IMIS API when used by any third party applications and thus not allowing access to API calls to not authorized users.

1.2           Background

The IMIS Web Services can be called by any Mobile or Web Client without prior need of a registered user. This is due to the fact that any API call is creating a new session on the server side and, even that a Validate_credential function exists, it doesn’t allows remembering the user whose credentials are validated. This represents a security threat for the all IMIS information system.

1.3           Assumptions

Assumes that the IMIS API is used by a registered user

1.4           User stories

2.             Technical Specification

This technical specification will deal with the implementation of the authentication and the authorisation of the user to execute API calls. In order to assure this, the LOGIN API call and the calls to all other functions must be updated.

2.1           Authentication protocol

2.1.1       JWT Authentication

The IMIS API should use a JSON Web Tokens authentication.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA. [https://jwt.io ]

JWTs consist of three parts separated by dots (.), which are:

Therefore, a JWT typically looks like the following: xxxxx.yyyyy.zzzzz

Header

The header typically consists of two parts: the type of the token, which is JWT, and the hashing algorithm such as HMAC SHA256 or RSA.

In our case we will use:

Then, this JSON is Base64Url encoded to form the first part of the JWT.

Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional metadata. There are three types of claims: reserved, public, and private claims.

Reserved claims: These are a set of predefined claims, which are not mandatory but recommended, thought to provide a set of useful, interoperable claims. Some of them are: iss (issuer), exp (expiration time), sub (subject), aud (audience), among others.

Notice that the claim names are only three characters long as JWT is meant to be compact.

Public claims: These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.

Private claims: These are the custom claims created to share information between parties that agree on using them.

An example of payload we will use:

Optional, we could add an expiration time to increase the security. We will add claims in the token for each role of the user within the IMIS system. These roles will be then used to define the authorisation access to the API calls.

The payload is then Base64Url encoded to form the second part of the JWT.

Signature

To create the signature part you have to take the encoded header, the encoded payload, a private_key, the algorithm specified in the header, and sign that.

As we choose to use HMAC SHA256 algorithm, the signature will be created in the following way.

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed in the way.

2.1.2       How to use the JWT

In authentication, when the user successfully logs in using his credentials, a JSON Web Token will be returned and must be saved locally (typically in local storage, but cookies can be also used), instead of the traditional approach of creating a session in the server and returning a cookie.

Whenever the user wants to access a protected route, it should send the JWT, typically in the Authorization header using the Bearer schema. Therefore the content of the header should look like the following.

This is a stateless authentication mechanism as the user state is never saved in the server memory. The server’s protected routes will check for a valid JWT in the Authorization header, and if there is, the user will be allowed.

2.1.3       Impact on the general architecture

There are some components that need to be updated in the general architecture (Figure 1) in order to implement the JWT authenticated API.

Figure 1. Composite structure for JWT authenticated API architecture

These components are:

·         The database for storing new private keys

·         The Web Application for creating and registering new private keys

·         The API for creating and validating the JWT

·         The different mobile or web clients to use the JWT

2.1.4       Impact on the database structure

In order to sign the token, we will generate a private_key for each registered User which will be saved on the server.

There are several possibilities:

·         The private_key can be generated on the user registration and used for all logins. This possibility allows multiple logins (multiple devices at a time).

·         The private_key can be regenerated on each login, but can be used only for the last login (only one device at a time).

·         The private_key can be generated for each login (multiple devices at a time) and all private_keys will be saved on a separated table in the database. This solution is more secure but it requests more time when calling the API on the validation part.

For IMIS authentication, we will use the first solution. This will impact:

·         the tblUsers table in the database by adding a column for the private_key

·         the User.aspx.vb page by generating the private_key and assigning it to the user

When generating the private_key value, a minimum length of 20 characters must be considered in order to satisfy encryption requirements.

Every time the user change the password, a new private key must be generated in order to invalidate any already provided JWT.

2.2           Authorisation protocol

Net Core supports for several types of authorisation mechanisms (ex. Simple, Role-based, Claims-based, and Policy-based).

For implementing the authorisation protocol, we will use the role-based authorization, as described in section 2.1.1. This is based on the Role claims from the JWT token stored on token creation.

For each API controller and/or action we will need to add the Authorize attribute with the Roles parameter (list of roles that has access to the controller/action).

2.3           JWT Payload information

In the authentication protocol we decided to use a JWT signed by user defined private key. For any API requests, the JWT have to be validated. This is only possible by knowing which user has requested this token, and to access his private key. We will use the “name” claim type to register the username in the token payload.

In the authorisation protocol, we chose to implement a Role-based authorisation protocol. Net core IdentityModel library provide out of the box authorisation mechanism based on the “role” claim type coming from the JWT. For each user’s role we will add a “role” claim with a string representing the role, the same strings used in the Authorisation protocol described in section 2.2.

For the expiration date we will provide a 5 (five) days limit. This value will be provided in the configuration file (appsettings.json) as an integer of number of days the token is valid (NOW + number of days).

Two additional claim types will be registered in the payload: the issuer and the audience. These values will be taken from the configuration file.

The JWT payload will have the following structure:

Example of a JWT payload for the Admin user:

2.4           Get API token

2.4.1       API /login diagram

Figure 2. Sequence diagram for API login call

2.4.2       API /login description

2.5           API call

As presented in 2.1.2, every call that needs authentication has to add to the request header the Authorization tag with the token. This way, on the server side, the token is validated and the access to the resource is granted.

The next diagram presents an example of API call with JWT authentication.

2.5.1       API call diagram

2.5.2       API call description

Example of the specification for an API method: