Configuration example: Securing a direct request with TLS client authentication

This task explains how to configure a CICS® web service provider that supports authentication by using a TLS client certificate.

Before you begin

This configuration task is based on the example security scenario Design example: Securing a direct request with TLS client authentication.

You must be familiar with web services and TLS.

You must complete these tasks:

You must have:

  • Authorization to create CICS resource definitions.
  • Authorization to install CICS resources.
  • Authorization to define RACF® commands.

About this task

In this example, you configure a CICS region to accept web service requests over TLS. The CICS region identifies itself to the client by using the region’s TLS server certificate. The client identifies itself to CICS by using its TLS client certificate that maps to a RACF user ID. This user ID is used to run the CICS web service attach transaction. The user ID is also used to run the web service when started through the client that sends the web service request.

This task assumes the following definitions:

  • keyRingA is the name of the RACF key ring that is associated with the CICS region.
  • clientCA is the RACF key ring label for the client certificate’s signing CA.
  • clientCACertificateDataSet is the data set containing the client certificate’s signing CA.
  • clientCertificateDataSet is the data set containing the client certificate (if a specific client certificate is mapped to a RACF user ID).
  • certificateLabel is the RACF label for the client certificate in RACF.
  • groupA is the RDO group name.
  • tcpipService is the name of a TCPIPSERVICE definition.
  • tcpipPort is a TCPIP port that is used by CICS to listen for the web service requests.
  • webServicePipe is the name of a PIPELINE definition.
  • webServiceProvider is the name of the webServiceProvider program.
  • soapProviderXmlFile is the zFS file that contains information about the processing nodes that act on a service request, and on the response.
  • shelfDir is the zFS directory for the web service binding file.
  • wsProviderDir is the web service binding directory on zFS for this pipeline.
  • matchID an identifier for the security request recording (SRR) report.
  • regionUseridA is the region user ID for the CICS region.
  • clientUserid is the user ID associated with the client certificate (from the requester) that runs the web attach transaction.
  • CN=myClient.host.com, O=IBM®, C=US is the client certificate subject's distinguished name value.

Procedure

  1. Import the client’s CA certificate into the RACF key ring.

    First, export the client’s CA certificate (public key) from their keystore and transfer it to a sequential data set on z/OS®. Now import the certificate into the CICS region’s key ring by using the following RACF commands:

    RACDCERT ID(regionUseridA) ADD('clientCACertificateDataSet') WITHLABEL('clientCA') TRUST
  2. Identify the client’s CA certificate as a trusted (CERTAUTH) certificate in the RACF keying: 
    RACDCERT ID(regionUseridA) CONNECT(RING(keyRingA) LABEL('clientCA') USAGE(CERTAUTH))
  3. The client’s certificate must be mapped to a RACF user ID. Client certificates can be associated with a RACF user ID in two ways. Each expected client certificate can be mapped to a RACF user ID individually, or groups of certificates that match a specified pattern can be mapped to a RACF user ID. This latter approach significantly reduces the administration burden of managing digital certificates and is the approach that is described here.

    Use the RACDCERT MAP command to define a certificate name filter. This command maps the certificate subject's distinguished name (DN) to a RACF user ID. Certificate name filtering supports generic filters allowing multiple certificates to be associated with a single RACF user ID.

    1. Activate the RACF DIGTNMAP class to allow certificate name filters to be created or changed.

      Enter the following RACF command:

      SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)
      Important: In this command, the syntax of the SDNFILTER is significant. Use periods to separate the components of the distinguished name and remove any spaces between DN components.

      For the full syntax of the RACDCERT MAP command, see RACDCERT MAP (Create mapping) in the z/OS® Security Server RACF Command Language Reference.

    2. Map the TLS client certificate to a RACF user ID.

      Enter the following command to use RACF certificate name filtering to map the client certificate to a RACF user ID.

      RACDCERT MAP ID(clientUserid) SDNFILTER('CN=myClient.host.com.O=IBM.C=US') WITHLABEL('certificateLabel')
    3. Refresh the DIGTNMAP RACF class for the changes to take effect.

      Enter the following RACF command:

      SETROPTS RACLIST(DIGTNMAP) REFRESH

    When this certificate is presented to the CICS region as part of a TLS handshake, the CICS region runs the subsequent transaction under the clientUserid, which is associated with the certificate in RACF.

  4. Define the TCPIPSERVICE.

    A TCPIPSERVICE is needed to listen for connections from the client. The connection uses TLS and requires the client to authenticate with a TLS certificate that is mapped to a user ID in RACF.

    DEFINE TCPIPSERVICE(tcpipService) GROUP(groupA)
       PORT(tcpipPort) 
       SSL(CLIENTAUTH) AUTHENTICATE(CERTIFICATE)
       URM(NONE) PROTOCOL(HTTP) TRANSACTION(CWXN)
  5. Define the PIPELINE.

    The PIPELINE provides information about the message handler programs that act on a service request and on the response.

    DEFINE PIPELINE(webServicePipe) GROUP(groupA)
       CONFIGFILE(soapProviderXmlFile) SHELF(shelfDir)
       WSDIR(wsProviderDir)

    An example CONFIGFILE can be found in <cics-install-dir>/samples/pipelines/basicsoap11provider.xml.

  6. Authorize clientUserid to the pipeline alias transaction CPIH and subsequent processing.

    The following commands associate the clientUserid with the taskUserGroup and grant the group READ access to the PIPEUSER member list that contains CPIA, CPIH, CPIL, and CPIQ:

    RDEFINE GCICSTRN PIPEUSER ADDMEM(CPIA,CPIH,CPIL,CPIQ) UACC(NONE)                                                    
PERMIT GCICSTRN PIPEUSER ID(taskUserGroup) ACCESS(READ)        
CONNECT clientUserid GROUP(taskUserGroup)
SETROPTS RACLIST(TCICSTRN) REFRESH

    If the PIPEUSER member list is already defined and associated with a user group, then you need only to add clientUserid to that user group.

  7. Install the definitions in group groupA. Installing the PIPELINE creates URIMAP and WEBSERVICE resources for the web service.

Results

Installing the resources in group groupA causes CICS to issue messages that report the installation of the PIPELINE and creation of the WEBSERVICE and a URIMAP resource:

DFHSO0107 02/07/2022 14:27:00 APPLID TCPIPSERVICE tcpipService has been opened on port tcpipPort at IP address ANY.                         
DFHPI0701 I 02/07/2022 14:27:00 APPLID regionUseridA PIPELINE webServicePipe has been created.                                                
DFHPI0204 I 02/07/2022 14:27:00 APPLID regionUseridA PIPELINE webServicePipe is now ENABLED and is ready for use.                                   
DFHPI0703 I 02/07/2022 14:27:00 APPLID regionUseridA PIPELINE webServicePipe is about to scan the WSDIR directory.                                 
DFHPI0901 I 02/07/2022 14:27:00 APPLID regionUseridA New WEBSERVICE webServiceProvider is being created during a scan against PIPELINE webServicePipe.   
DFHPI0910 I 02/07/2022 14:27:00 APPLID regionUseridA WEBSERVICE webServiceProvider within PIPELINE webServicePipe has been created.                      
DFHPI0915 I 02/07/2022 14:27:00 APPLID regionUseridA WEBSERVICE webServiceProvider is now INSERVICE and is ready for use.                          
DFHPI0903 I 02/07/2022 14:27:00 APPLID regionUseridA New URIMAP £055300 is being created during a scan against PIPELINE webServicePipe for         
           WEBSERVICE webServiceProvider.                         
DFHWB1560 02/07/2022 13:47:00 APPLID regionUseridA URIMAP £055300 has been created.
DFHPI0704 I 02/07/2022 14:27:00 APPLID regionUseridA PIPELINE webServicePipe Implicit scan has completed. Number of wsbind files found in the       
           WSDIR directory: 000001. Number of successful WEBSERVICE creates: 000001. Number of failed WEBSERVICE creates: 000000.

If you inquire on the created CICS resources:

  • The TCPIPSERVICE must have an OPENSTATUS of OPEN.
  • The PIPELINE must have an ENABLESTATUS of ENABLED.
  • The WEBSERVICE must have a STATE of INSERVICE.
  • You must have a generated URIMAP with an ENABLESTATUS of ENABLED.

To validate the security environment is functioning correctly when you run this example, you can use the CICS security request recording (SRR) utility. The SRR logs all authorization calls and the matching response codes.

You can use the CICS security request recording (SRR) feature from within CICS Explorer® to validate this example. With the Regions view in focus, you select the Add Security Request Recording pop-up menu option. On that window, select the Web tab and set the TCPIP Service field to tcpipService. For more information, see Checking that a CICS security configuration example is working by using the SRR.

The web service client can now start the CICS web service provider.