Enabling certificate authentication

Edit online

About this task

Certificate authentication is not enabled by default. To enable certificate authentication, complete the following procedure.

Procedure

Edit the WebSEAL configuration file. In the [certificate] stanza, specify a value to the accept-client-certs stanza entry that instructs WebSEAL on how to handle client-side certificate authentication requests. The following table provides the valid values:
Table 1. Configuring certificate authentication
Configuration Description
accept-client-certs = optional

Clients can choose to use certificate-based authentication.

WebSEAL asks clients for an X.509 certificate. If the user supplies a certificate, certificate-based authentication is used.
accept-client-certs = required

Clients must use certificate-based authentication.

WebSEAL asks clients for an X.509 certificate. If the user does not present a certificate, WebSEAL does not allow a connection.

accept-client-certs = prompt_as_needed

Clients do not need to authenticate with a certificate at session start-up. Clients can later initiate certificate authentication.

This setting enables delayed certificate authentication mode.

For example, to prompt users for a client-side certificate only when the user encounters a resource that requires certificate authentication, enter: 

[certificate]
accept-client-certs = prompt_as_needed
This setting is used to configure an authentication strength policy (step-up) for certificate authentication.
Note: The Chrome browser does not support the renegotiation of an SSL session. It causes the prompt_as_needed configuration entry to function incorrectly in the Chrome browser. Extra configuration is needed to allow prompt_as_needed to work with all browsers.

The configuration parameter secondary-port must be set in the [certificate] stanza. This parameter modifies the behavior of accept-client-certs = prompt_as_needed to post the certificate login to a secondary interface configured to listen on this port.

A secondary interface must be configured for the secondary-port that is specified and accept-client-certs=required set for the secondary interface.

If a content security policy with a form-action directive is defined, it must be updated to allow forms to post to the secondary interface.

The following example configuration uses the secondary-port method: 

[server]
https = yes
https-port = 443
network-interface = 172.16.99.10

[ssl]
webseal-cert-keyfile-label = WebSEAL-Test-Only

[certificate]
accept-client-certs = prompt_as_needed
secondary-port = 444

[interfaces]
interface1 = network-interface=172.16.99.10;https-port=444;certificate-label=WebSEAL-Test-Only;accept-client-certs=required;always-neg-tls=yes;use-secondary-listener=yes

[acnt-mgt]
http-rsp-header = content-security-policy:TEXT{default-src 'self'; frame-ancestors 'self'; form-action 'self' https://172.16.99.10:444;}
  • An interface that is configured with accept-client-certs = prompt_as_needed is not used to prompt for certificates when a value is provided for secondary-port.
  • A template page macro %SECONDARY_BASE% is available.
    • When secondary-port is provided, it has the value: HTTPS://%HOSTNAME%:<secondary-port>.
    • When secondary-port is not provided, the macro is not populated.
  • The certlogin.html and stepuplogin.html template pages use the %SECONDARY_BASE% macro.
    • When Certificate Login is clicked, the form posts to %SECONDARY_BASE%/pkmslogin.form.
      Note: If a content security policy is configured, the form-action directive must be updated to include the value of %SECONDARY_BASE% to allow this post.
  • The [certificate] cert-prompt-max-tries is not used in this mode, and the login process requires less redirects to operate.
A change was made to the behavior of interfaces configured with accept-client-certs=required.
  • When a successful authentication that uses client certs occurs on a request for /pkmslogin.form, WebSEAL redirects the client to the previously cached request that was made before the login process started.
    Note: [server] cache-host-header must be set to yes.
    • This behavior is different from the previous behavior. The use of the required method of authentication did not disrupt the access to the page requested when the client received the prompt for a certificate.
  • A configuration parameter always-neg-tls was added to [server] and [interfaces].
    • If always-neg-tls is set to yes, each TLS connection on this interface processes only a single request. After the request is complete, the connection is closed and the TLS session ends. A TLS session renegotiation must then be completed for every connection. The always-neg-tls = yes is an expensive method of using TLS and must be used only where necessary. Typically, always-neg-tls = yes is used on the interface that uses secondary-port so that TLS connections on that interface always request a certificate from the client.