Configure the AT-TLS profile for mutual authentication on the z/OS® system you are using as the web services server.
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.
-
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.
-
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
{
TTLSGskHttpCdpParms
{
HttpCdpEnable On
}
TTLSGskOcspParms
{
OcspAiaEnable On
}
GSK_V3_SESSION_TIMEOUT 5 g
}
Callout Notes:
- 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.
- Enable client authentication.
- 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.
- 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.
- 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.
- 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.
- 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.
-
Save the changes.