Security enhancement for IBM Unified Management Server

Introduction

We recently shipped an important and highly requested security enhancement for IBM Unified Management Server (UMS) which is the platform for IBM Db2 Administration Foundation (ADF), IBM Db2 DevOps Experience (DOE), and IMS Admin Foundation (IAF). 
Prior to this enhancement UMS used a hybrid security model where a user’s roles are defined through permissions on SAF resources, but the user also needs to be listed in a dataset (the so-called USERLIST). If either was missing, the user was not permitted access to UMS. Additionally, team membership for Db2 DevOps Experience was also kept in a dataset (the so-called TEAMLIST). 
A larger number of customers strongly preferred to manage everything security-related in the ESM.

With UMS V1.2 PTF2 (APAR PH54452, PTF UI91302) we delivered an enhancement for SAF-based management of users and teams. This is an alternative to the original architecture described above. In this new security mode all team, user, and role information are stored in the ESM, and eliminates the need to maintain the datasets for user lists and team lists. 

Deprecation

This feature is currently optional and must explicitly be turned on. So, when you apply PTF2 the security behavior is unchanged. 
Due to most customers telling us they would turn on this feature, we have also deprecated the old security mode with UMS V1.2 PTF3 (APAR PH55598, UI93092):

• Current plans are to remove support for the old security mode in the first maintenance shipped after August 2024
• The default for new installations will default to the new mode (from UMS V1.2 PTF4)
• Existing UMS installations will continue using the old security mode until the new mode is explicitly turned on.

So, you have one year to migrate away from the old security mode to the new one. 
In the rest of the blog, we assume you are using RACF as the ESM, but ACF2 and TSS are also supported. 

Migration 

As mentioned, the new security mode will remain unchanged for existing installations and is still the default for new installs until after UMS V1.2 PTF4. 
The profiles that protect access to UMS are unchanged:

• Regular users: READ on IZP.ADMIN* on class IZP
• Super-administrators: READ on IZP.SUPER* in class IZP

From a high-level point of view, you need to take the following steps to migrate:
Step 1: Define new SAF profiles (some new APIs are protected by new profiles)
Step 2: Migrate team information from the dataset to the ESM (Db2 DevOps only)
Step 3: turn on the feature in your UMS YAML configuration file
Step 4: restart Zowe and UMS

Step 1: Define new SAF profiles.

For display purposes UMS keeps a cache of user and team information. The reason is that querying the ESM for the information can be resource intensive. The APIs that refresh the cache are protected by profiles IZP.FUNCTION.GET.ROLES, IZP.FUNCTION.GET.USERS, and IZP.FUNCTION.GET.TEAMS in class IZP. 
These new resources need to be defined in the ESM, and READ authority permitted to the user(s) that are allowed to refresh this information. 

When you run the IZPGENER job a customized sample job JCLLIB(IZPD7R) will be generated with the appropriate RACF commands to create the profiles.
Use the sample job JCLLIB(IZPD7VR) to validate the existence of the profiles. 

Step 2: Migrate team information from the dataset to the ESM (Db2 DevOps Experience only)

In the old security mode, the team membership was stored in the TEAMLIST dataset. 
Example:

{                                        
  "teamName": "N9CO5F76",                
  "members": [                           
    {                                    
      "id": "HOLADM1",                   
      "isTeamAdmin": true                
    },                                   
    {                                    
      "id": "HOLADM2",                   
      "isTeamAdmin": true                
    },                                   
    {                                    
      "id": "HOLUSR1",                   
      "isTeamAdmin": false               
    },                                   
    {                                    
      "id": "HOLUSR2",                   
      "isTeamAdmin": false               
    },                                   
    {                                    
      "id": "HOLUSR3",                   
      "isTeamAdmin": false               
    },                                   
    {                                    
      "id": "HOLUSR4",                   
      "isTeamAdmin": false               
    },                                   
  ]                                      
}                                        

 
The teamName is N9CO5F76 with users HOLADM1 and HOLADM2 being team administrators, and HOLUSR1 – HOLUSR4 are regular team members. 
Define a new SAF profile for the team:
RDEFINE IZP IZP.TEAM.N9CO5F76 UACC(NONE)
and permit access to the users:
PERMIT IZP.TEAM.N9CO5F76 CLASS(IZP) -
ID(HOLADM1,HOLADM2) ACCESS(UPDATE)

PERMIT IZP.TEAM.N9CO5F76 CLASS(IZP) -
ID(HOLUSR1,HOLUSR2,HOLUSR3,HOLUSR4) ACCESS(READ)
Finally, remember to refresh the class if it is raclisted: SETROPTS RACLIST(IZP) REFRESH
Repeat for all the teams that have been created. 
Instead of permitting users access individually, you can of course use permit access through RACF groups. 

Step 3: Turn on the new security mode.

The new security mode is by default turned off for existing installs and turned off for new installs until UMS V1.2 PTF4. 
You enable it by adding 
useSAFOnly: true
or by changing:
useSAFOnly: false to useSAFOnly: true 
in your UMS configuration YAML file PARMLIB(ZWEYAML) in the section components.izp.security:

    security:                                                     
      #                                                           
      useSAFOnly: true                                            

Step 4: Restart Zowe and UMS

Finally restart Zowe and UMS:
/P ZWESLSTC
[wait until started task has come down]
/S ZWESLSTC

Once UMS has started you will see the message:
IZPSC0008I - Using saf security mode because useSAFOnly is true.   

Cleaning up

After you have tested the new security mode and found that everything works as expected you can delete the following artifacts:

• hlq.USERLIST dataset
• hlq.TEAMLIST PDS/E library 
• SAF profiles related to protection of the datasets above.
• Surrogate users IZPSRGAD and IZPSRGSP
• Do not remove the sections components.izp.security.surrogateUser, components.izp.security.surrogateGroup, components.izp.datasets.userList, and components.izp.datasets.teamList in PARMLIB(ZWEYAML)

UI related changes

There are two UI related changes after activating the new security mode:
1.    Any user, role, and team information is now read-only in the UI, as any changes to users, roles, and teams are now managed through your ESM
2.    The UI relies on cached information. In the UI we show the timestamp for the last refresh of the cache, and there is a button available to refresh the cache. Note that refreshing the cache is only allowed for users with READ on IZP.FUNCTION.<type>.GET in class IZP. 
Here’s an example from Manage -> Users:
The first time you enter you will see a warning message about the cache not being initialized. 

If you are authorized to refresh the list, you will see the refresh button to the far right. Click it to refresh the cache:

Similarly, if you navigate to Manage -> Teams and “Edit” the team, you can view the team list information, but no longer manage the list of users or who is team administrator or not. 
Also notice that the SAF qualifier is shown. In this case the SAF qualifier is “N9CO5F76”, so the related profile is IZP.TEAM. N9CO5F76 in class IZP.