Configure PKI Browser Certificate Authentication

Intro

PKI Public Key Infrastructure 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

  1. A user connects to Sintelix 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.
  2. The web browser connects to Sintelix 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’.
  3. Sintelix 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.
Troubleshooting

If the client sees ‘No permissions to use Sintelix’ 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.

User name

The user name used by Sintelix 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:

  1. Make sure your users can access https protocol on port 8883. Sintelix’s Jetty server listens on that port for authentication purposes and requires a trusted HTTPS client certificate to connect.
  2. Client certificates are trusted if they can be validated against a root certificate located in ‘truststore’ file. This root certificate is randomly generated at Sintelix install time. Its alias is ‘sintelix-users’ and password is ‘secret’. You can replace it with your own certificate.
  3. Go to the file: <Sintelix Database Directory>\external-users\user_repositories.xml

    To find the location of your Sintelix database folder, select the Status tab and find the System Configuration section. the location is displayed in the Main datastore location field.

  4. 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.
  5. Generate user certificates if necessary. The batch file ‘create-client.cmd’ can be used for this purpose.

    6. In practice, follow your company’s procedures. Users need to install their key in their web browser (or the operating system’s key store).

Example

Copy 
<item>
    <adminPaths>
        <item>OU=admins,O=mycompany,OU=com</item>
    </adminPaths>
    <userPaths role="CONFIGURE">
        <item>OU=admins,O=mycompany,OU=com</item>
    </userPaths>
    <userPaths role="ANALYST">
        <item>OU=users,O=mycompany,OU=com</item>
    </userPaths>
    <allAdmins>false</allAdmins>
    <allUsers role="CONFIGURE">false</allUsers>
</item>    
  • 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).