Securing Access to APIs

From iDENprotect Knowledge Base
Jump to: navigation, search

Introduction

The idenprotect Core Platform provides a number of APIs for integration with mobile clients and other systems. Access to these APIs can be secured in a number of ways. The same security mechanics are also applicable to the Admin console. This article discusses authenticating to these APIs. For more information on the APIs, see API Documentation with Swagger

The authority to use a given API is determined by the role allocated to a user once they have authenticated and they have been associated with a Site User, for more information, see Site Users


Basic Authentication

By default, the Admin Console and the APIs are secured using Basic Authentication. For a user accessing the admin console, this means entering a valid username and password on the admin console login page. For devices/services accessing the APIs, this means the API call must contain a Basic Authorization Header that matches a website username and password.

To enable basic authentication you need to edit the /etc/idenprotect/web-security.properties file and set

basic.auth=true

An example of this form of integration is the Site User account which is used by the idenprotect Authentication Portal and idenprotect User Portal which require an account with a username and password in order to access the APIs.

For more information on the idenprotect Authentication Portal, you can Start Here - idenprotect Authentication Portal or view all articles

For more information on the idenprotect User Portal, you can Start Here - idenprotect User Portal or view all articles

Mutual TLS

It is also possible to secure access to the admin console and APIs via Mutual TLS. It is important to note that this approach will apply to all APIs and access points, even those that do not require Authorization/Authentication using Basic Authentication. There are two steps to this approach.

Configuring Mutual TLS

To enable mutual TLS for the idenprotect Core Platform you need to edit webserver.properties with the required details of the Keystore and Truststore that the server should use to establish the mutual TLS session. It is beyond the scope of this article to fully explain the mechanics of Mutual TLS but basically a typical set of settings would be.

server.ssl.key-store = /etc/idenprotect/keystore.jks
server.ssl.key-store-password=cakeystorepass
server.ssl.key-storetype=JKS
server.ssl.keyalias = idenprotect
server.ssl.trust-store=/etc/idenprotect/truststore.jks
server.ssl.trust-store-password=cakeystorepass
server.ssl.trust-storetype=JKS
server.ssl.client-auth=need

These settings specify the keys to be used and the certificates to be trusted.

A key setting is

 server.ssl.client-auth=need

This means that the server will attempt to establish a mutual TLS connection and if it fails connection will be refused. However, if it is required to support other forms of authentication in parallel this should be changed to

 server.ssl.client-auth=want

This means that an attempt will be made to establish mutual TLS, but if that fails other methods can be attempted.

Mutual TLS for Authentication

Establishing mutual TLS will protect the APIs but will not, on its own, identify the user aiming to access the API or Admin Console. In order to do this, we need to map the CN of the certificate to a registered Website User account. To do this Certificate-based authentication must be enabled in web-security.properties

cert.auth=true

Then website user accounts must be created that match the CNs of the certs that are going to be used to gain access to the APIs/Admin Console


Header/Token (SSO) Authentication

To support integration with SSO solutions idenprotect Core Platform can be configured to authenticate the user by means of an HTTP Header. This solution assumes that access to the APIs/idenprotect Core Platform is only possible via a proxy that will enforce the required authentication.

To support this form of authentication the HTTP header name must be specified and the field within that header that is used to specify the user's identity. Then there must be a website users account that matches the identity presented in the header.

These parameters are set in the web-security.properties file

token.auth=true
token.auth.header=USERID_HEADER
token.auth.field=User

For these settings, idenprotect would look for a header call USERID_HEADER and look for User=username.

Using multiple forms of Authentication

It is possible to combine different forms of authentication at the same time however it is important to consider the security and usability implications of doing this. For example, if combining Header/Token-based with any other form it is important to ensure that a valid header can not be injected into the HTTP request by an unauthorized user.

Specific API Policies

Some APIs have complete public access like the public on boarding page. To disable or enable the functionality of these pages, amend the parameters set in the web-security.properties file

policy.publiconboarding.visible=true