Configure client (mutual) authentication

Configure the AT-TLS profile for mutual authentication on the z/OS® system you are using as the web services server.

Before you begin

You must have already configured an AT-TLS profile for HTTPS on the z/OS system, as described in Configure an AT-TLS profile. This procedure builds upon that existing profile by defining the rule for the mutual authentication port.

About this task

In AT-TLS, whether or not client authentication is done is controlled by the HandshakeRole parameter on either the TTLSEnvironmentAction or TTLSConnectionAction statements. When the HandshakeRole parameter is set to ServerWithClientAuth, a certificate request is sent to the client during the handshake. The client can send its certificate to the server, which can then validate the certificate.

The level of validation done by the server is controlled with the ClientAuthType parameter on the TTLSEnvironmentAdvancedParms statement.


  1. Edit the policy you created in Configure an AT-TLS profile to add a new rule for client authentication. The example rule uses the same keyring and cipher suites.
  2. Add the HandshakeRole and ClientAuthType parameters. Specific lines in the example are numbered to the right so that you can associate them with the notes that follow.
    Note: This is an example fragment. See SYS1.SAZFSAMP(AZFTTLSX) for sample AT-TLS rule definitions for IBM MFA.
    TTLSRule                          client_AZF            
      LocalAddr                       ALL                    
      RemoteAddr                      ALL                    
      LocalPortRange                  6777 a                    
      Direction                       Inbound                
      Priority                        255                    
      TTLSGroupActionRef              clientgA-AZF      
      TTLSEnvironmentActionRef        clienteA-AZF      
      TTLSConnectionActionRef         clientcA-AZF      
    TTLSGroupAction                   clientgA-AZF      
       TTLSEnabled                     On                      
       Trace                           2                       
     TTLSEnvironmentAction             clienteA-AZF       
       HandshakeRole                   ServerWithClientAuth b     
       EnvironmentUserInstance         0                       
       TTLSEnvironmentAdvancedParmsRef clienteAdv1-AZF
       TTLSGskAdvancedParmsRef        gskAdvMutWithCRL       
       TTLSKeyringParmsRef             keyR1~AZF       
       Trace                           2                       
     TTLSConnectionAction              clientcA-AZF       
       TTLSCipherParmsRef              cipher-AZF           
       TTLSConnectionAdvancedParmsRef  clientcAdv1-AZF       
       CtraceClearText                 Off                     
       Trace                           2                       
     TTLSConnectionAdvancedParms       clientcAdv1-AZF       
       HandshakeTimeout                30 c   
       ApplicationControlled           Off               
       SecondaryMap                    Off               
     TTLSEnvironmentAdvancedParms      clienteAdv1-AZF 
       ClientAuthType                  Required d 
       CertValidationMode              RFC5280 e           
       ApplicationControlled           Off               
       SSLv2                           Off               
       SSLv3                           Off               
       TLSv1                           Off                
       TLSv1.1                         On                
       TLSv1.2                         On                
    TTLSGskAdvancedParms    gskAdvMutWithCRL f 
         HttpCdpEnable                 On
         OcspAiaEnable                 On
       GSK_V3_SESSION_TIMEOUT          5 g  
    Callout Notes®:
    1. The example uses port 6777, but you can choose your own value. You need to specify this port when you run AZFEXEC to configure the web services mutual authentication port.
    2. Enable client authentication.
    3. Specifies the number of seconds to wait for the initial handshake to complete. Allow sufficient time for the user to validate a smart card PIN and provide the client certificate, if needed.
    4. The server ensures that the signer of the client’s certificate is trusted by checking the trusted root CA certificate that is in the server’s key ring.
    5. Specifies that certificates are validated by using the method described in RFC 5280. If you are using z/OS Version 2 Release 1, use the highest supported validation method.
    6. For z/OS Version 2 Release 2 and later, implement certificate revocation checking. See z/OS Communications Server: IP Configuration Guide and z/OS Communications Server: IP Configuration Reference for complete information.
    7. This value is the number of seconds that lapse until a session identifier expires. Set GSK_V3_SESSION_TIMEOUT to a low value, such as 5, to require the user to always re-enter their Common Access Card (CAC) and Personal Identification Verification (PIV) card PIN at logon. If the value is set too high, the TLS connection uses an abbreviated handshake that does not use the client's private key and therefore does not require the user to enter their PIN.
  3. Save the changes.