CICS - Group home

Using the Liberty angel to access authorized z/OS services

  

This article by Eric Phan, explains how Liberty servers running in CICS can use the angel process to provide access to z/OS authorized services such as SAF. It also discusses a set of security usability enhancements that have been delivered with Liberty since fix pack 16.0.0.4. These include more robust startups through changes in the way that authorized services are accessed, improvements in angel process connectivity and better diagnostics when security processing fails.

A list of CICS APARs that provide support for each Liberty fix pack is available in the IBM CICS Knowledge Center.

1. Using authorized services

A Liberty server needs to be granted access to z/OS authorized services, such as SAF authorized user registry services and SAF authorization services (SAFCRED), the IFAUSAGE services (PRODMGR) to collect usage data in SMF record types 30 and 89, and the asynchronous I/O services (ZOSAIO) to handle asynchronous TCP/IP sockets. To access z/OS authorized services, the Liberty server must connect to an angel process at startup. After connecting, the Liberty server retrieves a list of z/OS authorized services it is permitted to call. For a list of z/OS authorized services and how to enable them, see Enabling z/OS authorized services on Liberty for z/OS.

Which security functions require access to SAF authorization services?

In a CICS Liberty JVM server, access to the angel SAFCRED services is mandatory whenever the cicsts:security feature is used with a SAF registry. This applies to both HTTP requests into Liberty or CICS tasks that link to Java components using the link to liberty feature. When running in a CICS region, the use of SAFCRED services is the only way for a Liberty server to authenticate requests with the SAF registry or to authorize a Subject to Java EE roles via a SAF registry.

What happens if the angel is not available?

Liberty also offers the ability to failover to unauthorized UNIX System Services to authenticate requests when the angel process is unavailable. However, this is not supported when running a Liberty server in CICS. As of Liberty fix pack 18.0.0.3, this failover should be prevented by setting the attribute enableFailover to false in the safRegistry element in server.xml, as follows:

<safRegistry enableFailover="false"/>

 

With this option set, if the Liberty server starts up and is not able to register with the angel process, then instead of failing over to unauthorized UNIX System Services to authenticate requests, the server may fail requests and issue the following FFDC message to the Liberty messages.log.

FFDC1015I: An FFDC Incident has been created: "com.ibm.ws.security.registry.RegistryException: The server is not permitted to use the authorized SAF registry and is configured to not allow the use unauthorized SAF registry services through the enableFailover attribute under the safRegistry configuration element. This operation is not permitted. "

 

Note: The CICS Liberty JVM server autoconfiguration process now sets enableFailover to false by default.
 

The following table summarizes the scenarios where the angel SAF authorized user registry services are required.

Request Type Authentication mechanism Security registry Angel required
HTTP Request Basic Auth SAF Yes
HTTP Request SSL client certificate mapping to a SAF user ID SAF Yes
HTTP Request Basic Auth LDAP with mapDistributedIdentities=true Yes
HTTP Request URIMAP userid attribute Any No
Link to Liberty CICS task user ID SAF Yes *
Authorization mechanism
Any EJBROLE profiles SAF Yes
Any Java EE roles in server.xml Any No


* Angel registration only required for Link to Liberty if cicsts:security-1.0 feature is installed.

2. Named angels

A Liberty server can only connect to one angel process at server startup. However, multiple Liberty servers can share the same angel process, independently of the level of code that the servers are running.

Liberty fix pack 16.0.0.4 introduced the notion of a named angel that allows multiple uniquely named angel processes to run on a single z/OS system, in addition to the default unnamed angel process. A named angel has the same function as the default angel process, but it can be used for a selected group of Liberty servers. This provides the ability to isolate servers from one another, so that they can run different service levels or be managed independently. For instance, the z/OSMF server requires the use of an angel process, by default it registers itself with the named angel IZUANG1 as illustrated in Figure 1.

An angel process can only service Liberty servers running on the same LPAR. Each LPAR can have multiple named angel processes but only one default angel process.

Named-Angel.png
Fig 1: Angel registration

 

To start a named angel, the NAME parameter is specified on the START command or in the PROC, for example:

//BBGZANGL PROC NAME='MYANGEL'
//   SET ROOT='/usr/lpp/cicsts/cicsts55/wlp'
//STEP1   EXEC PGM=BPXBATA2,REGION=0M,TIME=NOLIMIT,
//   PARM='PGM &ROOT./lib/native/zos/s390x/bbgzangl NAME=&NAME’
//STDOUT    DD SYSOUT=*
//STDERR    DD SYSOUT=*

 

Connecting to a named angel

In order to connect a Liberty server to a named angel, the name of the angel process is provided as a JVM system property. This can be defined either via the bootstrap.properties file, as follows:

com.ibm.ws.zos.core.angelName=MYANGEL

 

or in the CICS JVM profile, as follows:

-Dcom.ibm.ws.zos.core.angelName=MYANGEL

 

Angel process required

A Liberty server that requires the services of an angel process must register with the specified angel process during server startup. However, by default, if the angel process is unavailable the Liberty server will continue to initialize and will then be unable to use any authorized services including password authentication and EJB role authorization. This situation can sometimes occur during automated startup procedures if the angel process is not available early enough in the IPL sequence.

To address this, a property was added in Liberty fix pack 16.0.0.4 to cause a Liberty server to fail during startup if the connection to the angel process cannot be established. This property can be defined either in the bootstrap.properties file, as follows:

com.ibm.ws.zos.core.angelRequired=true

 

or in the CICS JVM profile, as follows:

-Dcom.ibm.ws.zos.core.angelRequired=true

 

In addition, when using CICS TS V5.4 with APAR PI87691 if the com.ibm.ws.zos.core.angelRequired property is set to true, the JVM server first checks if the angel process is available before starting the Liberty server. If the JVM server is installed from the GRPLIST during region startup and the angel process is not available, the JVM server will wait in an ENABLING state and make 5 attempts to check if the angel process becomes available. If the 5 attempts fail, the JVM server startup will be suspended and an MVS console message will be issued. The following message is printed in the JVM server standard error output:

2019/11/07 11:45:34.389174 UTC E [LE-Thread-0] [DFHSJSC] *Exc* : ipt_control_loop() - The Liberty angel MYANGEL is unavailable.

 

The following message is printed to the MVS operator console, as a write to operator with reply message:

12.45.34 STC05278 @06 DFHSJ1404D CICSMOBT JVMSERVER RESTWLP The Liberty angel is unavailable. Reply 'Y' to continue waiting or 'N' to cancel

 

If answered with a ‘Y’ response, the JVM server repeats its attempt to check if the angel process is started. If answered with a ‘N’ response the JVM server is disabled.

Angel version interoperability

All Liberty servers that are running on a z/OS image can share a single angel process, regardless of the level of Liberty code that the servers are using. The recommendation is that the angel process is upgraded before the Liberty servers that use its services, as it provides back level support for older versions of Liberty servers and this ensures support is available for all authorized services potentially required by the Liberty servers.

The angel has its own versioning schema described in the IBM WebSphere Knowledge Center. The current version is v11 which was first provided in Liberty fix pack 19.0.0.3.

Note: The support for multiple CICS Liberty JVM servers in the same CICS region to register with an angel, required new angel function which was provided in Liberty angel v8 and in CICS APAR PI98174.

Cold starting an angel process

Cold starting an angel process will reinitialize the MVS shared storage used by the angel processes and will affect all angel processes on the system. It is designed to be used only under the guidance of IBM service to resolve connectivity issues between Liberty servers and the angel process. You should ensure all angel processes on the system are stopped before issuing a cold start. Subsequent angel processes should not need a cold start, just the first one for the system.

Querying angel registration

Once a Liberty server is registered with its configured angel process, it can sometimes be hard to ascertain exactly which servers are registered with which angel process. To address this issue, you can issue the following MVS modify command against an angel process to display the details of all the Liberty servers that are registered with it.

/F BBGZANGL.MYANGEL,DISPLAY,SERVERS,PID

 

16.36.02 STC13422  CWWKB0067I ANGEL DISPLAY OF ACTIVE SERVERS
16.36.02 STC13422  CWWKB0080I ACTIVE SERVER ASID 5d  JOBNAME CICPY00A PID 33621816
16.36.02 STC13422  CWWKB0080I ACTIVE SERVER ASID 1b8 JOBNAME CICPY00C PID 50397610
16.36.02 STC13422  CWWKB0080I ACTIVE SERVER ASID 61  JOBNAME CICPY00C PID 50398147
16.36.02 STC13422  CWWKB0080I ACTIVE SERVER ASID 68  JOBNAME WUI56    PID 50397356

 

The PID option on the DISPLAY command is new in Liberty fix pack 18.0.0.4 and shows the process ID of the listed JVM servers. This is particularly useful if multiple Liberty JVM servers in a single CICS region connect to the same angel process. The JVM server process ID can be cross checked using the CEMT INQUIRE JVMSERVER() PID command and is also reported in CICS message DFHSJ1405I.

In summary, these new features help users to create more robust CICS startup automation and they also simplify problem determination if there has been a problem starting or registering with the angel process.

3. Security auditing

When using the SAFCRED services, most error messages related to unauthorized access to SAF resources are only printed to the Liberty server messages.log in zFS. Whereas on z/OS it is usually expected to find messages about security violations, such as RACF ICH408I, on the MVS operator console. This section highlights that as of Liberty fix pack 18.0.0.3 it is now possible to enable security messages from SAF to be written to the MVS console. This helps to speed up the problem determination of security issues, and to improve audit control.

z/OS authorized services

A Liberty server can be granted access to some z/OS authorized services. In order to know which z/OS authorized services the Liberty server is permitted to call, the permissions are printed in the messages.log file. However, a security violation message can also be generated on the MVS operator console if the angel process is started with the parameter SAFLOG=Y, for example:

//BBGZANGL PROC NAME='MYANGEL'
//  SET ROOT='/usr/lpp/cicsts/cicsts55/wlp'
//STEP1   EXEC PGM=BPXBATA2,REGION=0M,TIME=NOLIMIT,
//  PARM='PGM &ROOT./lib/native/zos/s390x/bbgzangl NAME=&NAME SAFLOG=Y’
//STDOUT    DD SYSOUT=*
//STDERR    DD SYSOUT=*

 

Profile prefix

A Liberty server is configured to use a profile prefix that specifies the SAF APPL-ID. The profile prefix is specified using the profilePrefix attribute of the safCredentials element, for example:

<safCredentials profilePrefix="BBGZDFLT"/>

 

By default, the value of profilePrefix is BBGZDFLT.

The profile prefix is similar in function to the CICS SECPRFX system initialization parameter as it is used to control access to server specific security resources. If desired it can be set to the same value as the CICS APPLID.

SERVER and APPL profiles

When using the angel process to provide user authentication via the SAF registry, the CICS region must be granted access to two profiles that reference the profile prefix. The region user ID must be granted READ access to the SERVER class profile BBG.SECPFX.<profilePrefix>, and each authenticated user must be granted READ access to the APPL class profile named by the profile prefix. Further details of the security profiles required are available in the IBM CICS Knowledge Center. If a user is not authorized to the APPL profile then message CWWKS2907E is printed to Liberty messages.log, when authentication fails.

CWWKS2907E: SAF Service IRRSIA00_CREATE did not succeed because user EMPLOY1 has insufficient authority to access APPL-ID BBGZDFLT. SAF return code 0x00000008. RACF return code 0x00000008. RACF reason code 0x00000020.

 

In order to print the corresponding SAF audit message to the MVS console, the following configuration needs to be added to server.xml:

<safCredentials suppressAuthFailureMessages="false"/>

 

When using RACF this results in the following message being written to the MVS console:

ICH408I USER(EMPLOY1 ) GROUP(DB2USR  ) NAME(EMPLOY1 USERID)
  BBGZDFLT CL(APPL    )
  INSUFFICIENT ACCESS AUTHORITY
  ACCESS INTENT(READ   )  ACCESS ALLOWED(NONE   )

EJBROLE profile

When using SAF authorization in a Liberty server, the roles defined in the Java application are used to control access to application resources based on the access permissions in the mapped EJBROLE profile. This behavior is enabled by setting the safAuthorization element in server.xml as follows:

<safAuthorization id="saf"/>

 

If an authenticated user is not authorized to a role then message CWWKS9104A is printed by Liberty to the messages.log, as shown.

CWWKS9104A: Authorization failed for user EMPLOY1:defaultRealm while invoking CatalogManagerService on /api/items. The user is not granted access to any of the required roles: [cicsAllAuthenticated].

 

In order to print the related SAF audit message to the MVS console, the following configuration needs to be added to the safAuthorization element.

<safAuthorization id="saf" racRouteLog="ASIS"/>

 

This will result in the following message to the MVS console if using RACF.

ICH408I USER(EMPLOY1 ) GROUP(DB2USR  ) NAME(EMPLOY1 USERID)
  BBGZDFLT.CatalogManagerService.cicsAllAuthenticated
  CL(EJBROLE )
  INSUFFICIENT ACCESS AUTHORITY
  ACCESS INTENT(READ   )  ACCESS ALLOWED(NONE   )