| This blog was originally published on October 5, 2016, by Nigel Williams, IBM Systems Center Montpellier. |
Introduction
z/OS Connect EE benefits a great deal from the security foundation of Liberty z/OS, for example for authentication and support for encryption. However, z/OS Connect EE supplements these foundational security capabilities with specific security capabilities, for example, to control access to APIs and services.
One of the main advantages of z/OS Connect EE is that it supports a common security model for REST API enablement of z/OS applications. This article considers how APIs can be secured with z/OS Connect EE (see Figure 1).
Figure 1 z/OS Connect EE security considerations
In most cases, z/OS Connect EE will be used in conjunction with other servers such as a security or API gateway. In this article we refer to such a server as a ‘trusted server’.
Figure 1 highlights the main z/OS Connect EE security considerations:
Authentication – this answers the “who are you?” question. There are several ways this can be accomplished; either the REST client can authenticate with a trusted server (as shown in Figure 1) or the REST client can authenticate directly with z/OS Connect EE.
Encryption – often referred to as “SSL” (though more accurately we mean “Transport Layer Security” or “TLS”). This protects communications between REST clients and z/OS Connect EE.
API Layer Security – these are the security policies that we apply to APIs.
Service Layer Security – we can also apply security policies to the underlying services.
Role Access -– assuming authentication is successful, the next question is whether the user is permitted to access the z/OS Connect EE server. This is accomplished with an application role, and for a user to succeed, the user ID needs to be on the access list for the role.
Group Authorization – this determines who is allowed to perform actions on an API. This is done with a group-based authorization model.
SAF Security – System Authorization Facility (SAF) can be used to secure the z/OS Connect server runtime, and also for authentication and authorization. RACF is IBM’s implementation of SAF.
SMF Audit – z/OS System Management Facility (SMF) can be used to provide an audit log of who has accessed which APIs.
Identity propagation – finally, with a user ID authenticated and authorized to access an API, the question is whether you want the request to the backend system of record to be performed using the authenticated user ID. This is known as “identity propagation” and can be accomplished based on the connectivity mechanism used and the state of the security setup in the backend system.
In the remainder of this article we look more closely at how z/OS Connect EE can be used to perform the following basic security requirements; authenticate REST clients, authorize access to APIs, audit requests, and ensure confidentiality and data integrity.
Authentication
By default, z/OS Connect EE requires users to be authenticated. This is controlled by the requireAuth attribute on the zosConnectManager, zosConnectAPI and zosConnectService elements of the server.xml configuration file. The default value is true. However, this value can be set to false to remove the requirement for users to be authenticated.
z/OS Connect EE builds on the authentication mechanisms supported by Liberty z/OS (Figure 2).
Figure 2 Authentication options
Figure 2 shows 3 basic mechanisms for authenticating REST clients with z/OS Connect EE:
- Basic authentication directly to the Liberty z/OS server – The REST client is prompted for a user ID and password. The user’s credentials are then validated against the configured user registry and the user is authenticated (or not). The registry can be something really simple (in the server.xml file), in LDAP, or in SAF.
- A second mechanism is to present a TLS client certificate, and based on the authenticity of the certificate, the user identity can be established by mapping the certificate information to a user ID. This is the mechanism that is likely to be used when there’s a trusted server in front of z/OS Connect EE. The trusted server presents a client certificate to z/OS Connect EE, and is authenticated and allowed in based on that. From there all requests run under the user ID of the trusted server.
- The final picture shows another way to establish identity, and that’s with a trusted third party doing the authentication. The end user authenticates with the trusted third party and receives a token establishing the authenticated credentials of the user (the token does not contain a password). An example of such a token is a WebSphere LTPA token (acronym = “Lightweight Third Party Authentication”). z/OS Connect EE can be configured to map the token to an identity in the user registry (for example, ‘FRED’ as shown in Figure 2).
Authorization
If authentication is enabled, users must be defined in the configured user registry and the user ID must be authorized to access the z/OS Connect EE server. This can be configured in the server.xml file configuration as shown in Example 1.
Example 1 Authorizing access to z/OS Connect using server.xml
<authorization-roles id="zos.connect.access.roles">
<security-role name="zosConnectAccess">
<user name="Fred"/>
</security-role>
</authorization-roles>
Alternatively, you can use RACF to authorize a user ID to the zosConnectAccess role, as shown in Example 2.
Example 2 Authorizing access to z/OS Connect using RACF
RDEFINE EJBROLE BBGZDFLT.zos.connect.access.roles.zosConnectAccess UACC(NONE)
PERMIT BBGZDFLT.zos.connect.access.roles.zosConnectAccess CLASS(EJBROLE)
ID(FRED) ACCESS(READ)
Optionally, you can also enable the z/OS Connect authorization interceptor which will check if the user is authorized to perform the requested action on the API (Figure 3).
Figure 3 API authorization
The authorization interceptor provides 4 levels of authority:
- Administrator – full authority
- Operator – the ability to use REST APIs to control the configured APIs and services, such as starting and stopping an API
- Invoke – the ability to invoke the configured APIs or services
- Reader – the ability to read the Swagger document, access and import the API, read a list of all APIs and services, and get detailed information
The interceptor can be configured at the global level (all configured APIs and services), at the API or service level, or a combination of the two.
Example 3 shows how RACF can be used to create an authorization group, and how the user ID FRED can be connected to the group.
Example 3 RACF group definition
ADDGROUP APIUSERS OMVS(GID(xxx)) OWNER(xxxx)
CONNECT FRED GROUP(APIUSERS)
Example 4 shows how the z/OS Connect EE authorization interceptor can be enabled for an API, so that only users in the group APIUSERS can invoke the API.
Example 4 Authorizing access to invoke an API in server.xml
<zosConnectAPI name="api1" invokeGroup="APIUSERS"/>
Note: If you want to perform additional authorization checking in the backend system then, depending on which Service Provider is being used, you can configure the backend system so that the target program runs with the same user ID that is used for z/OS Connect EE authorization.
Audit
z/OS Connect EE also provides an audit interceptor which can be used to selectively audit API requests. The audit interceptor records request activity in SMF type 123, subtype 1 records. The audit record includes date and time stamps, target URI, name of API or service, and the user name. For more information on the structure of the audit record, see API provider audit in the z/OS Connect EE V3.0 documentation.
Encryption and Data Integrity
The SSL/TLS protocol provides transport layer security including authenticity, data signing, and data encryption that can be used to ensure a secure connection between a REST client and a z/OS Connect EE server.
By default, z/OS Connect EE requires an SSL/TLS connection from the client, and it also defaults to client authentication. This is controlled by the requireSecure attribute on the zosConnectManager, zosConnectAPI, and zosConnectService elements of the server.xml configuration file. The default value is true. However, this value can be set to false to remove the requirement for an SSL/TLS connection. If SSL/TLS is enabled, there is an option to use basic authentication instead of client authentication.
z/OS Connect EE builds on the SSL/TLS support provided by Liberty z/OS which uses Java Secure Sockets Extension (JSSE). JSSE relies on X.509 certificate-based asymmetric key pairs for secure connection protection and some data encryption. Key pairs effectively encrypt session-based secret keys that encrypt larger blocks of data.
More information
More information on configuring security with z/OS Connect EE, see the security section of the z/OS Connect EE V3.0 documentation in the IBM Knowledge Center.
You should also watch out for further articles here on securing z/OS Connect EE.