How to define authorization roles for z/OS Connect zosConnect-3.0

zosConnect-3.0 Applies to zosConnect-3.0.

Define the roles required to invoke each API operation.

This task is applicable when IBM® z/OS® Connect is used as an API provider.

Before you begin

Be familiar with the information in API provider authorization.
Know the names for the roles to be defined and whether the roles are to be assigned globally for the API or for individual API operations.
The z/OS Connect Server must have been configured to authenticate users. For more information, see API provider basic authentication for z/OS Connect zosConnect-3.0, API provider third-party authentication, or API provider client certificate authentication for z/OS Connect zosConnect-3.0.

About this task

Define the roles required to invoke each API operation. The required roles are assigned in the APIs OpenAPI definition by using a custom z/OS Connect OpenAPI 3.0 specification extension called x-ibm-zcon-roles-allowed.

This task illustrates how to:

Define roles that apply to all operations of an API.
Define roles for specific API operations.
Define a generic role that allows all authenticated users to start an API or specific API operations when using an LDAP or a basic user registry.

Warning: You must define roles for user authentication to be enforced. Any API operation that does not have either a specific or API level role definition can be started by unauthenticated users.

Procedure

Locate and open the OpenAPI document.
If the OpenAPI document isn't imported into the Designer UI, then this is your original OpenAPI document.
If the OpenAPI document is imported into the Designer UI, then this is the openapi.yaml or openapi.json file in the API project src/main/api directory. This might be in your local Designer workspace or might be stored in a Source Control Manager.
Open the OpenAPI document in edit mode.

Optional: Assign the roles that apply to all operations in the API.

Define the x-ibm-zcon-roles-allowed in the root of the OpenAPI definition, where the value is an array of role names.

Example 1: to add the Staff role as the default role for all operations in the API by using YAML.

openapi: 3.0.0
info:
  title: EmployeesApi
  version: "1.1"
servers:
- url: http://localhost:9080/
- url: https://localhost:9443/
x-ibm-zcon-roles-allowed:
- Staff
...

Example 2: to add the Staff role as the default role for all operations in the API by using JSON.

{
  "openapi": "3.0.0",
  "info": { "title": "EmployeesApi", "version": "1.1" },
  "servers":[
    {"url":" http://localhost:9080/"},
    {"url":" https://localhost:9443/"},
  ]
  "x-ibm-zcon-roles-allowed": [ "Staff" ],
  ...
}

Optional: Assign the roles that apply to a specific API operation. Assign the x-ibm-zcon-roles-allowed in the appropriate operation section of the OpenAPI document where the value is an array of role names.
Example 1: to add the Manager and HR roles to the Get /employees operations in the API by using YAML.
```
...
/employees:
  get:
    summary: Get all employee details
    operationId: employeesGet
    x-ibm-zcon-roles-allowed:
    - Manager
    - HR
...
```
Example 2: to add the Manager and HR roles to the Get /employees operations in the API by using JSON.
```
...
"/employees": {
  "get": {
    "summary": "Get all employee details",
    "operationId": "employeesGet",
    "x-ibm-zcon-roles-allowed": [
    "Manager",
    "HR"
    ],
...
```
Save the changes to the OpenAPI document.
Regenerate the API to use the specified roles.
If you are using the Designer, the API is automatically regenerated to use the specified roles.
If you are making this change as part of a DevOps pipeline, follow your usual procedure to generate the API from the API project.
Required if using an LDAP or basic registry: Configure role mappings.
A role can be mapped to a user, a group, or the special subject ALL_AUTHENTICATED_USERS or EVERYONE.
1. Deploy the API .war file into a named directory.
  For example, ${server.config.dir}/apps, but not the ${server.config.dir}/dropins directory.
  This requires a webApplication element to be defined in the configuration file to reference the name and location of the .war file. For example,
```
<webApplication name="Employees" location="${server.config.dir}/apps/api.war"></webApplication>
```
2. Add a nested application-bnd subelement to the APIs webApplication element in the configuration file to map each role used in steps 2 and 3 to a registry user, a registry group, or a special subject. For example,
```
<webApplication name="Employees" location="${server.config.dir}/apps/api.war">
	<application-bnd>
		<security-role name="HR">
			<group name="administrators"/>
		</security-role>
		<security-role name="Manager">
			<user name="gjones"/>
		</security-role>
		<security-role name="Staff">
			<special-subject type="ALL_AUTHENTICATED_USERS"/>
		</security-role>
	</application-bnd>
</webApplication>
```
  In this example, the HR role is mapped to the administrators group, the Manager role is mapped to the user gjones, and the Staff role is mapped to the special subject ALL_AUTHENTICATED_USERS.
Required if using SAF authorization: Define SAF EJBROLE profiles to authorize SAF users and groups to the roles, see How to define SAF profiles for authorization roles.

Results

The roles that are required to start the operations in the API are now defined.