Mapping management roles for Liberty

You can use quickStartSecurity element or any supported user registries for administrative role mapping on Liberty.

For the latest documentation about Liberty role mapping, see the Open Liberty website.

About this task

All the JMX methods and MBeans accessed through the REST connector are protected by either the role that is named administrator or the role that is named reader. The administrator role provides read and write access to all JMX methods and MBeans. The reader role provides administrative access to JMX methods and MBeans that are considered read only. To get started quickly, use the quickStartSecurity element to configure a single user with the administrator role and configure the default SSL configuration.

You can also use any supported user registry. You cannot use the quickStartSecurity element if you have already configured another user registry. In this case, map users or roles from the registry to the administrator role.

If user authentication in Liberty is performed with single sign-on (SSO) technologies (for example SAML, OpenID Connect, or JWT), and there is no user registry that is configured, or the user is not in the configured user registry, you can still map the administrator role to a trusted user or group that is authenticated by an SSO server.

Procedure

Use quickStartSecurity element for a single user mapping.

Here is an example that shows the minimal required configuration:

<featureManager>
     <feature>restConnector-2.0</feature>
 </featureManager>
 <quickStartSecurity userName="bob" userPassword="bobpassword" />
 <keyStore id="defaultKeyStore" password="keystorePassword"/>

Or use the basic registry for administrative role mapping.

Here is an example of the basic registry that gives the user "bob" or the group "group1" administrator role:

<basicRegistry>
     <user name="bob" password="bobpassword"/>
     <user name="joe" password="joepassword"/>
     <group name="group1" ...>
     </group>
 </basicRegistry>

 <administrator-role>
     <user>bob</user>
     <group>group1</group>
 </administrator-role>

Or use the LDAP registry for administrator role mapping. (Add the ldapRegistry-3.0 feature to your server.xml file.)
Here is an example of the LDAP registry that gives the user "bob" administrator role.
```
 <ldapRegistry id="basic" host="" port="">
     <tds.properties ... />
 </ldapRegistry>

 <administrator-role>
     <user>cn=bob,o=ibm,c=us</user>
 </administrator-role>
```
Map the administrator role to an SSO user or group that does not exist in the configured user registry. First, configure SSO features, such as samlWeb-2.0, openidConnectClient-1.0, socialLogin-1.0, or mpJwt-1.x.
Liberty security authorization is access-id based. An access-id takes following formats:

access-id for a user:
```
user:<security realm name>/<user name>
```
access-id for a group:
```
group:<security realm name>/<group name>
```
For example, if a user is authenticated as tom@example.com, and the SSO server or issuer is identified as https://idp.example.com, the access-id for this user in Liberty issuer is: user:https://idp.example.com/tom@example.com.
Assign an administrative role to a user authenticated by the SSO server. Map the role to the user's access-id instead of the user name. The following example shows how to assign an administrative role to the user tom@example.com, authenticated by the SSO server https://idp.example.com.
```
<administrator-role>
     <user-access-id>user:https://idp.example.com/tom@example.com</user-access-id>
</administrator-role>
```

Similarly, to map an administrative role to a group from an SSO server, you map the role to the group access-id. For example:

<administrator-role>
     <group-access-id>group:https://idp.example.com/ManagerGroups</group-access-id>
</administrator-role>

If authentication is performed with mpJwt-1.x, the default user access-id is:
```
user:<value of "iss" claim>/<value of "upn" claim>
```
The default group access-id is:
```
group:<value of "iss" claim>/<value of "groups" claim>
```
If authentication is performed with samlWeb-2.0 feature, the default user access-id is:
```
user:<value of "issuer" assertion>/<value of "NameID" assertion>
```
For more information, see the configuration instructions for your chosen SSO feature.