Identity assertion for API requesters

z/OS® Connect provides the capability of allowing a z/OS application to invoke an API requester with an asserted identity that is provided in the application context.

zosConnect-2.0 Applies to zosConnect-2.0.

Before you study this topic, you should be familiar with the information in Overview of IBM z/OS Connect security, API requester authentication and identification, and API requester authorization.

Figure 1 illustrates how identity assertion works in IBM® z/OS Connect.
Figure 1. An illustration of the identity assertion function
Diagram showing how identity assertion works in z/OS Connect for API requesters.

Two user IDs are included in Figure 1:

The link user ID
The identity that is used to authenticate the z/OS subsystem access to the z/OS Connect Server. It is configured using basic authentication or client authentication, for more information about configuring this user ID, see API requester basic authentication to IBM z/OS Connect or API requester client certificate authentication to IBM z/OS Connect.
The z/OS application asserted user ID
An identity that is provided in the z/OS application context.
  • For CICS applications, the z/OS application asserted user ID is the task owner ID.
  • For IMS applications, the z/OS application asserted user ID is the transaction owner ID.
  • For other z/OS applications, the z/OS application asserted user ID is the job owner ID.

As illustrated in Figure 1, a secure connection is set up from the z/OS subsystem to z/OS Connect by using the link user ID for authentication. Instead of using the link user ID, the z/OS application attempts to invoke an API requester by using the z/OS application asserted user ID as an asserted identity. When the z/OS application sends a request to the z/OS Connect Server, the z/OS application asserted user ID is flowed to the z/OS Connect Server in a proprietary header. Depending on which values you configure for the requireAuth and idAssertion attributes in the server.xml file, the z/OS Connect Server performs different actions on the user IDs.

Important: Authorization interceptor is required for the identity assertion function to work.
The following table shows the actions that are performed by the z/OS Connect Server based on the value of the requireAuth and idAssertion attributes.
Note: The following actions assume that the authorization interceptor is enabled so that z/OS Connect can perform the authorization check.
Table 1. z/OS Connect actions on different value combinations of requireAuth and idAssertion
Value of requireAuth Value of idAssertion Actions performed by z/OS Connect
true OFF Identity assertion is disabled. z/OS Connect authenticates the link user ID. If the authorization interceptor is configured, it checks whether the link user ID has the authority to invoke the API requester.
ASSERT_SURROGATE Identity assertion is enabled. The z/OS Connect Server authenticates the link user ID, and performs a SAF SURROGAT profile check, to ensure it is a surrogate of the z/OS application asserted user ID. If the link user ID is a surrogate of the z/OS application asserted user ID, the server further checks whether the z/OS application asserted user ID has the authority to invoke an API requester; otherwise, a BAQR7114E message occurs.
ASSERT_ONLY Identity assertion is enabled. The z/OS Connect Server authenticates the link user ID, and directly checks whether the z/OS application asserted user ID has the authority to invoke an API requester.
false OFF Identity assertion is disabled. If there is no link user ID and the authorization interceptor is configured, the BAQR0407W message is issued to indicate that no authenticated user ID is associated with the request and the authorization interceptor rejects the request.
ASSERT_SURROGATE Identity assertion is enabled. The z/OS Connect Server checks whether the z/OS application asserted user ID has the authority to invoke an API requester, and a warning message occurs to indicate that the ASSERT_ONLY value is used instead of the ASSERT_SURROGATE value.
ASSERT_ONLY Identity assertion is enabled. The z/OS Connect Server checks whether the z/OS application asserted user ID has the authority to invoke an API requester.
Note:
  1. The link user ID and z/OS application asserted user ID might be granted with different authorities to perform actions on API requesters. When authentication is required for the access from the z/OS subsystem to the z/OS Connect Server and identity assertion is enabled, the link user ID is only used for API requester authentication and the z/OS application asserted user ID is used for the API requester authorization check.
  2. When you enable identity assertion without authentication on the z/OS subsystem access to the z/OS Connect Server or surrogate check, you must ensure that the z/OS application asserted user ID is trusted and allowed to access the z/OS Connect Server, which means that the z/OS application asserted user ID must be authorized to the zosConnectAccess role. For more information about configuring the zosConnectAccess role, see How to configure the zosConnectAccess role with a SAF user registry.
  3. SAF credentials can be cached to improve performance. The SAF cache contains SAF user IDs and any associated RACF groups in which the user ID resides. The SAF cache is only applicable to API requester, and only when ID assertion is enabled. For more information, see zosconnect_authorizationInterceptor. You can clear this cache by using the Modify command. For more information, see The MODIFY command zosConnect-2.0.

By default, identity assertion is disabled (OFF) for all API requesters. You can enable identity assertion for all API requesters by configuring the idAssertion attribute on the zosconnect_apiRequesters element. Alternatively you can enable identity assertion for individual API requesters by configuring the idAssertion attribute on the zosconnect_apiRequesters > apiRequester subelement, which overrides the value configured on the zosconnect_apiRequesters element.

For information about configuring the z/OS Connect Server for identity assertion, see: