IBM Support

User registry, groups, and roles

News


Abstract

The IWS server has been enhanced in the area of authentication and authorization to supplement the available options by providing a user registry.

Content

What is it?

A user registry holds unique user account credentials, primarily usernames and passwords, which are accessed during authentication.

The user registry is automatically enabled when a new server is created that is running a Java Runtime Environment (JRE) of 8 or greater.  Existing servers need to go into server properties and enable the user registry.  A server must be running JRE 8 or greater for the user registry to function properly.  The JRE for a server can be changed by navigating to the server properties and selecting the JRE tab.
By default, the user registry is based on user profiles.  The user registry can also be based on a validation list object or a file.
The web administration GUI shows the following panel for configuring the user registry:
image 7700
  • Realm. The realm identifies the security domain that defines the authentication schema and collection of users and groups.
  • Use secure connections. You can indicate that the authentication flow between the IWS server and the host server job running on the IBM i server is to be done over a secure connection.  In order for this to occur, the host server jobs need to be configured for SSL and the default keystore for the IWS server must be set.
  • Path to role definition file. The path to an XML document that maps roles to users and groups in the domain user registry.  When you deploy a web service and you protect the web service, you can indicate what roles are authorized to the web service.  Here is an example of a file that defines the “admin” role:
      
    <?xml version="1.0" encoding="UTF-8"?>

<server>
  <IBMiUserRegistry> 
    <role name="admin">
      <user name="user1" />
      <user name="user2" />
      <group name="testers" />
    </role>
  </IBMiUserRegistry> 
</server>
  • Path to group definition file. The path to an XML document that defines groups and users that are members of the groups.  Here is an example of a file that defines the “testers” group:
      
    <?xml version="1.0" encoding="UTF-8"?>

<server>
  <IBMiUserRegistry> 
    <group name=”testers">
      <member name="user3" />
      <member name="user4" />
    </group>
  </IBMiUserRegistry> 
</server>
    The group definition file is read upon startup.  Any updates to the group definition file after it is read by the user registry requires a server restart in order for the updates to take effect.
  • Normalize login name case. Specifies whether to normalize login name case before authentication.  You can indicate uppercase, lowercase, or none.  A registry based on validation lists or files is sensitive to the login case.  A registry based on user profiles is not.
  • User registry.  By default, the user registry is based on user profiles for authentication.  If you select validation list for authentication, you can specify a path to a validation list, such as:  /QSYS.LIB/MYLIB.LIB/MYLIST.VLDL.

    If you select a file for authentication, you can specify a path to a file, such as /registry/users.xml.  Here is an example of a file that defines users:
      
    <?xml version=”1.0” encoding=”UTF-8”?>

<server>
  <IBMiUserRegistry> 
      <user name=”user1” password=”{xor}Lz4sLChvLTs=”/>              
      <user name=”user2” password=”user2passw0rd”/>              
  </IBMiUserRegistry> 
</server>
     Passwords can be specified in "exclusive or" (XOR) encoding.
Changes to the user registry configuration require the server to be in a stopped state.

Why use it?

The process of authenticating users involves a user registry and an authentication mechanism. Users of the integrated web services (IWS) server have generally relied on two ways to protect web services or APIs:
  1. Using the HTTP Server associated with the IWS server and enabling basic authentication provided by the HTTP Server.
  2. Web service defined authentication mechanism where security data is passed as parameters to web service implementation code and it is up to the web service implementation code to authenticate
The IWS server has been enhanced to supplement the options by providing support for a user registry built into the IWS server and the ability to integrate third-party security services by using a trust association interceptor (TAI).
You can indicate that all authenticated users can access the web service, or you can indicate only certain roles are authorized to use the web service.  In the latter case, a user must be authorized to the role or be member of a group that is authorized to the role. In order to use roles, you must have specified a role definition file.

In addition, you can get even more granular with roles by specifying different roles for different procedures.  For example, you can indicate that only the role “Teacher” is able to perform updates using the HTTP PUT method and the role “Student” is limited to retrieving information (the HTTP GET method).
The web administration GUI shows the following panel during deployment of a web service:
image 7701
  • Secure transport is required. Whether a secure transport is required to access the web service.  This is a recommended option if you are passing passwords between the client and the server, or if you want clients to access the web service only over secure connections.  Note you have to configure an SSL endpoint (using the SSL wizard) in the server in order for this option to work.  
  • Protect using authentication method. The authentication mechanism of *BASIC indicates the web service is protected that uses basic authentication – a user ID and password must be passed in.  However, if TAI is configured, the TAI can authenticate the client via other mechanisms and thus a user ID and password would not need to be sent as part of the client request, unless you configure the TAI to indicate that if the TAI fails to authenticate, then it should fall back to application (web service) authentication, in which case a user ID and password would need to be sent if you wanted the authentication to succeed.
  • Authorized roles.  If the authentication method is *BASIC, and you define roles in the user registry, you can indicate what roles are authorized to the web service.  If you do not assign authorized roles, then the result is that all authenticated users are able to access the web service. You can also assign a subset of the roles for every procedure, so that different procedures allow a subset of the roles assigned for the web service.
You can indicate the web service should be protected when deploying a service using Qshell command installWebService.sh command by adding the following line in the property file:
  
ws.iws.gen.authenticationmethod=*BASIC
You can also indicate that a secure transport is required by adding the following line in the property file:
  
ws.iws.gen.securetransportrequired=true
You specify roles in the properties file by specifying role statements in the following format:
  
ws.iws.gen.authorizationrole.N=
Where “N” is a number starting from 1 and increasing sequentially. For example, if the roles “testers” and “administrators” are authorized to the web service, you would need to specify the following in the property file:
  
ws.iws.gen.authorizationrole.1=testers
ws.iws.gen.authorizationrole.2=administrators
To authorize a subset of the web service authorized roles for a procedure, the role statement must be specified in the following format:
ws.method.PPPPPP.gen.authorizedrole.N=
Where "PPPPPP" is the procedure name and “N” is a number starting from 1 and increasing sequentially. For example:
ws.method.PROC1.gen.authorizedrole.1=testers

Availability

The support is enabled in the following HTTP group PTFs and PTFs:

V7R2M0  SF99713 Level 40, SI75444,SI75178
V7R3M0  SF99722 Level 28, SI75443,SI75177
V7R4M0  SF99662 Level 09, SI75442,SI75176

[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"HW1A1","label":"IBM Power Systems"},"Component":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB08","label":"Cognitive Systems"}}]

Document Information

Modified date:
26 February 2021

UID

ibm16396442

Page Feedback