IBM Support

Setup functional userid for collective create and collective join on z/OS

How To


Summary

Setting up a collective requires that the userid that is running the commands:

- collective create
- collective join

be the same userid that the address space will run with since the controller/member keyring is accessed with the id that owns the keyring.

The RDATALIB class provides the ability for a functional userID to access the keyrings and certificates owned by the controller and member.
This allows the functional id to be used to login to USS and issue the collective create/join commands for the controller and member.

Objective

Setup a functional userid for running collective create and collective join on Liberty for z/OS using SAF keyrings.

Steps

The RACF commands assume that the controller and member are running under id CONTRLID. 
The functional userid that is used to run the scripts collective create and collective join is USER1

RACF commands

//Activate RDATALIB class
SETR CLASSACT(RDATALIB)
SETR RACLIST(RDATALIB) GENERIC(RDATALIB)

//Create the RDATALIB class for keyring CONTROL.KEYRING owned by user CONTRLID
RDEFINE RDATALIB CONTRLID.CONTROL.KEYRING.LST UACC(NONE)
RDEFINE RDATALIB CONTRLID.CONTROL.SERVID.KEYRING.LST UACC(NONE)
RDEFINE RDATALIB CONTRLID.MEMBER.KEYRING.LST UACC(NONE)
RDEFINE RDATALIB CONTRLID.MEMBER.SERVID.KEYRING.LST UACC(NONE)

//Allow USER1 to access the keyring/private key owned by CONTRLID

PERMIT CONTRLID.CONTROL.KEYRING.LST CLASS(RDATALIB) ID(USER1 ) ACC(CONTROL)
PERMIT CONTRLID.CONTROL.SERVID.KEYRING.LST CLASS(RDATALIB) ID(USER1 ) ACC(CONTROL)
PERMIT CONTRLID.MEMBER.KEYRING.LST CLASS(RDATALIB) ID(USER1 ) ACC(CONTROL)
PERMIT CONTRLID.MEMBER.SERVID.KEYRING.LST CLASS(RDATALIB) ID(USER1) ACC(CONTROL)

//Refresh the RDATLIB class
SETR RACLIST(RDATALIB) REFRESH

Prior to starting the server, login to USS with USER1 and confirm that it has access to the keyring and certificates owned by CONTRLID.

This can be accomplished by running the following keytool commands from Unix System Services.:

The keytool command output should show contents of the certificates on the keyrings for CONTROLID.

id uid=123(USER1) gid=100(WSCFG)

keytool -list -v -storetype JCERACFKS -keystore safkeyring://CONTROLID/CONTROL.KEYRING -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider

keytool -list -v -storetype JCERACFKS -keystore safkeyring://CONTROLID/CONTROL.SERVID.KEYRING -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider

keytool -list -v -storetype JCERACFKS -keystore safkeyring://CONTROLID/MEMBER.KEYRING -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider

keytool -list -v -storetype JCERACFKS -keystore safkeyring://CONTROLID/MEMBER.SERVID.KEYRING -J-Djava.protocol.handler.pkgs=com.ibm.crypto.provider

Now, you should be ready to issue the collective create and collective join commands with the user CONTROLID in the safkeyring name.

collective create myController
--safKeyring=safkeyring://CONTROLID/CONTROL.KEYRING
--keystorePassword=password
--safCertificateLabel=CollectiveSSH
--safKeystoreType=JCERACFKS
--safKeystoreProvider=IBMJCE
--serverIdentityKeystore=safkeyring://CONTROLID/CONTROL.KEYRING
--serverIdentityKeystoreAlias=ControllerHTTPS
--serverIdentityKeystorePassword=password
--collectiveTrustKeystore=safkeyring://CONTROLID/CONTROL.KEYRING
--collectiveTrustKeystorePassword=password
--createConfigFile=/WebSphere/Liberty/servers/myController/collective-create-include.xml

The full Java 8 command is provided:
  
collective create myController --safKeyring=safkeyring://CONTROLID/CONTROL.KEYRING --keystorePassword=password --safCertificateLabel=CollectiveSSH --safKeystoreType=JCERACFKS --safKeystoreProvider=IBMJCE --serverIdentityKeystore=safkeyring://CONTROLID/CONTROL.KEYRING --serverIdentityKeystoreAlias=ControllerHTTPS --serverIdentityKeystorePassword=password --collectiveTrustKeystore=safkeyring://CONTROLID/CONTROL.KEYRING --collectiveTrustKeystorePassword=password --createConfigFile=/WebSphere/Liberty/servers/myController/collective-create-include.xml
If the Liberty server is using Java 11 or Java 17 for z/OS, you'll need to replace:

–safKeystoreProvider=IBMJCE
with
–safKeystoreProvider=IBMZSecurity
 
The full Java 11 or Java 17  command is provided:
  
collective create myController --safKeyring=safkeyring://CONTROLID/CONTROL.KEYRING --keystorePassword=password --safCertificateLabel=CollectiveSSH --safKeystoreType=JCERACFKS --safKeystoreProvider=IBMZSecurity --serverIdentityKeystore=safkeyring://CONTROLID/CONTROL.KEYRING --serverIdentityKeystoreAlias=ControllerHTTPS --serverIdentityKeystorePassword=password --collectiveTrustKeystore=safkeyring://CONTROLID/CONTROL.KEYRING --collectiveTrustKeystorePassword=password --createConfigFile=/WebSphere/Liberty/servers/myController/collective-create-include.xml
collective join myMember
--host=controllerHostname
--port=9443
--user=adminUser
--password=adminPassword  
--keystorePassword=password
--serverIdentityKeystore="safkeyring://CONTROLID/MEMBER.KEYRING"
--serverIdentityKeystoreAlias="MemberHTTPS"
--collectiveTrustKeystore="safkeyring://CONTROLID/MEMBER.KEYRING"
--safKeystoreType=JCERACFKS
--safKeystoreProvider=IBMJCE  
--autoAcceptCertificates
--createConfigFile=/WebSphere/Liberty/servers/myMember/member-join-include.xml

The full Java 8 command is provided:
  
collective join myMember --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword  --keystorePassword=password --serverIdentityKeystore="safkeyring://CONTROLID/MEMBER.KEYRING" --serverIdentityKeystoreAlias="MemberHTTPS" --collectiveTrustKeystore="safkeyring://CONTROLID/MEMBER.KEYRING" --safKeystoreType=JCERACFKS --safKeystoreProvider=IBMJCE --autoAcceptCertificates --createConfigFile=/WebSphere/Liberty/servers/myMember/member-join-include.xml
If the Liberty server is using Java 11 or Java 17 for z/OS, you'll need to replace:

–safKeystoreProvider=IBMJCE
with
–safKeystoreProvider=IBMZSecurity
 
The full Java 11 or Java 17 command is provided:
  
collective join myMember --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword  --keystorePassword=password --serverIdentityKeystore="safkeyring://CONTROLID/MEMBER.KEYRING" --serverIdentityKeystoreAlias="MemberHTTPS" --collectiveTrustKeystore="safkeyring://CONTROLID/MEMBER.KEYRING" --safKeystoreType=JCERACFKS --safKeystoreProvider=IBMZSecurity --autoAcceptCertificates --createConfigFile=/WebSphere/Liberty/servers/myMember/member-join-include.xml

The collective-create-include.xml and member-join-include.xml will show the updated keyring names.

Additional Information

Reference Links
 

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SS7K4U","label":"WebSphere Application Server for z\/OS"},"ARM Category":[{"code":"a8m3p000000F7yQAAS","label":"IBM WebSphere Liberty-All Platforms-\u003ELiberty Security-\u003ELiberty - SSL"},{"code":"a8m0z0000001h7hAAA","label":"IBM WebSphere Liberty-All Platforms-\u003ELiberty z\/OS"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Versions"}]

Document Information

Modified date:
11 September 2024

UID

ibm17167117

Page Feedback