Local operating system registries

With the registry implementation for the local operating system, the WebSphere® Application Server authentication mechanism can use the user accounts database of the local operating system.

Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

[IBM i] If you want to use the local operating system registry to represent the principals who access your WebSphere Application Server resources, you do not have to complete any special user registry setup steps. The local operating system registry is used for authentication and authorization of users who access WebSphere Application Server resources, but not for WebSphere Application Server users who access operating system resources. WebSphere Application Server does not run under the operating system user profile of Application Server users. Instead, WebSphere Application Server runs under the operating system profile that is configured by the Application Server administrator.

[IBM i] If you want to authorize a user for any WebSphere Application Server resource, a user profile for that user must exist in the operating system. Use the Create User Profile (CRTUSRPRF) command to create new user IDs that can be used by WebSphere Application Server

[AIX Solaris HP-UX Linux Windows] Lightweight Directory Access Protocol (LDAP) is a centralized registry. Most local operating system registries are not centralized registries.

[AIX Solaris HP-UX Linux Windows] WebSphere Application Server provides implementations for the Windows 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.

Note: For an Active Directory (domain controller), the three group scopes are Domain Local Group, Global Group, and Universal Group. For an Active Directory (Domain Controller), the two group types are Security and Distribution.

When a group is created, the default value is Global and the default type is Security. With Windows NT domain registry support for Windows 2003 domain controllers, WebSphere Application Server only supports Global groups that are the Security type. It is recommended that you use the Active Directory registry support rather than a Windows NT domain registry if you use Windows 2003 domain controllers because the Active Directory supports all group scopes and types. The Active Directory also supports a nested group that is not support by Windows NT domain registry. The Active Directory is a centralized control registry.

Note: WebSphere Application Server does not have to install the member of the domain because it can be installed on any machine on any platform. Note that the Windows NT domain native call returns the support group only without an error.

[AIX Solaris HP-UX Linux Windows] [IBM i] Do not use a local operating system registry in a WebSphere Application Server environment where application servers are dispersed across more than one machine because each machine has its own user registry.

[AIX Solaris HP-UX Linux Windows] The Windows domain registry and Network Information Services (NIS) are exceptions. Both the Windows domain registry and Network Information Services (NIS) are centralized registries. The Windows domain registry is supported by WebSphere Application Server; however, NIS is not supported.

[AIX Solaris HP-UX Linux Windows] [IBM i] As mentioned previously, the access IDs taken from the user registry are used during authorization checks. Because these IDs are typically unique identifiers, they vary from machine to machine, even if the exact users and passwords exist on each machine.

[AIX Solaris HP-UX Linux Windows] [IBM i] 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.

[AIX Solaris HP-UX Linux Windows] [IBM i] Even though Java client certificates function correctly, the following error displays in the SystemOut.log file:

CWSCJ0337E: 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.

[z/OS] A local operating system registry is a centralized registry within a sysplex.

[z/OS] WebSphere Application Server uses the System Authorization Facility (SAF) interfaces. SAF interfaces are defined by MVS™ to enable applications to use system authorization services or registries to control access to resources such as data sets and MVS commands. SAF allows security authorization requests to be processed directly through the Resource Access Control Facility (RACF®) or a third party z/OS security provider. You must provide a mapping from a user registry identity to a SAF user ID unless you select local operating system as the user registry. For more information, see Custom System Authorization Facility mapping modules.

[z/OS] Web client certificate authentication is supported when using the local operating system user registry. Digital certificates can be mapped to MVS identities by both web and Java clients when you select Local OS. A certificate name filter can be used to simplify the mapping. If you are using RACF as the security server, the RACDCERT MAP command creates a resource profile that maps multiple user identities to a digital certificate to simplify administration of certificates, conserve storage space in the RACF database, maintain accountability, or maintain access control granularity.

Required privileges

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

For a stand-alone machine, the user:
- Is a member of the administrative group.
- Has the Act as part of the operating system privilege.
- Has 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:
- Is a member of the domain administrative groups in the domain controller.
- Has the Act as part of the operating system privilege in the Local security policy on the local machine.
- Has the Log on as a service privilege on the local machine, if the server is run as a service.
  The 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:
- Is a member of the domain administrative groups in the domain controller.
- Has the Log on as a service privilege on the domain controller, if the server is run as a service.

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

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

Avoid trouble: The application server must be started with Administrator privileges if you are using a command prompt. Start the application server from a command prompt window that is launched by performing the following actions:

Right-click a command prompt shortcut.
Click Run As Administrator.
When you open the command prompt window as Administrator, an operating-system dialog appears that asks you if you want to continue. Click Continue to proceed.

Domain and local user 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 precedence. The list of users and groups that is presented during the security role mapping includes users and groups from both the local user registry and the domain user registry. The users and groups can be distinguished by the associated host names.

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 user registry and the local operating system registry

When the machine that hosts the WebSphere Application Server process is a member of a domain, both the local and the domain user registries are used by default. The following section describes more on this topic and recommends some best practices to avoid unfavorable consequences.

Note: Although this section does not directly describe z/OS considerations, you should be aware that overall security operations are affected by how well you set up these registries.

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 unfavorable side effects. If possible, give users and groups access to unique security roles, including the server ID and administrative roles. In this situation, select the users and groups from either the local user registry or the domain user registry to map to the roles.
- In cases where the same users or groups exist in both the local user registry and the domain user registry, it is recommended that at least the server ID and the users and groups that are mapped to the administrative roles be unique in the registries and exist only in 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 user registry tries to authenticate the user first. If authentication fails, the local user registry is used. When a user or a group is mapped to a role, the user and group information is first obtained from the domain user registry. In case of failure, the local user registry is tried.
- However, when a fully qualified user or a group name, one with an attached domain or host name, is mapped to a role, only that user registry is used to get the information. Use the administrative console or scripts to get the fully qualified user and group names, which is the recommended way to map users and groups to roles.
  Tip: A user, Bob, on one machine in the local OS user registry, for example, is not the same as the user Bob on another machine in the domain user registry, for example, because the unique ID of Bob, which is the security identifier [SID] in this case, is different in different user registries.
Examples
The MyMachine machine is part of the MyDomain domain. The MyMachine machine contains the following users and groups:
- MyMachine\user2
- MyMachine\user3
- MyMachine\group2
The MyDomain domain contains the following users and groups:
- MyDomain\user1
- MyDomain\user2
- MyDomain\group1
- MyDomain\group2
Here are some scenarios that assume the previous set of users and groups:
1. When user2 logs into the system, the domain user registry is used for authentication. If the authentication fails because the password is different, for example, the local user registry is used.
2. If the MyMachine\user2 user is mapped to a role, only the user2 user in MyMachine machine has access. Thus, if the user2 password is the same on both the local and the domain user registries, the user2 user cannot access the resource because the user2 user is always authenticated using the domain user registry. If both user registries have common users, it is recommended that you have different passwords.
3. If the group2 group is mapped to a role, only the users who are members of the MyDomain\group2 group can access the resource because group2 information is first obtained from the domain user registry.
4. If the MyMachine\group2 group is mapped to a role, only the users who are members of the MyMachine\group2 group can access the resource. A specific group is mapped to the role (MyMachine\group2 instead of just group2).
5. Use either the user3 user or the MyMachine\user3 user to map to a role because the user3 user is unique as it exists in one user registry only.
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 that is associated with the role. To avoid this problem, map security roles to domain users instead of local users.

Only a centralized repository can be used if more than one node is involved. This usage implies that only the domain user registry can be used because the user and group unique IDs (SIDs) differ on various nodes, as previously mentioned.

Avoid trouble: Prior to this fix pack, the local operating system user registry on UNIX systems might not find group names if the registry contains a large number of groups. This problem arises from a memory limitation and typically occurs when the registry contains several hundred groups. Starting with this fix pack, the buffer size can accommodate a larger number of groups.

Using either the local or the domain user registry

If you want to access users and groups from either the local or the domain user registry, instead of both, set the com.ibm.websphere.registry.UseRegistry property. This property can be set to either local or domain. When this property is set to local (case insensitive) only the local user registry is used. When this property is set to domain, (case insensitive) only the domain user registry is used.

Set this property by completing the following steps to access the Custom Properties panel in the administrative console:

Click Security > Global security
Under User account repository, click the Available realm definitions drop-down list, select Local operating system, and click Configure.
Under Additional properties, click Custom properties.

You can also use wsadmin to configure this property. 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 that is running the process requires the same privilege, as if the property was not set.

Using system user registries

The following notes apply when you use system user registries:

When using system user registries, the process ID that runs the WebSphere Application Server process needs the root authority to call the local operating system APIs for authentication and for obtaining user or group information.
Only the local machine user registry is used. Network Information Service (NIS) (Yellow Pages) is not supported.
If you are using the local operating system user registry, HP-UX must be configured in untrusted mode. Trusted mode is not supported if using the local operating system user registry.
For WebSphere Application Server local operating system 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 administrative security and configuring the registry as local operating system.

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.