Local operating system user registries

 

With the local operating system, or Local OS, user registry implementation, the WebSphere authentication mechanism can use the user accounts database of the local operating system.

WAS provides implementations for Windows NT and Windows 2000 local accounts registry and domain registry, as well as implementations for the Linux, Solaris and AIX user accounts registries. Windows Active Directory is supported through the LDAP user registry implementation discussed later.

A Local OS user registry is not a centralized user registry like LDAP. Do not use a Local OS user registry in a distributed WebSphere Application Server environment, where appservers are dispersed across several machines, because each machine has its own user registry. There are exceptions though, a Windows domain registry is a centralized registry.

Also, as mentioned previously, the access-IDs taken from the user registry are used during authorization checks. Since these IDs are typically unique identifiers, they vary from machine to machine even if the exact users and passwords exist on each machine.

Web client certificate authentication is not currently supported when using the local operating system user registry. However, Java client certificate authentication does function with a local operating user registry. Java client certificate authentication maps the first attribute of the certificate domain name to the user ID in the user registry.

Even though Java client certificates function correctly, the following error displays in the SystemOut.log file: 

SECJ0337E: The mapCertificate method is not supported

The error is intended for Web client certificates; however, it also displays for Java client certificates. Ignore this error for Java client certificates.

 

Using Windows operating system registries

When enabling security on Windows operating systems, if local operating system (LocalOS) is selected as the registry, keep the following in mind:

 

Required privileges

The user that is running the WAS process should have enough operating system privilege to call the Windows systems API for authenticating and obtaining user and group information from the Windows operating system. This is the user who logs into the machine or if running as a service this is the Log On As user. Depending on the machine (whether the machine is a stand-alone machine or a machine that is part of a domain or is the domain controller, itself), the access requirements vary.

For a stand-alone machine, the user should be:

  1. A member of the administrative group.
  2. Should have the Act as part of the operating system privilege.
  3. Should have the Log on as a service privilege, if the server is run as a service.

For a machine that is a member of a domain, only a domain user can start the server process and should be:

  • A member of the domain administrative groups in the domain controller.
  • Should have the Act as part of the operating system privilege in the Domain Security Policy on the domain controller.
  • Should have the Act as part of the operating system privilege in the Local Security Policy on the local machine.
  • Should have the Log on as a service privilege on the local machine, if the server is run as a service.

    Note that user is a domain user and not a local user, which implies that when a machine is part of a domain, only a domain user can start the server.

    For a Domain Controller machine, the user should be:

    1. A member of the domain administrative groups in the domain controller.

    2. Should have the Act as part of the operating system privilege in the Domain Security Policy on the domain controller.

    3. Should have the Log on as a service privilege on the domain controller, if the server is run as a service.

To give a user the Act as part of the operating system or Log on as a service on Windows 2000:

  1. Click Start > Set > Control Panel > Admininstrative Tools > Local Security Policy > Local Policies > User Rights Assignments > Act as part of the operating system (or Log on as a service) .

  2. Add the user name using the Add button.

  3. Restart the machine.

    Note: For a Windows 2000 Domain Controller replace Local Security Policy with Domain Security Policy in the previous step.

    Note: In all of the previous configurations, the server can be run as a service using the LocalSystem for the Log On As entry. LocalSystem has the required privileges and there is no need to give any user special privilege. However, because the LocalSystem has special privileges, make sure it is appropriate to use it in your environment.

If the user running the server does not have the required privilege you may see one of the following exception messages in the log files:

  • A required privilege is not held by the client.
  • Access is denied.

 

Domain and local registries

When WebSphere Application Server is started, the security run time initialization process dynamically attempts to determine if the local machine is a member of a Windows domain. If the machine is part of a domain then by default both the local registry users or groups and the domain registry users or groups can be used for authentication and authorization purposes with the domain registry taking precendence. The list of users and groups presented during the security role mapping would then include users and groups from both the local user registry and the domain user registry. The users and groups can be distinguished by the host names associated with them.

WebSphere Application Server does not support trusted domains.

If the machine is not a member of a Windows system domain, the user registry local to that machine is used.

Using both the domain registry and the local registry. As previously mentioned, when the machine hosting the WebSphere Application Server process is a member of a domain, both the local and the domain registries are used by default. The following section describes more on this topic and recommends some best practices to avoid undesirable consequences.

  • Best Practices

    In general, if the local and the domain registries do not contain common users or groups, it is simpler to administer and it eliminates undesirable side effects. So if possible, it is recommended that users and groups given access to security roles (including the server ID and administrative roles) be unique. In other words, they do not exist in both the local registry and the domain registry. In this situation, select the users and groups from either the local registry or the domain registry to map to the roles.

    In cases where the same user(s) or group(s) exist in both the local registry and the domain registry, it is recommended that at least the server ID and the users and groups who are mapped to the administrative roles be unique in the registries (exist only on the domain).

    If a common set of users exists, set a different password to make sure that the appropriate user is authenticated.

  • How it works

    When a machine is part of a domain, the domain user registry takes precedence over the local user registry. For example, when a user logs into the system, the domain registry tries to authenticate the user first. If the authentication fails the local registry will be used. Also, when a user or a group is mapped to a role, the user/group information is first obtained from the domain registry. In case of failure the local registry will be tried. However, when a fully qualified user or a group name (one that has a domain or host name attached to it) is mapped to a role, then only that registry is used to get the information. Use the administrative console or scripts to get the fully qualified user and group names and is the recommended way to map users and groups to roles.

    Note that a user Bob on one machine (the local registry, for example) is not the same as the user Bob on another machine (say the domain registry) because the uniqueID of Bob (the security identifier [SID], in this case) is different in different registries.

  • Examples

    Let's say the machine MyMachine is part of the domain MyDomain . MyMachine contains the following users and groups:

    • MyMachine\user2

    • MyMachine\user3

    • MyMachine\group2

    MyDomain contains the following users and groups:

    • MyDomain\user1

    • MyDomain\user2

    • MyDomain\group1

    • MyDomain\group2

    Here are some scenarios assuming the above set of users and groups.

    1. When user2 logs into the system, the domain registry is used for authentication. If the authentication fails (the password is different) the local registry is used.

    2. If the user MyMachine\user2 are mapped to a role, only the user2 in MyMachine can access it. So if the user2 password is same on both the local and the domain registries, user2 cannot access the resource, since user2 is always authenticated using the domain registry. Hence, if both registries have common users, it is recommended that the password be different.

    3. If the group2 is mapped to a role (using the Application Assembly Tool, for example), only the users who are members of the MyDomain\group2 can access the resource since group2 information is first obtained from the domain registry.

    4. If the group MyMachine\group2 is mapped to a role, only the users who are members of the MyMachine\group2 can access the resource. This is because a specific group is mapped to the role ( MyMachine\group2 instead of just group2 ).

    5. Use either user3 or MyMachine\user3 to map to a role, since user3 is unique; it exists in only one registry.

    Authorizing with the domain user registry first can cause problems if a user exists in both the domain and local user registries with the same password. Role-based authorization can fail in this situation because the user is first authenticated within the domain user registry. This authentication produces a unique domain security ID that is used in WebSphere Application Server during the authorization check. However, the local user registry is used for role assignment. The domain security ID does not match the unique security ID associated with the role. To avoid this problem, map security roles to domain users instead of local users.

    In a Network Deployment environment, only a centralized repository can be used if more than one node is involved. This implies that only the domain registry can be used, which is because the user and group uniqueIDs (SIDs) differ on different nodes, as previously mentioned.

Using either the local or the domain registry. If you want to access users and groups from either the local registry or the domain registry, instead of both, set the property com.ibm.websphere.registry.UseRegistry . This can be set to either local or domain. When this property is set to local (case insensitive) only the local registry is used. When this property is set to domain (case insensitive) only the domain registry is used. This property should be set by using the Custom Properties link in the Security > User Registries > Local OS panel in the administrative console or by using scripts.

Note: When the property is set, the privilege requirement for the user who is running the product process does not change. For example, if this property is set to local, the user running the process requires the same privilege, as if the property were not set.

 

Using UNIX system registries

When using UNIX system registries, the process ID that runs the WebSphere Application Server process should have the root authority to call the local operating system APIs for authentication and obtaining user or group information.

Note: In UNIX systems, only the local machine registry is used. NIS (Yellow Pages) is not supported.

 

Using Linux and Solaris system registries

For WebSphere Application Server Local OS security registry to work on the Linux and Solaris platforms, a shadow password file must exist. The shadow password file is named shadow and is located in the /etc directory. If the shadow password file does not exist, an error occurs after enabling global security and configuring the user registry as Local OS.

To create the shadow file, run the pwconv command (with no parameters). This command creates an /etc/shadow file from the /etc/passwd file. After creating the shadow file, you can enable local operating system security successfully.

 

Remote registries

By default, the registry is local to all the product processes. The performance is higher, (no need for remote calls) and it also increases availability. Any process failing will not effect other processes. When using LocalOS as the registry, every product process must run with privilege access ( root in UNIX, Act as part of operating system in Windows systems). If this is not practical in some situations, you can use a remote registry from the node (or in very rare situations from the cell). Using a remote registry affects performance and creates a single point of failure. Use remote registries only in rare situations.

The node and the cell processes are meant for manipulating configuration information and using them to host the registry for all the appservers creates traffic and can cause problems. It is highly recommended that remote registries be used only when a very limited number of application servers exist in a Network Deployment environment. Using a node agent (instead of the cell) to host the remote registry is preferable, since the cell process is not designed to be highly available. Also, using a node to host the remote registry indicates that only the application servers in that node are using it. Since the Node Agent does not contain any application code giving it the privilege access required should not be a concern.

One can set up a remote registry by setting the property WAS_UseRemoteRegistry in the Global Security panel using the Custom Properties link at the bottom of the administrative console panel. The value should be either Cell or Node (case insensitive). If the value is Cell, the cell registry is used by all the product processes including the Node Agent and all the appservers. If the cell process is down for any reason, restart all the processes after the cell is restarted. If the node agent registry needs to be used for the remote registry, set the value, WAS_UseRemoteRegistry , to node. In this case, all the application server processes use the node agent registry. In this case, if the node agent fails and does not start automatically, then depending on that node agent, you might need to restart all the application servers, once the node agent is started.

Custom user registries

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.