Securing APIs with WSO2 API Manager

The API-driven business model plays a major role in today’s business world as most organizations have reaped the benefits of exposing their services via APIs. In most digitally transformed businesses, revenue is generated from exposing APIs to a wider consumer community.

Security is one of the main concerns for any IT application, and it has the same importance for API management as well. Service providers must make sure that only authorized parties have access to respective resources/services. Securing APIs is an important task because unauthorized access to resources will negatively impact an organization’s revenue.

Securing APIs with WSO2 API Manager

It is clear that API security is a crucial factor in API-driven digital business models. Hence, an effective API management solution should facilitate to implement the key attributes of API security, which are authentication, authorization, confidentiality, integrity, availability, and non-repudiation. In this section, we will identify how WSO2 API Manager is capable of securing exposed APIs.

Transport level security

Transport level security should be ensured to provide privacy and data integrity between two communicating computer applications. This makes sure that all messages are transmitted (between the applications) in a secure and reliable manner.

When it comes to API management, we need to maintain proper transport level security. If not, a third-party attacker might misuse the information sent over the network during API consumption. Therefore, it is highly recommended that API management solutions include support for transport level security.

WSO2 API Manager has support for transport level security out of the box. It can be easily configured to enable TLS and disable SSL support. This is important because of a bug (Poodle Attack) in the SSL protocol that could expose critical data encrypted between clients and servers. Compared to SSL, TLS utilizes improved cryptographic algorithms to ensure communication security. This improves the conversation speed and security for the handshake.

In addition, WSO2 API Manager can be configured to disable weak ciphers. We can do this for the Tomcat transport or PassThrough transport. Disabling weak ciphers is one of the important factors in an API management production system. Weak ciphers can make the system vulnerable to attacks, e.g. the Logjam attack (Man-in-the-Middle attack) on Diffie-Hellman Key Exchange.

Moreover, it is possible to change the server name in HTTP response headers if needed. WSO2 API Manager sends "WSO2 Carbon Server" as the server value in HTTP headers when sending HTTP responses. If this needs to be modified with a custom value, that can also be done with a simple configuration change.

WSO2’s official documentation contains a complete set of security guidelines for production deployments. It also contains more information about WSO2 product-level security, OS-level security, and network-level security as further reading.

OAuth

OAuth 2 (Open Authorization) is an open standard for access delegation. It is used for token-based authentication and authorization. This standard is used by many technology providers, such as Google, Facebook, and Twitter. By using OAuth 2, it is possible to grant access to a secured resource (with an access token) for a specific period of time. Once the lifetime of that access token expires, the consumer has to refresh the token to obtain a new token.

Figure 1: OAuth 2.0 protocol overview

WSO2 API Manager is a production-ready API management solution. After subscribing to an API, consumers need to generate an access token to invoke the API. This is an OAuth2 access token. The validity period of this access token can be specified when generating it.

By default, WSO2 API Manager’s key manager component is responsible for handling token-related operations. The key manager properly decouples operations to create OAuth applications and validate access tokens. As a result, we can plug in a third-party authorization server for key validations if needed (e.g. WSO2 Identity Server).

Figure 2: Processing flow in API Gateway

When a request comes to the API Gateway (i.e. when consuming an API), it will be validated with the key manager; access token validation occurs at this stage. The request is allowed to reach the backend endpoint only if the token is a valid token. This ensures that services exposed via APIs can only be consumed by authorized parties.

WSO2 API Manager also has the capability to encrypt any sensitive OAuth 2 keys that are created. This can be achieved via a configuration change in the product.

Grant types

There are several grants for a client application to acquire an access token (which represents a user’s permission for the client to access their data). This makes the OAuth 2.0 specification a flexible authorization framework.

WSO2 API Manager supports the following common authorization grant types. If required, it is possible to define additional types.

Authorization Code Grant

This grant type is optimized for confidential clients. With this, it is possible to authenticate the client and transmit the access token directly to the client without passing it through the resource owner's user agent and potentially expose it to others (including the resource owner). In this grant type, the client directs the resource owner to an authorization server. The authorization server sits between the client and the resource owner. Upon request, it will issue an authorization code, authenticate the resource owner, and obtain authorization. This is a redirection-based flow as the client must be capable of interacting with the resource owner's user agent and receive incoming requests (via redirection) from the authorization server.

In this mechanism, the client has ensured that his access token is not visible to any third party other than the authorization server (including the resource owner). The resource owner can “trust” the client without any issues if he/she is authenticated by the authorization server.

NTLM Grant

NT LAN Manager (NTLM) is an authentication protocol that is proprietary to Microsoft. This provides authentication, integrity, and confidentiality to users, and it is used in various Microsoft network protocol implementations. NTLM is the successor to the authentication protocol in Microsoft LAN Manager (LANMAN). It uses a challenge-response mechanism for authentication. Users can prove their identity without sending a password to the server.

NTLM provides authentication, confidentiality, and integrity while enabling support for single sign-on (SSO).

Password Grant

If the resource owner has a trust relationship with the client (e.g. the device operating system or a highly privileged application), the password credentials grant type can be used. However, the authorization server must ensure special care when enabling a password credentials grant type. The server should only allow it when other flows are not viable.

The client will ask the user for the resource owner's username and password. Then, the client sends these credentials to the authorization server, along with the client’s own credentials. In this scenario, the client is not redirected to the authorization server. In this grant type, it sends a single call to the authorization server. This allows an application that is incapable of integrating with an interactive login. The authorization server will be given the flexibility in terms of the types of clients that can interact with it.

SAML Extension Grant

Security Assertion Markup Language (SAML) 2.0 is an XML-based protocol. In some applications, it is required to consume OAuth protected resources through APIs (environments with SAML2-based SSO infrastructures). In these scenarios, the applications prefer to use the existing trust relationship (with the identity provider). WSO2 API Manager can facilitate the aforementioned requirement by exchanging the SAML 2.0 token to an OAuth token with the authorization server.

SAML uses security tokens containing assertions to pass information about an end user between a SAML authority (typically an identity provider) and a SAML consumer (usually a service provider). Many enterprise-level applications use SAML protocol to engage a third-party identity provider to grant access to resources that are only authenticated against the enterprise application.

Client Credentials Grant

The client credentials grant type is easy to to understand. This is not associated with a resource owner. In this mechanism, to obtain a token, an app sends the client ID and client secret associated with it. If these parameters (i.e. client ID and client secret) are valid, an access token will be returned back. In this flow, the end user does not get involved. In most cases, the client credentials grant type is used when the app owner and resource owner are the same.

If there is a need to establish machine-to-machine authentication or for a client making requests to an API that does not require the user’s permission, the client credentials grant type can be used. However, this grant type should be allowed for use only by trusted clients.

Kerberos OAuth2 Grant

This is one of the security protocols that supports many operating systems and open-source distributions, such as Ubuntu, Windows, RedHat, Open Solaris, etc. In addition, most popular web browsers have support for Kerberos. With WSO2 API Manager, it is possible for organizations to exchange a Kerberos ticket for an OAuth 2.0 token. With this, organizations can reuse the existing Kerberos infrastructure and adopt OAuth 2.0.

Refresh Token Grant

An access token is issued with a limited lifetime. Therefore, when the lifetime is over, the token will expire. Afterward, users/client apps need a new token to consume the secured services. This can be addressed using the refresh token grant type. The refresh token is a credential that is issued by the authorization server to the client along with the access token. In some cases, sending a refresh token might be optional. If a refresh token is issued, then it can be used to obtain a new, live token when the old access token expires. Users should take special care of the refresh token, as it can be used to obtain an access token without user interaction.

Accordingly, with WSO2 API Manager, API publishers need not worry about the security of their APIs, because the product has inbuilt support for API security mainly based on OAuth 2.0. The above-mentioned grant types are used to authorize access to protected resources in different ways.

Scopes

In API-driven, digitally transformed businesses, revenue is generated by exposing APIs. In this situation, it’s important to make sure that only allowed parties have access to the respective resources. Since unauthorized access to resources will affect revenue and eventually have a negative impact on the organization, securing APIs becomes an important task. This might seem difficult, but a security solution that can facilitate fine-grained access control to every resource of an API is a must-have. This can be easily achieved with WSO2 API Manager since it has inbuilt support for OAuth 2.0 scopes.

When it comes to distributed web authorization, OAuth 2.0 is a very useful standard. Here, mainly authorization is implemented using an access token. Consumers need an access token to consume the respective service. OAuth scopes will facilitate to specify what type of access is required per resource, and what can be done with the access token is defined based on the scopes associated with it. That is how a scope enables fine-grained access control for each resource of the API based on specific consumer roles. This ensures that only the allowed resources can be accessed by the consumer.

Depending on the need, it is possible to obtain a token with multiple scopes so that a particular user can access all (only allowed) resources using a single token. If that is not suitable for the requirement, we can have better control over resource usage by having tokens per scope.

Figure 3: Different ways of generating tokens for scopes

The above figure shows a visual representation of the different ways of generating access tokens for multiple scopes.

More information about scopes in WSO2 API Manager is included in the official documentation. In addition to that, please refer to this WSO2 library article about scopes.

XACML

XACML (eXtensible Access Control Markup Language) is a declarative access control policy language based on XML. It is capable of providing a standardized way of validating authorization requests.

The main use of XACML is to enable a role-based access control mechanism. In any API-driven digital business model, it is important to maintain security, so that all authorized users are able to access its APIs without any interruption. At the same time, the system should make sure that any unauthorized users are kept out. To facilitate this requirement, we can use parameters such as the user role to grant access to secured services or APIs. XACML is suitable for these situations.

In WSO2 API Manager, we have support for an OAuth 2-based authorization mechanism. As discussed in the "Scopes" and "OAuth" subsections, this feature can be extended. XACML provides a standardized mechanism to validate authorization requests using policies. These XACML policies are managed and stored through a policy administration point. Policies written to one XACML engine can be ported to another engine from a different vendor without much effort because XACML policies are standardized.

XACML enables an attribute- and policy-based approach to authorization. Also, fine-grained and dynamic authorization can be performed using XACML. More information about XACML is included in the official documentation as well.

JWT

Sometimes, there will be a need to send end-user attributes to the backend for authentication purposes. For such scenarios, we can use JWT (JSON web token) to facilitate that with WSO2 API Manager. According to the RFC specification, JWT is a JSON object that can be used as a safe way to represent a set of information between two parties. The token is composed of a header, a payload, and a signature. JWT is useful for authentication and information exchange.

Figure 4: JWT flow (image source)

We can easily understand the flow, as presented in Figure 4. First, the user tries to log in with his credentials. Then, after the authentication process, JWT is issued to the user. This JWT is sent to the backend when making API calls, so that the backend can recognize the user based on the information sent along with the JWT.

With WSO2 API Manager, it is possible to customize the JWT generation, change the JWT encoding to Base64URL encoding if needed. Moreover, we can set an expiry time to the JWT as well.

Conclusion

This article focused on WSO2 API Manager’s security aspects when it comes to securing APIs. Since WSO2 API Manager is a complete, enterprise-ready solution for managing APIs across the complete API lifecycle, organizations can use it to deploy and expose APIs while ensuring a secure environment for API consumption.

Moreover, this article depicted relevant information with respect to transport level security, OAuth 2, grant types, scopes, XACML and JWT, with related concepts.