Configuring PKI browser certificate authentication
browser certificate authentication enables users to use authentication based on installed browser certificates. The file ’truststore’ stores a root certificate used for PKI (X509) client authentication. The PKI client authentication is disabled by default and this certificate has no effect.
How PKI authentication works
- A user connects to ETA normally, using HTTP (port 8081 by default) or HTTPS (port 8443 by default). On the login screen, the user presses ‘Log in using Client Certificate’ button.
- The web browser connects to ETA using HTTPS protocol and a port specified by <x509LoginConfigurations> (8883 by default). Jetty will only accept this connection if the client certificate is presented by the browser, and this certificate is signed by a root certificate present in ‘truststore’.
- ETA uses session cookies to start an authenticated session and redirects back to the original port and protocol. If the client sees an SSL/TLS error after pressing the ‘Log in using Client Certificate’ button, then their browser does not have an appropriate certificate installed.
If the client sees ‘No permissions to use ETA’ error after pressing the ‘Log in using Client Certificate’ button, then the certificate was accepted but the client is neither ‘user’ nor ‘admin. Adjust the <x509LoginConfigurations> section to accept the client as user and/or admin. The user name used by ETA is derived from the first part of the certificate’s Subject field. If the certificate’s Subject is CN=John,O=mycompany,OU=com then the user name is ‘John’.
Setting up PKI authentication
To set up PKI authentication:
- Make sure your users can access https protocol on port 8883. ETA’s Jetty server listens on that port for authentication purposes and requires a trusted HTTPS client certificate to connect.
- Client certificates are trusted if they can be validated against a root certificate located in ‘truststore’ file. This root certificate is randomly generated at ETA install time. Its alias is ‘sintelix-users’ and password is ‘secret’. You can replace it with your own certificate.
- Go to the file \external-users\user_repositories.xml
Note: If you don’t know where your Sintelix database folder is click Status at the top right of the Sintelix toolbar then scroll down to the System Configuration section. The location of your Sintelix database is shown beside Main datastore location.
- In the xml file locate the <x509LoginConfigurations x509Port="8883"> section. Make the changes you require to the code. Use the code below as a guide.
- Generate user certificates if necessary. The batch file ‘create-client.cmd’ can be used for this purpose.
In practice, follow your company’s procedures. Users need to install their key in their web browser (or the operating system’s key store).
- adminPaths: if a certificate's Subject field ends with any of the values, the user has administrator access to Sintelix.
- userPaths: if a certificate's Subject field ends with any of the values, the user gets the user access of the given role (defaults to CONFIGURE, can be declared multiple times with different roles, evaluated in order of occurrence).
- allAdmins: overrides Subject paths and gives all authenticated users administrator access.
- allUsers: overrides Subject paths and gives all authenticated users the user access of the given role (defaults to CONFIGURE).