IBM Support

Set up Admin Center with an SSL Keyring and SAF Authorization on Liberty for z/OS

How To


Summary

This document describes the steps needed to set up Liberty with SSL communication using an SSL keyring,
and to set up roles for SAF authorization to access the Admin Center.

Objective

  1. Create a signer certificate and personal certificate and connect them to the Liberty Keyring
  2. Create administrator, reader, and allAuthenticated roles in SAF and permit users to the Admin Center roles
  3. Enable Admin Center with SSL Keyring and SAF authorization in server.xml
  4. Start the Angel and Liberty server and login to Admin Center
  5. Deploy an application
  6. Uninstall an application
     

Environment

Setting up AdminCenter with SAF roles requires the Angel to be set  up and started.  

If the Angel has not been set up, follow the steps in:
Administering Liberty on z/OS 
to set up the bbgzangl and bbgzsrv JCL procedure templates (PROCs)
for issuing the necessary RACF commands.
The following output should be seen in the messages.log if the Angel is started and configured correctly with authorized services.

CWWKB0122I: This server is connected to the default angel process.
CWWKB0103I: Authorized service group KERNEL is available.
CWWKB0103I: Authorized service group LOCALCOM is available.
CWWKB0103I: Authorized service group PRODMGR is available.
CWWKB0103I: Authorized service group SAFCRED is available.
CWWKB0103I: Authorized service group TXRRS is available.
CWWKB0103I: Authorized service group WOLA is available.
CWWKB0103I: Authorized service group ZOSAIO is available.
CWWKB0103I: Authorized service group ZOSDUMP is available.
CWWKB0103I: Authorized service group ZOSWLM is available.
CWWKB0103I: Authorized service group CLIENT.WOLA is available.

Steps

1.  Create a signer certificate and personal certificate and connect them to the Liberty Keyring
Connect the keyring LibertyKeyring to Liberty userid LIBSERV:

RACDCERT ADDRING(LibertyKeyring) ID(LIBSERV)
Generate Signer Certificate LibertySigner:

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('LibertySigner')) WITHLABEL('LibertySigner')  TRUST NOTAFTER(DATE(2048/12/31))
Create and sign Personal Certificate LibertyPersonal with Signer certificate LibertySigner:

RACDCERT ID(LIBSERV) GENCERT SUBJECTSDN(CN('host.name')) WITHLABEL('LibertyPersonal') SIGNWITH(CERTAUTH LABEL('LibertySigner')) TRUST NOTAFTER(DATE(2048/12/31))
Connect Signer certificate  LibertySigner and Personal Certificate LibertyPersonal to keyring LibertyKeyring:

RACDCERT ID(LIBSERV) CONNECT(CERTAUTH LABEL('LibertySigner') RING(LibertyKeyring))
RACDCERT ID(LIBSERV) CONNECT(LABEL('LibertyPersonal') RING(LibertyKeyring)) 
List Signer and Personal Certificate on Keyring:
RACDCERT LISTRING(LibertyKeyring) ID(LIBSERV)
Digital ring information for user LIBSERV:  
Ring:                                                                
     >LibertyKeyring<                                                     
Certificate Label Name             Cert Owner     USAGE      DEFAULT 
--------------------------------   ------------   --------   ------- 
LibertySigner                      CERTAUTH       CERTAUTH     NO    
LibertyPersonal                    ID(LIBSERV)    PERSONAL     NO 
2.  Create Administrator, Reader, and allAuthenticated roles in SAF and permit users to the Admin Center roles
RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.management.security.resource.Administrator UACC(NONE)
PERMIT BBGZDFLT.com.ibm.ws.management.security.resource.Administrator ID(ADMINID) ACCESS(READ) CLASS(EJBROLE)
RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.management.security.resource.Reader UACC(NONE)
PERMIT BBGZDFLT.com.ibm.ws.management.security.resource.Reader ID(READID) ACCESS(READ) CLASS(EJBROLE)
RDEFINE EJBROLE BBGZDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers  UACC(NONE)
PERMIT BBGZDFLT.com.ibm.ws.management.security.resource.allAuthenticatedUsers  ID(ADMINID) ACCESS(READ) CLASS(EJBROLE)


3. Enable Admin Center with SSL Keyring and SAF authorization in server.xml
<server description="defaultServer">
    <featureManager>
         <feature>transportSecurity-1.0</feature>
         <feature>zosSecurity-1.0</feature>
         <feature>adminCenter-1.0</feature>
    </featureManager>

    <httpEndpoint host="host.name" httpPort="8080" httpsPort="8443">
    </httpEndpoint>

    <sslDefault sslRef="DefaultSSLSettings"/>

    <ssl id="DefaultSSLSettings"
     securityLevel="HIGH"
     keyStoreRef="CellDefaultKeyStore"
     trustStoreRef="CellDefaultTrustStore"/>

    <keyStore id="CellDefaultKeyStore"
     location="safkeyring:///LibertyKeyring"
     filebased="false"
     updateTrigger="mbean"
     password="password"
     type="JCERACFKS"/>

    <keyStore id="CellDefaultTrustStore"
     location="safkeyring:///LibertyKeyring"
     filebased="false"
     updateTrigger="mbean"
     password="password"
     type="JCERACFKS"/>

   <safRegistry id="saf" realm="WASRealm"/>
   <safAuthorization />
   <safCredentials profilePrefix="BBGZDFLT" unauthenticatedUser="WSGUEST"/>
   <safRoleMapper profilePattern="%profilePrefix%.%resource%.%role%" />

   <applicationMonitor updateTrigger="mbean" dropinsEnabled="false"/>
   <config updateTrigger="mbean" />

   <remoteFileAccess>
      <writeDir>${server.config.dir}</writeDir>
   </remoteFileAccess>

   <logging traceSpecification="*=info" />
</server>
The example assumes the Angel PROC is BBGZANGL and Liberty server PROC is BBGZSRV.

The example server.xml sets the updateTrigger to mbean for keyStore, applicationMonitor, and config tags in order to reduce the amount of CPU from polling.
The dropins directory is disabled to reduce CPU.

Changes to the following:
- keystore and keyring
- server.xml and include xml file
- applications 
can be picked up dynamically with MVS console commands:
F BBGZSRV1,REFRESH,KEYSTORE
F BBGZSRV1,REFRESH,CONFIG
F BBGZSRV1,REFRESH,APPS          (if dropins directory is enabled)
The profilePattern in safRoleMapper can be changed to reduce the length of the SAF role name.
For example:
%profilePrefix%.%resource%.%role% = BBGZDFLT.com.ibm.ws.management.security.resource.Administrator
%profilePrefix%.%role% = BBGZDFLT.Administrator
A change to the profilePattern will apply to all roles in the server.

The remoteFileAccess tag is added with writeDir to allow the user logged in to the Administrator role (ADMINID) to edit tags using Admin Center and save them. 
4.  Start the Angel and Liberty server and login to Admin Center
S BBGZANGL
S BBGZSRV,parms='defaultServer'
Locate the Admin Center url in messages.log
CWWKT0016I: Web application available (default_host): http://host.name:8080/adminCenter
Login with the SAF user permitted to the Administrator role
image-20230317124347-1
Click on Server Config to see panels to administer the tags in server.xml.
image-20230317125153-3
5. Deploy an application
Create a file called application.xml in the same directory as server.xml.
Place the application file (SampleEAR.ear) in a directory of the file system that Liberty has access to.
In this example, the SampleEAR.ear was placed in the same directory as the server.xml.
Add the following lines to application.xml
<server description="SampleEAR Application file">
  <enterpriseApplication id="SampleEAR" location="${server.config.dir}/SampleEAR.ear" name="SampleEAR">
  </enterpriseApplication>
</server>
Add the following line to server.xml
<include location="${server.config.dir}/application.xml" />
Issue the dynamic MVS console command to refresh the server.xml and application.xml to pickup the changes:
F BBGZSRV1,REFRESH,CONFIG
The following message should appear on the MVS console.

CWWKB0005I: COMMAND RESPONSES COMPLETED SUCCESSFULLY FROM File Refresh Command Handler.                               CWWKB0002I: MODIFY COMMAND REFRESH,CONFIG COMPLETED SUCCESSFULLY.
The following messages should appear in messages.log to indicate the application was deployed.
CWWKG0028A: Processing included configuration resource: /WebSphere/Liberty/wlp/usr/servers/defaultServer/application.xml
CWWKZ0018I: Starting application SampleEAR.
CWWKZ0136I: The SampleEAR application is using the archive file at the /WebSphere/Liberty/wlp/usr/servers/defaultServer/SampleEAR.ear location.
SRVE0169I: Loading Web Module: SampleWAR.
SRVE0250I: Web Module SampleWAR has been bound to default_host.
CWWKT0016I: Web application available (default_host): http://host.name:8080/SampleWAR
The server.xml and application.xml can be viewed in the Admin Center.
image-20230320153527-1

Changes to existing tags or additional tags can be added to the application.xml
image-20230320154430-3
6. Uninstall an application
The SampleEAR.ear can be uninstalled by removing tag from server.xml:
<include location="${server.config.dir}/application.xml" />
or by selecting Remove followed by Save in Admin Center for the include tag.
image-20230320155625-1
Issue the dynamic MVS console command to refresh the server.xml:
F BBGZSRV1,REFRESH,CONFIG

Additional Information

Administering Liberty on z/OS
Enabling z/OS authorized services on Liberty for z/OS
Keystores
Mapping management roles for Liberty on z/OS
Required SAF permission when components use the REST Handler framework
Setting up Admin Center
Logging in to Admin Center

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS7K4U","label":"WebSphere Application Server for z\/OS"},"ARM Category":[{"code":"a8m50000000Cd8DAAS","label":"WebSphere Application Server traditional-All Platforms-\u003ESecurity-\u003ESSL-\u003ESSL - General"},{"code":"a8m50000000CdKsAAK","label":"WebSphere Application Server traditional-All Platforms-\u003ESecurity-\u003ESecurity zOS Only"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
21 March 2023

UID

ibm16962485

Page Feedback