Admin REST Connector
2.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

You can configure management roles for your Open Liberty server to grant users and groups that are defined in a user registry access to select administrative REST APIs. The administrator role (administrator-role) provides read and write access to administrative REST APIs. The reader role (reader-role) provides read-only access to administrative REST APIs. Users who are in the reader role can monitor the server but do not have permission to modify it in any way.

In the following example, a user who is named Bob and a group that is named employees are granted the reader role. A user who is named Wanda and a group that is named managers are granted the administrator role:

<reader-role>
    <user>Bob</user>
    <group>employees</group>
</reader-role>

<administrator-role>
    <user>Wanda</user>
    <group>managers</group>
</administrator-role>

You can use access IDs to map a role to a user or group that does not exist in the configured user registry. 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>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>group:https://idp.example.com/[email protected]</user-access-id>
    <group-access-id>group:https://idp.example.com/ManagerGroups</group-access-id>
</administrator-role>

Liberty API packages provided by this feature

  • com.ibm.websphere.filetransfer

  • com.ibm.websphere.jmx.connector.rest

  • com.ibm.ws.jmx.connector.client.rest

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-19.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

com.ibm.websphere.appserver.restConnector-2.0; type="osgi.subsystem.feature"