![[16.0.0.4 and later]](../ng_v16004plus.gif)
Configuring SAF certificates and keyrings for TLS on the z/OS operating system
Migrate an existing collective to use System Authorization Facility (SAF) for security-related functions, such as requests for authentication, authorization, or certificates.
Before you begin
DN=<hostname>, O=IBM, OU=Collective
Configure
the rdn attribute with the "OU=Collective" string from the distinguished name in the
server.xml file:
<collectiveCertificate rdn="OU=Collective"></collectiveCertificate>
About this task
The Organizational Unit (OU), OU('Collective'), component of the Subject Distinguished Name defines the string and marks the certificate to be recognized for the following procedure.
In the sample RACF® commands that follow, CONTROL is the RACF user ID of the controller and MEMBER is the RACF user ID of the member.
Procedure
- Create SAF certificates and a keyring for the controller.
- Create a collective controller CA (CERTAUTH) certificate.
RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('CONTROLLER ROOT') O('IBM') C('US'))SIZE(2048)WITHLABEL('CONTROLLER ROOT') TRUST NOTAFTER(DATE(2035/12/31))
- Create a server certificate for the collective controller that is signed by the collective
controller CA. Important: Replace the text of controller.host.name with the controller host name to avoid a host name mismatch with the browser URL.
RACDCERT ID(CONTROL) GENCERT SUBJECTSDN(CN('controller.host.name') O('IBM') OU('Collective')) WITHLABEL('CONTROLLER') SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2020/12/30))
- Create a keyring for the collective controller.
RACDCERT ID(CONTROL) ADDRING(CONTROL.KEYRING)
- Connect the collective controller CA to the controller keyring.
RACDCERT CONNECT(CERTAUTH LABEL('CONTROLLER ROOT') RING(CONTROL.KEYRING))ID(CONTROL)
- Connect the controller server certificate to the controller keyring.
RACDCERT CONNECT(ID(CONTROL) LABEL('CONTROLLER') RING(CONTROL.KEYRING)) ID(CONTROL)
- Create a collective controller CA (CERTAUTH) certificate.
- Create SAF certificates and a keyring for the member.
- Create a collective member CA (CERTAUTH) certificate.
RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('MEMBER ROOT') O('IBM') C('US'))SIZE(2048)WITHLABEL('MEMBER ROOT') TRUST NOTAFTER(DATE(2035/12/31))
- Connect the collective member CA to the controller keyring.
RACDCERT CONNECT(CERTAUTH LABEL('MEMBER ROOT') RING(CONTROL.KEYRING))ID(CONTROL)
- Create a server certificate for the collective member that is signed by the collective member
CA. Important: Replace the text of member.host.name with the member host name to avoid a host name mismatch with the browser URL.
RACDCERT ID(MEMBER) GENCERT SUBJECTSDN(CN('member.host.name') O('IBM') OU('Collective')) WITHLABEL('MEMBER') SIGNWITH(CERTAUTH LABEL('MEMBER ROOT')) SIZE(2048) NOTAFTER(DATE(2020/12/30))
- Create a keyring MEMBER.KEY for the collective member.
RACDCERT ID(MEMBER) ADDRING(MEMBER.KEY)
- Connect the collective member CA to the MEMBER.KEY keyring.
RACDCERT CONNECT(CERTAUTH LABEL('MEMBER ROOT') RING(MEMBER.KEY)) ID(MEMBER)
- Connect the member server cert to the MEMBER.KEY keyring.
RACDCERT CONNECT(ID(MEMBER) LABEL('MEMBER') RING(MEMBER.KEY)) ID(MEMBER)
- List the member keyring.
You should see two certificates in the keyring.
RACDCERT ID(MEMBER) LISTRING(MEMBER.KEY)
Digital ring information for user MEMBER: >MEMBER.KEY< Certificate Label Name Cert Owner USAGE DEFAULT -------------------------------- ------------ -------- ------- MEMBER ROOT CERTAUTH CERTAUTH NO MEMBER ID(MEMBER) PERSONAL NO
- Create a second keyring MEMBER.TRUST for the member.
RACDCERT ID(MEMBER) ADDRING(MEMBER.TRUST)
- Connect the collective controller CA to the MEMBER.TRUST keyring.
RACDCERT CONNECT(CERTAUTH LABEL('CONTROLLER ROOT') RING(MEMBER.TRUST))ID(MEMBER)
- List the MEMBER.TRUST keyring. You should see one certificate in the keyring.
RACDCERT ID(MEMBER) LISTRING(MEMBER.TRUST)
Digital ring information for user MEMBER: Ring: >MEMBER.TRUST< Certificate Label Name Cert Owner USAGE DEFAULT -------------------------------- ------------ -------- ------- CONTROLLER ROOT CERTAUTH CERTAUTH NO
- Create a collective member CA (CERTAUTH) certificate.
- List the controller keyring. You should see three certificates in the keyring.
RACDCERT ID(CONTROL)LISTRING(CONTROL.KEYRING)
Ring: >CONTROL.KEYRING< Certificate Label Name Cert Owner USAGE DEFAULT -------------------------------- ------------ -------- ------- MEMBER ROOT CERTAUTH CERTAUTH NO CONTROLLER ROOT CERTAUTH CERTAUTH NO CONTROLLER ID(CONTROL) PERSONAL NO
- Give the controller and member the authority to use the keyrings and certificates that they
own.
You can use FACILITY class profiles or RDATALIB profiles.
The following example uses the FACILITY class permissions for the CONTROL and MEMBER users:
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(CONTROL MEMBER) ACCESS(READ) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(CONTROL MEMBER) ACCESS(READ) SETR RACLIST(FACILITY) REFRESH
The following example uses the for RDATALIB class permissions for the CONTROL and MEMBER users:
PERMIT CONTROL.**.LST CLASS(RDATALIB) ID(CONTROL) ACCESS(READ) PERMIT MEMBER.**.LST CLASS(RDATALIB) ID(MEMBER) ACCESS(READ) SETR RACLIST(RDATALIB) REFRESH
- Add the z/OS® security feature to the controller and member serverl.xml
files.
- Stop the controller and member. Save a copy of each of the server.xml files for the controller and member to your backup files.
- Continue to edit the server.xml files. In the controller and member
server.xml files, add the following features to the
featureManager element:
<feature>ssl-1.0</feature> <feature>zosSecurity-1.0</feature>
- Create a server class profile so the controller and member can access SAF services. See
Enabling z/OS authorized services on Liberty for z/OS in the product documentation.
Then, in the controller and member server.xml files,
replace the following line:
with the following five lines:<quickStartSecurity userName="admin" userPassword="adminpw" />
<safAuthorization id="saf" racRouteLog="ASIS" /> <safCredentials profilePrefix="BBGZDFLT" unauthenticatedUser="WSGUEST"/> <safRegistry id="saf" realm="WASRealm" /> <safRoleMapper profilePattern="%profilePrefix%.%role%" /> <zosLogging enableLogToMVS="true"></zosLogging>
The EJBROLE profile that controls access to the Admin Center is BBGZDFLT.Administrator.
- In the controller and member server.xml files, specify the
collectiveCertificate string by adding the following line:
<collectiveCertificate rdn="OU=Collective"></collectiveCertificate>
- In the controller server.xml file, replace the keyfile names with SAF
keyring names.
- Locate the keystore element with the defaultKeyStore ID. Replace location="${server.config.dir}/resources/security/key.jks"/> with the
following lines:
location="safkeyring:///CONTROL.KEYRING" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the defaultTrustStore ID. Replace location="${server.config.dir}/resources/security/trust.jks"/> with
the following lines:
location="safkeyring:///CONTROL.KEYRING" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the serverIdentity ID. Replace
location="${server.config.dir}/resources/collective/serverIdentity.jks"/> with the
following lines:
location="safkeyring:///CONTROL.KEYRING" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the collectiveTrust ID. Replace
location="${server.config.dir}/resources/collective/collectiveTrust.jks"/> with the
following lines:
location="safkeyring:///CONTROL.KEYRING" type="JCERACFKS" fileBased="false" readOnly="true" />
Do not change the collectiveRootKeys keystore element.
- Locate the keystore element with the defaultKeyStore ID. Replace location="${server.config.dir}/resources/security/key.jks"/> with the
following lines:
- In the member server.xml file, replace the keyfile names with SAF keyring
names.
- Locate the keystore element with the defaultKeyStore ID. Replace location="${server.config.dir}/resources/security/key.jks"/> with the
following lines:
location="safkeyring:///MEMBER.KEY" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the defaultTrustStore ID. Replace location="${server.config.dir}/resources/security/trust.jks"/> with
the following lines:
location="safkeyring:///MEMBER.TRUST" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the serverIdentity ID. Replace
location="${server.config.dir}/resources/collective/serverIdentity.jks"/> with the
following lines:
location="safkeyring:///MEMBER.KEY" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the collectiveTrust ID. Replace
location="${server.config.dir}/resources/collective/collectiveTrust.jks"/> with the
following lines:
location="safkeyring:///MEMBER.TRUST" type="JCERACFKS" fileBased="false" readOnly="true" />
- Locate the keystore element with the defaultKeyStore ID. Replace location="${server.config.dir}/resources/security/key.jks"/> with the
following lines:
- Start the controller and member.
Subtopics
- Avoiding problems with SSH in a collective
Learn to avoid problems with SSH in a collective. Security problems usually relate to a user not having access to a resource because security is too restrictive. The SSH configuration option StrictModes protects public and private key files against the opposite problem, when security is too permissive. SSH provides secure communications between systems without password authentication, but SSH does not work if the permissions on certain directories and files are not strict enough.

File name: tagt_wlp_collective_zos_tls.html