How to configure basic authentication with a basic user registry

Configure IBM® z/OS® Connect to perform basic authentication with a basic user registry.

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

Before you begin

About this task

You configure a basic user registry that defines a set of users and groups directly into the configuration file, which is used for authentication and authorization. This configuration is typically used in a development environment. The user IDs are "gjones", "mlee", and "rkumar" and the groups are "administrators" and "students". The user "gjones" is a member of the "administrators" group and users "mlee" and "rkumar" are members of the "students" group.

Note: Authentication is not enforced unless authorization roles are defined for the API operations.

During authorization the basic registry groups that the authenticated basic registry user is a member of are compared against the required API operation roles.


For more information about configuration elements, see Configuration elements in the Reference section.

  1. Enable the appSecurity-2.0 Liberty feature in the configuration file.
    For example,
    <featureManager> <feature>appSecurity-2.0</feature> </featureManager>
  2. Add the basicRegistry element to the configuration file.
    Add user and group subelements to define each of your users and groups.
    <basicRegistry id="basic" realm="customRealm">
        <user name="gjones" password="{xor}Lz4sLCgwLTs=" />
        <user name="mlee" password="p@ssw0rd" />
        <user name="rkumar" password="pa$$w0rd" />
        <group name="administrators">
            <member name="gjones" />
        <group name="students">
            <member name="mlee" />
            <member name="rkumar" />
    For more information, see Basic User Registry (basicRegistry) in the WebSphere Application Server for z/OS Liberty documentation.
    Be aware of the following considerations when you use this code sample:
    • You must use unique names for your users and groups.
    • Remove all leading and trailing spaces from the user and group names.
    • If the user name or password contains characters other than US-ASCII, make sure that the file is saved by using UTF-8 character encoding.
    • You can use the WebSphere® Liberty profile securityUtility encode command to encode the password for each user. The securityUtility command-line tool is available in the <installation_path>/wlp/bin directory. When you run the securityUtility encode command, you either supply the password to encode as an input from the command line or, if no arguments are specified, the tool prompts you for the password. The tool returns the encoded value. Copy the encoded value and use it for the password attribute value. An example is shown on the entry for user "gjones" above.

      For example, to encode the password openSesame, run the following command:

      securityUtility encode openSesame

      For more information, see the securityUtility command in the WebSphere Application Server Liberty documentation.


The pre-defined set of users and groups that are defined in the basic user registry can be used to authenticate with IBM z/OS Connect.