Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Require SSL or TLS Transport Assertion

Last update May 19, 2015

The Require SSL or TLS Transport /Require SSL or TLS Transport with Client Authentication assertion allows you to specify the SSL or TLS requirement to ensure transport-level confidentiality and integrity. You can specify whether an SSL/TLS connection is required, optional, or forbidden.

You can optionally require client certificate authentication and can control whether to check the validity period of the client certificate prior to gathering credentials.

When requiring client certificate authentication, the assertion will behave as a credential source that saves the client certificate from the SSL-TLS handshake for later authentication and authorization via the Authenticate User or Group assertion.

This assertion appears in two different assertion palettes:

  • When accessed from the Access Control palette, this assertion is labeled "Require SSL or TLS Transport with Client Authentication" and has the Require Client Certificate Authentication check box selected by default.
  • When access from the Transport Layer Security palette, this assertion is labeled "Require SSL or TLS Transport" and does not have the Require Client Certificate Authentication check box selected by default.

In either instance, you are free to toggle this check box according to your needs.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click [Require|Forbid|Optional] SSL or TLS Transport <with Client Authentication> in the policy window and select SSL or TLS Transport Properties or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:

    Setting Description
    Select the SSL or TLS requirements
    • Required: Select this option to disallow requests that do not arrive over an SSL-secured connection. This setting is the default setting for the assertion. When you select Required, the Peer Authentication options are enabled.
    • Optional: Select this option to configure the CA API Gateway to match the behavior of the incoming request. Requests are not required to arrive over an SSL-secured connection.
    • Forbidden: Select this option to disallow requests that arrive over an SSL-secured connection. This setting can be used to discourage users of a free service from consuming server SSL resources without paying for an upgraded account.
    Require Client Certificate Authentication

    Indicates whether the client certificate needs to be authenticated:

    • Select this check box to gather the client certificate to be authenticated later in the policy by an authentication assertion (for example, Authenticate User or Group Assertion).

    This indicates that a client certificate is required as part of the SSL-TLS handshake. The client certificate is used to authenticate the service requestor.

    This check box is available only when "Select the SSL or TLS requirements" is set to Required.

    Selecting the check box does not ensure that the client certificate will be authenticated. The Require SSL or TLS Transport with Client Authentication assertion only behaves as a credential source assertion. An authentication assertion must be present in the policy to authenticate the certificate.

    • Clear this check box to not gather the client certificate. This makes the "Require SSL or TLS Transport with Client Authentication Assertion" (accessed from the Access Control palette) identical to the "Require SSL or TLS Transport Assertion" (accessed from the Transport Layer Security palette).

    Check Client Certificate Validity Period

    Controls whether the validity period of the client certificate is checked during SSL-secured connections.

    • Select this check box to check the validity period of the client certificate and not gather credentials if the certificate is expired. This option will not populate the ${request.ssl.clientCertificate} variable. This setting is the default.
    • Clear this check box to not check the client certificate validity period and gather credentials from all client certificates. This options will allow the ${request.ssl.clientCertificate} variable to be populated with expired certificates.

    Notes: (1) Although expired certificate information may be gathered, such certificates cannot be used to authenticate users. For example, the Authenticate User or Group assertion will fail when an expired certificate is used. (2) Regardless of whether you check the validity period prior to gathering the credentials, validity will still be checked if an actual authentication is attempted (using the Internal Identity Provider, Federated Identity Provider, or LDAP Identity Provider).

  4. Click [OK] when done.
Was this helpful?

Please log in to post comments.