Configure Client Certificate Authentication and Authorization

Using Client Certificate Authentication and Authorization is one of the options that can be configured for a worker.

When a worker is configured with the Client Certificate Authorizer, requests to the worker should be sent using an HTTPS port (typically TCP port 443 or 8443). The TLS layer will then be responsible for performing the authentication of the client and only let through clients with a certificate that chains up to a Certificate Authority (CA) that is trusted in the application server trust store. Further on, the Client Certificate Authorizer will determine if the client should be authorized to send the request by checking if the provided certificate matches any of the authorization rules in the worker configuration.

Configuring Client Certificate Authorizer

To configure the Client Certificate Authorizer, do the following:

1. On the Admin Web Workers Page, click on the worker to configure.
2. Click the Configuration tab.
3. Click Edit for the AUTHTYPE property (or click Add and add it if it does not already exist).
4. Specify the value CLIENTCERT and click Submit.

From now on, requests to the worker will be refused unless the client authenticated with client TLS authentication and the client certificate matches one of the client certificate authorization rules.

Adding Client Certificate Authorization Rules

You can choose to add Client Certificate Authorization rules either by loading fields from your current administrator certificate, importing fields from a local certificate file, or manually specify the fields to match with.

1. On the Admin Web Worker Page, click the Authorization tab to open the Worker Authorization Page.
2. Click Add.
3. Fill in fields and values from the certificate to match on, using one of the supported alternatives:
   1. Alternative A: Using the values from your administrator certificate:
      1. Click Load Current.
      2. Choose which field to match the Subject with by clicking Select in front of it. Only fields available in the certificate can be selected. Example: "RDN: CN, commonName: Admin One".
      3. Click Submit and notice that the fields are now specified.
   2. Alternative B: Importing the fields from a local certificate file:
      1. Click From File.
      2. Click the Browse (file selector) button to select a local certificate file in PEM format or alternatively paste the PEM encoded certificate in the text area.
      3. Click Load.
      4. Choose which field to match the Subject with by clicking Select in front of it. Only fields available in the certificate can be selected. Example: "RDN: CN, commonName: Client One".
      5. Click Submit and notice that the fields are now specified.
   3. Alternative C: Manually specify what to match with and which value:
      1. For the Subject, use the drop-down list to choose which field to match with and then specify the expected value in the input field after it. For example, type "RDN: CN, commonName" and example value "Client One".
      2. For the Issuer, specify the full issuer DN in textual representation. The input value will be normalized the way it is presented in for instance EJBCA. This means that the order will be CN, OU, O, C, and so on and there will be no spaces after the commas between the RDN:s. Example: "CN=DSS Root CA 10,OU=Testing,O=SignServer,C=SE".
4. Optionally specify a free-text description of the rule.
5. Click Submit to save the rule.

From now on, requests from clients with a certificate matching this rule will be allowed. Add additional rules to authorize more clients.

Sending Requests with Client Certificate Authentication

Using Web Browser

• When sending the request, make sure to use an URL that uses TLS client authentication. Normally, that would be a URL starting with https://. In some setups, the port 8443 would have to be used. Examples:

  • https://example.com/signserver/demo
  • https://example.com:8443/signserver/demo
• Make sure the client certificate and private key are installed in the web browser (or available to the web browser in case it is on a token).
• Sometimes restarting the web browser (or clearing the cache/session) is needed in order to switch to using another certificate.

Using SignClient signdocument Command

• Make sure to provide the -truststore option to provide a keystore with the trusted certificates (for authenticating the server), and a keystore with your client certificate and private key.
• Provide the -port option with, for example, either port 443 or 8443.

For more information, see signdocument.