Introduction

Client Certificate authentication (also known as mutual authentication or 'mTLS') is the only supported way of authenticating machine-generated requests for data held in EnergySys. With this type of authentication both the client and the server use X.509 certificates to ensure they are communicating with the correct entity. Using certificates allows both the client and the server to authenticate the identity of the other party.


Configuration

Client Certificate authentication can be configured for an EnergySys instance as follows:

  1. customer obtains an X.509 certificate with Client Authentication capabilities (see below for more details)
  2. customer sends to EnergySys a request to create a user associated with the X.509 certificate
  3. customer provides to EnergySys all public certificates of the certification chain used by the X.509 certificate
  4. EnergySys adds the provided certificates to the trust store and creates a user associated with the X.509 certificate. The user id will match the subject (i.e. the distinguished name) of the SSL certificate.
  5. customer assigns roles to the user associated with the X.509 certificate to authorise access to the required objects


Certificates

X.509 Certificates used for Client Certificate Authentication must be signed by a Certificate Authority. They can be obtained from an external Certificate Authority (e.g., Digicert) or from an internal one (e.g., a Certificate Authority trusted internally). 


Certificates must support the 'Client Authentication (1.3.6.1.5.5.7.3.2)' extended key usage attribute. The attribute need to be added when creating the certificate request. In addition, the certificates should not contain wildcard characters (e.g., *) and have a subject (i.e. distinguished name) shorter than 100 characters.


We recommend that the certificate is named after the server running the software that initiating the connection to EnergySys. The server hostname (e.g., "server123.domain.com") should be used as the "common name" attribute of the certificate. The other parts of the certificate subject (e.g., organisational unit, organisation, etc.) can be chosen accordingly to the customer needs.