How to configure identity assertion

To enable identity assertion for API requesters, you must configure the idAssertion attribute in the server.xml file. You might also need to define SAF SURROGAT profiles.

Before you begin

Study the information in Identity assertion for API requesters.
Set up the connection from the z/OS subsystem to the IBM z/OS Connect server.
- For CICS, see Configure CICS to access IBM z/OS Connect to call APIs.
- For IMS, see Configuring IMS to access IBM z/OS Connect for API calls.
- For other z/OS applications, see Configuring other z/OS applications to access IBM z/OS Connect for API calls.
Complete the task How to activate and configure the SAF user registry to configure the IBM z/OS Connect server to use z/OS authorized services and a System Authorization Facility (SAF) user registry.
Configure security for the z/OS subsystem connection to the IBM z/OS Connect server according to your needs.
- For basic authentication, see API requester basic authentication to IBM z/OS Connect.
- For client authentication, see API requester client certificate authentication to IBM z/OS Connect.
If you want a surrogate check made on the asserted identity, you must ensure that the following requirements are completed:
- The user ID that is used to run the IBM z/OS Connect server instance must have READ access to the BPX.SERVER FACILITY class profile.
- The Java™ library libifaedjreg64.so must be program-controlled. For example, enter the following command:
  extattr +p /usr/lib/java_runtime/libifaedjreg64.so
- Third-party native code or native libraries, such as those used by a IBM z/OS Connect interceptor must be program-controlled. To define the native code or native library to be program-controlled, enter the following command under z/OS UNIX System Services:
  extattr +p <your library file path>
  
  Note: When your administrator applies maintenance to the Java library, this setting might be reset, so you must reenter this command.

About this task

You configure the IBM z/OS Connect server to specify that the API requester is invoked by the z/OS application asserted user ID. You can also specify that a SAF SURROGAT profile check is required to ensure that the link user ID, which has authenticated with the IBM z/OS Connect server, is authorized to act as a surrogate of the z/OS application asserted user ID.

This task assumes that RACF is used as security manager. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.

The asserted identity needs to be defined in a RACF system that can be accessed by the LPAR where IBM z/OS Connect is running.

Procedure

The following steps demonstrate how to enable a z/OS application to invoke an API requester with an asserted identity that is provided in the z/OS application context.

Configure the idAssertion attribute in the server.xml file.
- If you want to enable the z/OS application to invoke an API requester with an asserted identity and don't need the IBM z/OS Connect server to perform a surrogate check, set the idAssertion attribute to ASSERT_ONLY.
```
<zosconnect_apiRequesters location="/myserver/resources/zosconnect/apiRequesters" idAssertion="ASSERT_ONLY">
```
- If you want to enable the z/OS application to invoke an API requester with an asserted identity and also want the IBM z/OS Connect server to perform a surrogate check, ensure the requireAuth attribute for the request is set to true and set the idAssertion attribute to ASSERT_SURROGATE.
```
<zosconnect_apiRequesters location="/myserver/resources/zosconnect/apiRequesters" idAssertion="ASSERT_SURROGATE">
```
  For more information about how to set the requireAuth attribute for a request, see Step 1 in How to configure basic authentication with a SAF user registry.
Note:
- If you set the requireAuth attribute to false, the IBM z/OS Connect server does not require authentication for a request. If you also set the idAssertion attribute to ASSERT_SURROGATE, a warning message occurs and the IBM z/OS Connect server uses the value ASSERT_ONLY instead.
- If you set the idAssertion attribute for a specific API requester, it overrides the global setting for that specific API requester. For example,
```
<zosconnect_apiRequesters updateTrigger="polled" >
   <apiRequester name="myRequester" idAssertion="ASSERT_SURROGATE"/>
</zosconnect_apiRequesters>
```
- The examples above show how to set the idAssertion attribute for all API requesters on the zosconnect_apiRequesters element. Alternatively, If you want to configure Identity assertion for individual API requesters, you can configure the idAssertion attribute on the zosconnect_apiRequesters > apiRequester subelement, which overrides the value configured on the zosconnect_apiRequesters element. You can configure the idAssertion attribute at both scopes to set the required identity assertion for most of the API requesters deployed to this server and then override that value for individual API requesters which have a different requirement.
Configure authorization for the asserted identity to perform the Invoke action on the API requester.
- Ensure that the authorization interceptor is configured to allow the IBM z/OS Connect server to perform authorization checks.
- Ensure that the asserted identity is added into a SAF group that is assigned to the Admin or Invoke authorization level so that the asserted identity can pass the authorization check for the API requester.
For more information about how to configure authorization for the asserted identity, see How to configure authorization levels with a SAF user registry.
Optional: If the requireAuth attribute for the request is set to true, then IBM z/OS Connect can also check whether the link user ID used for authenticating the z/OS subsystem access to the IBM z/OS Connect server is a surrogate of the z/OS application asserted user ID. To authorize the link user ID as a surrogate of the z/OS application asserted user ID, perform the following steps:
1. Define a profile named assertedid.BAQASSRT in the SURROGAT class, where assertedid represents the z/OS application asserted user ID that is provided in the z/OS application context.
  For example, if the asserted identity is FRED, issue the RACF command: RDEFINE SURROGAT FRED.BAQASSRT UACC(NONE) OWNER(FRED).
2. Grant the identity that is used for authentication READ access to the assertedid.BAQASSRT profile in the SURROGAT class.
  For example, if the link user ID is LINKID1 and is allowed to act as a surrogate of z/OS application asserted user ID FRED, issue RACF command: PERMIT FRED.BAQASSRT CLASS(SURROGAT) ID(LINKID1) ACCESS(READ)