This article provides the security best practices for your REST APIs.
In the modern era, REST APIs become an integral part of the applications. By adopting the REST APIs, you can expose your services to web applications or mobile applications and all other digital platforms.
REST APIs must be built as a stateless service. I would like to explain the detailed REST API best practices in a separate article. This article primarily focuses only on Security best practices for REST APIs.
below are the key concepts that should be considered while designing the REST APIS
- Authentication / Authorization
- Input Validations and Sanitization
- Defining Content-Types
- Output encoding
- Rate limiters
- Responding with Appropriate Status codes to avoid the ambiguity
Authentication and Authorization
before delving into details let us first understand what is Authentication and Authorization.
Authentication: Authentication is the process of identifying the whether the credentials passed along with the request are valid or not. here credentials can be passed as user id and password or a token assigned for the user session.
Authorization: Authorization is the process of identifying whether the received request is allowed to access the requested endpoint or method.
In the request processing pipeline, Authentication comes first and Authorization comes next. i.e. Authorization occurs only after successful authentication of the request.
Below are the most used Authentication types when dealing with Remote APIs (REST APIs / Web Services).
- Basic Auth
- Bearer Token
- API Token
Basic Auth is the simplest way of dealing with Authentication when compared to other methodologies.
In the Basic Auth, the user has to send the user id and password in the format of userid:password encoded in base64 format. This method is preferred only over the https protocol only. This is highly discouraged to use over HTTP as your credentials are transferring in plain format.
Authorization: Basic base64(userid:password)
Bearer Token Authentication is also known as Token-based Authentication. When the user logs into an application using the credentials, the Authorization server generates a cryptographic token to uniquely identifies the user. the applications can use the token to identify the user after a successful login. i.e. The application is required to send this token when accessing protected resources.
Simillar to Basic Authentication, Bearer tokens are only recommended to send over HTTPS only.
Authorization Bearer <your token>
API Tokens are widely used in the web services / REST APIs security before evaluation of Client side frameworks. Still many organizations use the API Tokens as a security measure for the APIs. This is simplest way of implementing the security in REST APIs.
This is recommended when providing the communication between server to server requests. It is recommended to use the IP Address registration as well when using the API keys. i.e. API Token is uniquely identified along with the IP Address. This is not recommended to use as a methodology for end-user authentication and Authorization.
The API Key key can be sent as part of the query string or Authorization token or custom header or as part of the data.
OAuth2.0 is an authorization framework that allows user to grant a third-party website or application to access the users protected resources without revealing their credentials or identity. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
You probably see this option in the form of ‘Login using Google’, ‘Login using Facebook’, ‘Login using Github’ etc.
By default OAuth generates the access tokens in the format of JWT (Json web tokens). JWTs contain three parts: a header, a payload, and a signature.
Header: metadata about the token like cryptographic algorithms used to generate the token.
Payload: payload contains the Subject (usually identifier of the user), claims (also known as permissions or grants) , and other information like audiance and expiration time etc.
Signature: used to validate the token is trustworthy and has not been tampered with.
Below are the OAuth roles you must aware of when dealing OAuth2.0
Resource Owner: the entity that can grant access to a protected resource. Typically this is the end-user.
Resource Server: The server that is hosting the protected resources
Client: the app requesting access to a protected resource on behalf of the Resource Owner.
Authorization Server: the server that authenticates the Resource Owner, and issues Access Tokens after getting proper authorization.
OAuth2.0 provide various flows or grant types suitable for different types of api clients. Grant Types are out of scope for this article.
OIDC (Open ID Connect)
OIDC is a simple identity layer built on top of the OAuth2.0. OIDC defines a sign-in flow that enables a client application to authenticate a user, and to obtain information (or “claims”) about that user, such as the user name, email, and so on. User identity information is encoded in a secure JSON Web Token (JWT), called ID token.
In the Open ID Connect, Request flow will be happen as below.
- user will be navigated to the Authorization server from the client app
- The user enters the credentials to identify the user
- Upon successful authentication, Server sends back the user to client along with authorization code
- Client app requests the Authorization server for tokens (Access Token and Id Token) using the authorization code (we can use nonce here to incorporated additional security)
- Authorization server responds back with tokens.
Input validation should be applied on both syntactical and Semantic level.
Syntactical: should enforce correct syntax of structured fields (e.g. SSN, date, currency symbol).
Semantic: should enforce correctness of their values in the specific business context (e.g. start date is before end date, price is within expected range).
Basic Input validation guidelines
- Define an implicit input validation by using strong types like numbers, booleans, dates, times, or fixed data ranges in API parameters.
- Constrain string inputs with regular expressions.
- Use whitelisting and blacklisting techniques
- Define min and maximum lengths as a mandatory
- Enforce Input validations on client-side and server-side
- Reject unexpected/illegal content with a valid error messages
we must define the allowed content-types explicitly. It is always good practice to define the valid content types and share with the required shareholders. Upon receiving a unexpected or missing content type headers, API must respond with HTTP response status
406 Unacceptable or
415 Unsupported Media Type.
Content of given resources must be interpreted correctly by the browser, the server should always send the Content-Type header with the correct Content-Type, and preferably the Content-Type header should include a charset.
JSON encoders must be used when dealing with JSON Data
Rate limiters allows you to secure your APIs from the DDoS attacks. When exposing your API to publicly you must define the rate limiters. If you opt-in for any cloud provider tools, they explicitly provide the rate limiting capabilities to public faced resources. you must adjust the configurations accordingly to your needs.
Responding with Appropriate Status codes to avoid the ambiguity
Below are few common status codes used along with REST APIs
- 201 – Created
- 200 – OK
- 202 – Accepted and queued for processing
- 204 – No Content
- 304 – Not Modified
- 400 – Bad Request
- 401 – UnAuthorized
- 403 – Forbidden
- 404 – Not Found
- 405 – Method Not Allowed
- 406 – Not Acceptable (Used with Content Types)
- 415 – Unsupported Media Type
- 429 – Two Many requests
Thank you for reading the Article. Please share your thoughts in the comments box to improve it further.