Enabling certificate authentication

Edit online

About this task

Certificate authentication is disabled by default. To enable certificate authentication:

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

Client can optionally 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

Client 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

The user is not required to authenticate with a certificate at session start-up. The user 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 when implementing an authentication strength policy (step-up) for certificate authentication.
Note: The Chrome browser does not support the renegotiation of an SSL session which causes the prompt_as_needed configuration entry to not function correctly. Additional configuration is required to allow prompt_as_needed to work with all browsers.

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

A secondary interface must be configured for the secondary-port specified and accept-client-certs=required set for 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
  • An interface that is configured with "prompt_as_needed" and has a non-zero secondary-port is not used to prompt for certificates.
  • A macro is provided, %SECONDARY_BASE%. When secondary-port" is non-zero it has the value: HTTPS://%HOSTNAME%:<secondary-port>.
  • When secondary-port is zero, or not set, is has an empty (zero length) value.
  • The certlogin.html and stepuplogin.html pages use the %SECONDARY_BASE% macro.
    • When the Certificate Login button is pressed the underlying action is to POST to %SECONDARY_BASE%/pkmslogin.form.
  • [certificate] cert-prompt-max-tries is not used in this mode and the login requires significantly less redirects to operate.
A small modification was made to the behavior of interfaces configured with "accept-client-certs=required"
  • When a successful authentication using client certs occurs on a request accessing /pkmslogin.form, WebSEAL redirects back to a request cached due to being interrupted by the login process.
    Note: [server] cache-host-header must be set to yes
    • This is different to previous behavior as using “required” method of authentication did not disrupt the access to the page requested when prompting the user for a certificate.
  • A configuration parameter, always-neg-tls, was added to [server] and [interfaces].
    • If always-neg-tls is set to yes. then any TLS connections on this interface only processes one request. Once the request is complete the connection is closed, and the TLS session is destroyed. This forces a full TLS session renegotiation every connection. This is an expensive method of using TLS so this option should only be enabled if absolutely necessary. Typically, it could be enabled on the interface the secondary-port is referring to so the TLS on that interface always requests a certificate from the client (browser).