Configuring security for z/OS Connect

The z/OS® connect application can be accessed by authenticated users that are also authorized under the zosConnectAccess role. You can configure group authorization at the service definition level. Group authorization is supported for SAF and LDAP group types.

About this task

Users must be authenticated before the z/OS Connect application can be accessed.

The default authentication mechanism required by z/OS Connect is CLIENT_CERT. Users must be authorized under the zosConnectAccess role to be able to access the z/OS Connect application. The required transport mechanism is HTTPS.

You can configure z/OS Connect to run without any security constraints by setting the requireSecure and requireAuth attribute definitions. These attributes are defined under the zosConnectManager element, which applies to all configured services, or it is defined under the zosConnectService element for a specific service. If the attributes are defined under both the zosConnectService element and globally under the zosConnectManager element, the value defined under zosConnectService is used. See zosConnectManager and zosConnectService for more information on those attributes.

In order to provide a finer level of security, z/OS Connect offers the ability to constrain access based on group authorization that can be configured through SAF or LDAP. For this, z/OS Connect defines three levels of authority:

Administrator - IUsers with administrator authority have the authority to query services, perform operational tasks on them, and invoke them.
Operations - Users with operations authority are be able to perform tasks on services such as stop, start, etc. but they do not have authority to invoke services.
Invoke - Users with invoke authority are be able to invoke services, but have no other authority.

z/OS Connect supplies an authorization interceptor that implements the com.ibm.wsspi.zos.connect.Interceptor() SPI. This interceptor supports both SAF and LDAP. This interceptor uses the getGroupsforUser() security API internally to determine which groups the current user is in, and then compares these groups to the groups provided on the service definition or in the global definition.

When the z/OS Connect supplied authorization interceptor is enabled, the RACF or LDAP group names that are associated with users can also be associated with any of the groups that are mentioned previously at the global or service definition levels. At the global level, they can be defined under the <zosConnectManager> configuration element. The attributes that are defined at this level include: globalAdminGroup, globalOperationsGroup, and globalInvokeGroup. If configured, they apply to all configured services. If more granularity is wanted, the groups can also be configured at the service level under the <zosConnectService>configuration element. The attributes that are defined at that level are: adminGroup, operationsGroup, and invokeGroup. These values, if specified, override the values that are defined globally.

When an authorization interceptor is defined at the global level, authorization checks are done one time for all services. When you use /zosConnect/operations/getStatistics request for more than one service and service discovery, then the user gets information on all services that are registered with z/OS Connect when the following conditions exist:

The user passes the authorization check
No other conditions prevent service information from being returned

If the authorization interceptor is placed in a service level definition, access to information for those services are limited to users that are in that service definition.

For example, given the following configuration with the authorization interceptor defined at the service level:

User "USR1" Groups: ADMINS1, ADMINS2

User "USR2" Groups: OPERATS1

User "USR3" Groups: ADMINS2, OPERATS1

z/OS Connect configuration:

<!-- z/OS Connect global configuration. It applies to all services. -->
<zosConnectManager globalAdminGroup="ADMINS1"  globalOperationsGroup="OPERATS1" globalInvokeGroup="INVOKES1"/>

<!-- Interceptor configuration -->
<zosConnectInterceptors id="interceptorList1"  interceptorRef="zosConnectAuthorizationInterceptor"/>
<authorizationInterceptor id="zosConnectAuthorizationInterceptor"/>

<!--Service 1-->
<zosConnectService serviceName="service1" serviceRef="service1Ref" adminGroup="ADMINS2" operationsGroup="OPERATS2"   interceptorsRef="interceptorList1" .../>

<!--Service 2-->
<zosConnectService serviceName="service2" serviceRef="service2Ref" operationsGroup="OPERATS2"   interceptorsRef="interceptorList1" .../>

<!--Service 3-->
<zosConnectService  serviceName="service3" serviceRef="service3Ref" adminGroup="ADMINS1" interceptorsRef="interceptorList1" .../>

Table 1. . User data access
	service1	service2	service3
USR1	X	X	X
USR2	--	--	X
USR3	X	--	X

Procedure

Setup user authentication to access the z/OS Connect application.

To setup client certificate authentication, see the documentation on configuring your web application and server for client certificate authentication. To setup authentication through a registry, see the documentation on authenticating users in Liberty.

Sample 1: Basic registry configuration using steps outlined in the documentation for configuring a basic user registry for Liberty.

Server.xml:

<featureManager>
	<feature>zosConnect-1.0</feature>
	<feature>transportSecurity-1.0</feature>
	<feature>appSecurity-2.0</feature>
</featureManager>


<!-- Define a keystore. -->
<keyStore id="defaultKeyStore" password="Liberty"/>


<!-- Fail over to basic authenitcation -->
<webAppSecurity allowFailOverToBasicAuth="true"/>


<!-- Basic registry definition -->
<basicRegistry id="basic1" realm="zosConnect">
	<user name="Fred" password="fredpwd"/>
</basicRegistry>

Sample 2: SAF registry configuration using steps outlined in the documentation for activating and configuring the SAF registry on z/OS.

Server.xml:

<featureManager>
	<feature>zosConnect-1.0</feature>
	<feature>transportSecurity-1.0</feature>    
	<feature>appSecurity-2.0</feature>
	<feature>zosSecurity-1.0</feature>
</featureManager>

<!-- Saf registry definition -->
<safRegistry id="saf" realm="zosConnect"/>

RACF setup. For more details follow the documentation on Liberty: Accessing z/OS security resources using WZSSAD:

# Define the APPL class based on the default security prefix called BBGZDFLT.
RDEFINE APPL BBGZDFLT UACC(NONE)

# Activate the APPL class.
SETROPTS CLASSACT(APPL)

# For FRED to be authenticated by the server, assign FRED READ access to the APPLID in the APPL class.
PERMIT BBGZDFLT ID(FRED) ACCESS(READ) CLASS(APPL)

# The unauthenticated user ID (i.e. WSGUEST by default) requires READ access to the APPLID in the APPL class
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(unauthenticatedUserId)

# Grant the server permission to make authentication calls.
RDEFINE SERVER BBG.SECPFX.BBGZDFLT UACC(NONE)
PERMIT BBG.SECPFX.BBGZDFLT ID(serverId) ACCESS(READ) CLASS(SERVER)

Note that the server needs to granted permission to use the SAFCRED authorized service routines. See the documentation on enabling z/OS authorized services on Liberty for z/OS for more details.

Setup user authorization to access the z/OS Connect application by assigning users the zosConnectAccess role.
To do so, see the documentation on configuring authorization for applications on Liberty.
Add the following to the server.xml file configuration outlined in step 1 of sample1:
```
<authorization-roles id="zos.connect.access.roles">
	<security-role name="zosConnectAccess">
		<user name="Fred"/>
	</security-role>
</authorization-roles>
```
Sample2: Authorization configuration using SAF/RACF:
1. Add the following to the configuration outlined in step 1 of sample2.
```
<safAuthorization id="saf2" />
```
2. RACF setup. Commands to assigning FRED the zosConnectAccess role:
```
RDEFINE EJBROLE BBGZDFLT.zos.connect.access.roles.zosConnectAccess
UACC(NONE)
PERMIT BBGZDFLT.zos.connect.access.roles.zosConnectAccess
CLASS(EJBROLE) ID(FRED) ACCESS(READ)
```
(Optional) Define groups for authorization when using z/OS Connect's authorization interceptor.
Sample 1: RACF Group definition when using SAF:
```
ADDGROUP OPERATS1 OMVS(GID(xxx)) OWNER(xxxx)

# Add user FRED under the OPERATS1 group
ADDUSER FRED DFLTGRP(OPERATS1) OMVS(UID(xxx) HOME(/xxxx) PROGRAM(/bin/sh)) NAME('USER FRED') NOPASSWORD
ALTUSER FRED PASSWORD(xxxxxxx) NOEXPIRED

# Connect user Fred to the OPERATS1 group
CONNECT FRED GROUP(OPERATS1)
```
Note that the "OPERATS1" group can then be used when defining authorization groups to be used by z/OS Connect's authorization interceptor. For example: <zosConnectManager globalOperationsGroup="OPERATS1"/> or <zosConnectService serviceRef="service1" operationsGroup="OPERATS1"/>