Securing Access to APIs
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
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
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.
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
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
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
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