Admin REST Connector2.0
A secure, REST administrative connector that can be used locally or remotely using any Java developer kit. This connector enables remote access from a Java client or directly through an HTTPS call. The administrator and reader roles protect the connector. The connector requires TLS to keep the communication confidential. The HTTPS port used by the connector is defined through the default HTTP endpoint. This feature supersedes the restConnector-1.0 feature. It enables the REST handler configuration APIs. When this feature is combined with features supporting configuration validation, the corresponding REST handler validation APIs are enabled.
Enabling this feature
To enable the Admin REST Connector 2.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:
<feature>restConnector-2.0</feature>
Examples
Configure REST API management roles
When the REST connector feature is enabled, you can configure management roles for your Open Liberty server. These roles grant users and groups that are defined in a user registry access to select administrative REST APIs. You can use any supported user registry.
Administrator role: Grants users read and write access to administrative REST APIs, including the ability to modify their configuration or settings.
Reader role: Grants users the same permissions to monitor the server as in the administrator role, but without the ability to modify any configuration or settings. The reader role provides access to REST APIs that are considered read-only. Users in this role can monitor the server, but cannot modify it in any way.
The following example maps users and groups that are defined in a basic user registry to the reader and administrator roles.
<basicRegistry>
<user name="Bob" password="bobpassword"/>
<user name="Wanda" password="wandapassword"/>
<user name="Todd" password="toddpassword"/>
<group name="managers">
<member name="Wanda"/>
<member name="Todd"/>
</group>
</basicRegistry>
<administrator-role>
<group>managers</group>
</administrator-role>
<reader-role>
<user>Bob</user>
</reader-role>In this example, three users in the user registry are granted roles.
The users
WandaandToddare added to a group named asmanagers. Themanagersgroup is granted the administrator role.The user
Bobis granted the reader role.
To quickly configure a single administrator for testing and development purposes, use the quickStartSecurity element. This option automatically configures a registry with only one user who is granted the administrator role. The following example shows the minimal required configuration.
<featureManager>
<feature>restConnector-2.0</feature>
</featureManager>
<quickStartSecurity userName="bob" userPassword="bobpassword" />
<keyStore id="defaultKeyStore" password="keystorePassword"/>Configure REST API management roles by using access IDs
To map a role to a user or group that does not exist in the configured user registry, use access IDs. If a user or group is authenticated to a single-sign-on server, use the access ID syntax to specify the security realm where the user is authenticated. Access IDs in Open Liberty take the following formats.
Access ID for a user:
user: security realm name / user name
Access ID for a group:
group: security realm name / group name
To specify access IDs, you can use the user-access-id or group-access-id elements, as shown in the following example.
<reader-role>
<user-access-id>user:https://idp.example.com/[email protected]</user-access-id>
<group-access-id>group:https://idp.example.com/EmployeeGroups</group-access-id>
</reader-role>
<administrator-role>
<user-access-id>user:https://idp.example.com/[email protected]</user-access-id>
<group-access-id>group:https://idp.example.com/ManagerGroups</group-access-id>
</administrator-role>Define access-id values for users and groups that are authenticated by MicroProfile JWT
If authentication is performed with MicroProfile JSON Web Token, the default user-access-id is in the following format.
user: value of 'iss' claim / value of 'upn' claim
The default group-access-id is in the following format.
group: value of 'iss' claim / value of 'groups' claim
The following example shows the mapping for a JWT-authenticated user and group. The user is mapped to the administrator role and the group is mapped to the reader role. In this example, the JWT for the user includes an iss value of myCo and a upn value of [email protected]`. The JWT for the group includes an iss value of myCo and a groups value of readers.
<administrator-role>
<user-access-id> user:myCo/[email protected]</user-access-id>
</administrator-role>
<reader-role>
<group-access-id>group:myCo/readers</group-access-id>
</reader-role>User access for SAML Web Single Sign-On
If authentication is performed with SAML Web Single Sign-On feature, the following value is set as the default user-access-id.
user: value of 'issuer' assertion / value of 'NameID' assertion
The following example shows the mapping for a SAML-authenticated user. The user is mapped to the administrator role. In this example, the SAML for the user includes an iss value of myCo and a upn value of [email protected].
<administrator-role>
<user-access-id> user:myCo/[email protected]</user-access-id>
</administrator-role>
