(OpenShift) Security enablement example

Edit online

The following example shows how to enable secure communications between the OpenShift Container Platform where Z APM Connect DG is installed and MVS host, using RACF as the Security Server.

Before you begin

Make sure that the Secrets for Kafka, the Connection Manager, and Z APM Connect DG are created, and TLS is enabled with both the Connection Manager and Kafka routes in order for the OpenShift router to properly direct traffic. Without TLS, there is no SNI header indicating the desired host name. For more information, see Pre-deployment configuration.

Procedure

Transfer certificates from Z APM Connect DG OpenShift Clusters to z/OS components machine, create a key ring and certificate on z/OS components, and export personal certificate of the z/OS components.

Use the ASCII transfer mode to transfer the CA certificate used to sign the Z APM Connect DG certificates from the Z APM Connect DG OpenShift clusters to your MVS system into a Variable-Blocked (VB) dataset.

Important: You should be able to browse the certificate, and it should look the same as if you were to “cat” the CA certificate in the Z APM Connect DG OpenShift clusters.
Use the following command example to create a key ring and certificate on z/OS components, and export personal certificate of the z/OS components.

For this example below, you need to change all of these values to match your environment:

The VB dataset is 'ROOT.OSDG.CAROOT'.
The UserId under which the z/OS Connect EE server and Z APM Connect Base run is IBMUSER.
The UserId under which the Z APM Connect Base address space (AGMAPROC by default) runs is USER1.

Example

RACDCERT CERTAUTH ADD('ROOT.OSDG.CAROOT') HIGHTRUST WITHLABEL('IBM.OSDG.LABEL')

SETROPTS RACLIST(DIGTCERT) REFRESH 


RACDCERT CERTAUTH GENCERT SUBJECTSDN(O('ZOS APM Inc.') OU('ZOS APM Certificate Authority OSDG') C('US')) KEYUSAGE(CERTSIGN) WITHLABEL('ZOS_APM_Internal_CA_OSDG')

SETROPTS RACLIST(DIGTCERT) REFRESH

RACDCERT ID(IBMUSER) GENCERT SUBJECTSDN(CN('ZOS.APM.TEST.OSDG') O('ZOS APM Test OSDG') OU('ZOS APM Test Client OSDG') C('US')) WITHLABEL('Personal_Cert_OSDG') SIGNWITH(CERTAUTH LABEL('ZOS_APM_Internal_CA_OSDG')) 

SETROPTS RACLIST(DIGTCERT) REFRESH



RACDCERT ID(IBMUSER) ADDRING(OSDG-RING)

RACDCERT ID(IBMUSER) CONNECT(CERTAUTH LABEL('ZOS_APM_Internal_CA_OSDG') RING(OSDG-RING) USAGE(CERTAUTH))

RACDCERT ID(IBMUSER) CONNECT(ID(IBMUSER) LABEL('Personal_Cert_OSDG') RING(OSDG-RING) DEFAULT USAGE(PERSONAL))

RACDCERT ID(IBMUSER) CONNECT(CERTAUTH LABEL('IBM.OSDG.LABEL') RING(OSDG-RING) USAGE(CERTAUTH))

SETROPTS RACLIST(DIGTRING) REFRESH
SETROPTS RACLIST(DIGTCERT) REFRESH


PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(IBMUSER) ACCESS(READ)
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(IBMUSER) ACCESS(CONTROL)

SETROPTS RACLIST(FACILITY) REFRESH

RACDCERT CERTAUTH EXPORT(LABEL('ZOS_APM_Internal_CA_OSDG')) DSN('ROOT.OSDG.CACERT.EXPORT')

To give other users access to the key ring, (for instance, if the Z APM Connect Base address space is running under a UserId other than IBMUSER, in this example USER1), issue the following three commands, then also specify the LABEL value in the pagent configuration for that proc:

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(USER1) ACCESS(UPDATE)
 
RACDCERT ID(USER1) GENCERT SUBJECTSDN(CN('ZOS.APM.TEST.OSDG') O('ZOS APM Test OSDG') OU('ZOS APM Test Client OSDG') C('US')) WITHLABEL('Personal_Cert_USER1_OSDG') SIGNWITH(CERTAUTH LABEL('ZOS_APM_Internal_CA_OSDG')) 

RACDCERT ID(IBMUSER) CONNECT(ID(USER1) LABEL('Personal_Cert_USER1_OSDG') RING(OSDG-RING) USAGE(PERSONAL))

Update the policy agent (PAGENT) AT-TLS policy on the MVS system.

In the following command example:

The z/OS Connect EE server proc is ZCEESRVR.
The Z APM Connect Base proc is AGMAPROC.
The OpenShift machine name is ZAPMC-OSDG.ibm.com.
If you also have a CICS TG server, configure its connection to the Z APM Connect DG machine the same as you do for the z/OS Connect EE server.

Note: The Z APM Connect Base address space connects to the OpenShift’s ingress.apps process, and the z/OS Connect EE and CICS TG servers (if applicable) connect to the OpenShift’s kafka.apps process. These prefix values are configurable, so may be something other than ingress.apps and kafka.apps.

Example

TTLSRule                      CLIP_Probe-Client-OSDG-kafka
{
    RemotePortRange          443
    RemoteAddr               9.xx.xx.xx  # Address of OpenShift 
    Jobname                  ZCEESRVR	 # Jobname of zOS Connect EE server
    Direction                Outbound
    TTLSGroupActionRef       grp_Production
    TTLSEnvironmentActionRef act_CLIP_Probe-OSDG-kafka
    TTLSConnectionActionRef  act_IBMUSER-OSDG-kafka_Conn
}

TTLSConnectionAction act_IBMUSER-OSDG-kafka_Conn
{
   HandshakeRole    Client
   TTLSConnectionAdvancedParms
   {
       ClientHandshakeSNI Optional
       ClientHandshakeSNIMatch Optional
       ClientHandshakeSNIList kafka.apps.ZAPMC-OSDG.ibm.com
       SSLv3 Off
    }
}

TTLSEnvironmentAction         act_CLIP_Probe-OSDG-kafka
{
    HandshakeRole            Client
    Trace   255
    TTLSKeyRingParms
    {
        Keyring IBMUSER/OSDG-RING
     }
    TTLSEnvironmentAdvancedParms
    {
        SecondaryMap  On
           HandshakeTimeout  60
           TLSV1.2 On            
    }
}

TTLSRule                      CLIP_Probe-Client-OSDG-ingress
{
    RemotePortRange          443
    RemoteAddr               9.xx.xx.xx		# Address of OpenShift 
    Jobname                  AGMAPROC		# Jobname of Z APM Connect Base proc
    Direction                Outbound
    TTLSGroupActionRef       grp_Production
    TTLSEnvironmentActionRef act_CLIP_Probe-OSDG-ingress
    TTLSConnectionActionRef  act_IBMUSER-OSDG-ingress_Conn
}

TTLSConnectionAction act_IBMUSER-OSDG-ingress_Conn
{
   HandshakeRole    Client
   TTLSConnectionAdvancedParms
   {
       ClientHandshakeSNI Optional
       ClientHandshakeSNIMatch Optional
       ClientHandshakeSNIList ingress.apps.ZAPMC-OSDG.ibm.com
       SSLv3 Off
    }
}

TTLSEnvironmentAction         act_CLIP_Probe-OSDG-ingress
{
    HandshakeRole            Client
    Trace   255
    TTLSKeyRingParms
    {
        Keyring IBMUSER/OSDG-RING
     }
    TTLSEnvironmentAdvancedParms
    {
        SecondaryMap  On
           HandshakeTimeout  60
           TLSV1.2 On 
    }
}

Transfer over FTP using the ASCII mode the exported certificate, ROOT.OSDG.CACERT.EXPORT in this example, to the existing truststore on the Z APM Connect DG machine and place it in the same directory as the truststore file. The .cert file must be added to the truststore. In the following command example, host.cert is used as the exported certificate:
Example
```
keytool -import -keystore k8s.truststore.jks -deststoretype jks -alias customcert -file host.crt -storepass <pw> -keypass <pw> -noprompt
```
Recycle the Z APM Connect DG, if needed, to pick up the truststore addition.
1. Run the following command to uninstall the Z APM Connect DG:
  helm uninstall <name>
  For example.
```
helm uninstall zapm
```
2. Run the following command to reinstall and start Z APM Connect DG.
```
helm install --namespace <desired project> -f <values yaml> <name> <chart location>
```
  For example,
```
helm install --namespace ibm-zapm -f values.yaml zapm ./zapm-connect-6.1.0.7.tgz
```
Refresh or recycle the PAGENT address space. Recycle Z APM Connect Base address space (AGMAPROC) and if applicable, the CICS TG and z/OS Connect EE servers to pick up the new policy.