How to configure the zosConnectAccess role with an LDAP user registry

Assign LDAP users and groups to the zosConnectAccess role to control which users can access IBM® z/OS® Connect.

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

Before you begin

You should be familiar with the information in API provider authorization.
You need to know the users and groups that are to be granted access to IBM z/OS Connect.
You must have completed the task How to configure basic authentication with an LDAP user registry, unless you have authenticated using an alternative method which resulted in the authenticated user ID being an LDAP user ID. For example, using a JWT where the identity in the claim is an LDAP user ID, or client certificate authentication where the client certificate subject's distinguished name has been mapped to an LDAP user ID.
You must have write access to the server.xml configuration file.

About this task

Now you have configured the IBM z/OS Connect server to require authentication by setting the attribute requireAuth="true", you assign LDAP registry users and groups to the zosConnectAccess role.

Procedure

Assign users and groups to the zosConnectAccess role.
Choose whether you want to assign only specific users or groups to the role, or allow all authenticated users to be assigned to the role.

Follow the instructions in step 1.a to assign specific users and groups to the role.
Follow the instructions in step 1.b to allow all authenticated users to be assigned to the role.
1. Configure authorization to access IBM z/OS Connect, by assigning users and groups to the zosConnectAccess role.
  The users and groups must be defined in the LDAP server referenced by the ldapRegistry element. To assign the zosConnectAccess role to a group and a user, add the authorization-roles element to the server.xml configuration file:
```
<authorization-roles id="zos.connect.access.roles"> 
    <security-role name="zosConnectAccess">
        <group name="employees" 
            access-id="group:SampleLdapIDSRealm/cn=employees,ou=groups,o=mop,c=fr"/>
        <user name="PierreDuclos" 
            access-id="user:SampleLdapIDSRealm/uid=PierreDuclos,ou=customers,o=mop,c=fr"/>  
    </security-role>    
</authorization-roles>
```
  This element uses the following values:
  - The values, id="zos.connect.access.roles" and name="zosConnectAccess", must be specified exactly as shown.
  - "employees" is an LDAP group to be assigned to the role. Its distinguished name (DN) is "cn=employees,ou=groups,o=mop,c=fr".
  - "PierreDuclos" is an LDAP user to be assigned to the role. His distinguished name (DN) is "uid=PierreDuclos,ou=customers,o=mop,c=fr".
  - The values for access-id are optional. If not specified, a value will be generated by looking up the user or group in the LDAP server. If specified, the access-id has the following format:
    
    For a group: realmName/groupUniqueId.
    
    For a user: realmName/userUniqueId.
    
    The values are made up of the following components:
    
    realmName is the realm value specified on the ldapRegistry element.
    
    groupUniqueId is the distinguished name (DN) value of the group. The value is not case sensitive.
    
    userUniqueId is the distinguished name (DN) value of the user. The value is not case sensitive.
2. Configure authorization to access IBM z/OS Connect, by assigning the special subject type "ALL_AUTHENTICATED_USERS" to the zosConnectAccess role.
  Use this method if all authenticated LDAP users and groups are to be authorized to access IBM z/OS Connect. Add the following to the server.xml configuration file:
```
<authorization-roles id="zos.connect.access.roles">
    <security-role name="zosConnectAccess">
        <special-subject type="ALL_AUTHENTICATED_USERS"/>
    </security-role>
</authorization-roles>
```
  This element uses the following values:
  - id="zos.connect.access.roles" and name="zosConnectAccess", must be specified exactly as shown.
  - "ALL_AUTHENTICATED_USERS" is case sensitive.
For more information about the authorization-roles element, see the Server configuration section in the IBM WebSphere® Application Server for z/OS Liberty documentation.
Update the server configuration or restart the server.
The following message appears in the messages.log file:
```
CWWKS9120I: Authorization roles with id="zos.connect.access.roles" have been successfully processed.
```

Results

The LDAP users and groups assigned to the zosConnectAccess role now have authorization to access IBM z/OS Connect.

What to do next

You might be interested in configuring more specific authorization. See the task How to configure authorization levels with an LDAP user registry.