Accessing z/OS security resources using WZSSAD

The WLP z/OS® System Security Access Domain (WZSSAD) refers to the permissions granted to the Liberty server. These permissions control which System Authorization Facility (SAF) application domains and resource profiles the server is permitted to query when authenticating and authorizing users.

For example, if you want to set up two Liberty server instances, one for production and one for test and you want your role access to be different between production and test, you can set up two different System Security Access Domains.

The Liberty server is an unauthorized program that can be configured and run by non-administrator or non-privileged users, so it is important for system security and integrity purposes that the user is prevented from leveraging the server to run security operations for which they have not been explicitly granted permission.

Note: The WZSSAD is in effect only when the server is using authorized SAF services for authentication and authorization. This means the angel process is running, and the server has been granted permission to use the SAFCRED authorized service routines.

There are three SAF operations that are protected by the WZSSAD:

Authenticating a user
Authorizing a Subject to a Java™ EE role
Authorizing a Subject to other SAF resources

By default, the WZSSAD is not configured, which means the server has no permission to authenticate or authorize anything. For example, the Liberty server cannot use authorized SAF services for authentication or authorization until an administrator grants it permission to perform some or all of the operations.

Authenticating a user

The server authenticates users to a particular SAF domain that is configured by defining a resource, which is referred to as the APPLID in the APPL class. In order to authenticate a user to the domain, the user must have READ access to the APPLID resource in the APPL class. In addition, whenever the APPL class is active, the unauthenticated user ID (which is WSGUEST by default) also requires READ access to the APPLID resource in the APPL class.

The APPLID resource name used by the server is specified by the profilePrefix attribute in the <safCredentials> configuration element. If you do not specify this element, then the default profilePrefix of BBGZDFLT is used.

The following example shows how to configure a profilePrefix of BBGZDFLT in the server.xml file:

<safCredentials profilePrefix="BBGZDFLT"/>

The following example shows how to use RACF® commands to configure the APPLID as BBGZDFLT:

// Define the BBGZDFLT APPLID to RACF.
RDEFINE APPL BBGZDFLT UACC(NONE)

// Activate the APPL class. 
//If not active, the domain is not restricted, which means anyone can authenticate to it.
SETROPTS CLASSACT(APPL)

//All users to be authenticated by the server must have READ access to the APPLID in the APPL class:
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(UserID)

//The unauthenticated user ID requires READ access to the APPLID in the APPL class:
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(WSGUEST)

In addition, the server must be granted permission within the WZSSAD to make authentication calls in the given APPLID domain. This prevents an unauthorized user from leveraging the server's use of authorized SAF services to discover information about which APPLIDs can and cannot be authenticated. To grant the server permission to authenticate in a particular APPLID domain, the started task ID of the Liberty server must be granted READ access to the BBG.SECPFX.<APPLID> profile in the SERVER class:

RDEFINE SERVER BBG.SECPFX.BBGZDFLT UACC(NONE)
PERMIT BBG.SECPFX.BBGZDFLT CLASS(SERVER) ACCESS(READ) ID(serverUserId)

Authorizing a Subject to a Java EE role

The server authorizes a subject against a Java EE application security role name by checking whether the subject is authorized to a SAF resource profile defined in the EJBROLE class. The SAF resource profile name is mapped from the application role name via the SAF role mapper. The SAF role mapper generates a SAF profile name for a given application role name and application resource name. By default, it generates the SAF profile name using the pattern {profilePrefix}.{resource}.{role}. For example:

profilePrefix="BBGZDFLT"

Application resource name = "MYAPP"

Application role name = "ADMIN"

Mapped profile name = "BBGZDFLT.MYAPP.ADMIN"

For more information, see Controlling how roles are mapped to SAF Profiles

The WZSSAD restricts which SAF profiles in the EJBROLE class the server is allowed to perform authorization against. This prevents an unauthorized user from leveraging the server's use of authorized SAF services to discover information about which EJBROLE profiles can or cannot be authorized to. The server must be granted permission to run authorization checks against the HLQ of the EJBROLE profile name. The HLQ of the profile name is the first segment of the profile name, up to but not including the first '.'. For example:

EJBROLE profile name = "BBGZDFLT.ADMIN" 
HLQ = "BBGZDFLT"

To grant the server permission to run authorization checks against the profile HLQ, the user associated with the server process must be granted READ access to the BBG.SECPFX.<HLQ> profile in the SERVER class:

RDEFINE SERVER BBG.SECPFX.BBGZDFLT UACC(NONE)
PERMIT BBG.SECPFX.BBGZDFLT CLASS(SERVER) ACCESS(READ) ID(serverUserId)

In the example, because the SAF role mapper sets the HLQ of the mapped profile to the profilePrefix, the same profile BBG.SECPFX.BBGZDFLT governs both the APPLID authentication permissions, and the EJBROLE profile authorization permissions.

Authorizing a Subject to other SAF resources

Java EE applications can perform access control checks against SAF classes other than EJBROLE. The WZSSAD restricts which SAF classes outside of EJBROLE the server is allowed to authorize against. This prevents an unauthorized user or application from leveraging the server's use of authorized SAF services to discover information about which resource profiles in non-EJBROLE SAF classes the user or application is or is not authorized to.

To grant the server permission to perform authorization checks against non-EJBROLE SAF classes, the user associated with the server process must be granted READ access to the BBG.SECCLASS.<SAF-CLASS> profile in the SERVER class. For example, to authorize against a profile in the FACILITY class:

RDEFINE SERVER BBG.SECCLASS.FACILITY UACC(NONE)
PERMIT BBG.SECCLASS.FACILITY CLASS(SERVER) ACCESS(READ) ID(serverUserId)

Note: There are no restrictions on which resource profiles within the non-EJBROLE class the server is allowed to authorize against. If the server has been granted permission to perform authorization checks against a non-EJBROLE class, then it can authorize against any profile in that class.