Selecting a registry or repository

Information about users and groups reside in a user registry. In WebSphere® Application Server, a user registry authenticates a user and retrieves information about users and groups to perform security-related functions, including authentication and authorization.

Before you begin

Note: During profile creation, either during installation or post-installation, administrative security is enabled by default. The file-based federated user repository is configured as the active user registry. Decide if you want a different user registry.

Before configuring the user registry or repository, decide which user registry or repository to use. You can configure one Active default registry for the Cell.

About this task

WebSphere Application Server provides implementations that support multiple types of registries and repositories including the local operating system registry, a stand-alone Lightweight Directory Access Protocol (LDAP) registry, a stand-alone custom registry, and federated repositories.

With WebSphere Application Server, a user registry or a repository, such as a federated repository, authenticates a user and retrieves information about users and groups to perform security-related functions including authentication and authorization.

With WebSphere Application Server, a user registry or repository is used for:
  • Authenticating a user using basic authentication, identity assertion, or client certificates
  • Retrieving information about users and groups to perform security-related administrative functions, such as mapping users and groups to security roles

[z/OS]WebSphere Application Server is designed with the capability to support multiple operating systems or operating environment-based user registries, such as the z/OS® SAF registry, and most of the major Lightweight Directory Access Protocol (LDAP)-based registries. You can use the custom LDAP feature to support any LDAP server by setting up the correct configuration information, such as user and group filters. However, support is not extended to these custom LDAP servers because there are many possibilities that cannot be tested.

[z/OS]Configuring the correct registry or repository is a prerequisite to assigning users and groups to roles for applications. By default, when a user registry or repository is not configured, the local operating system SAF-based user registry is used. If your choice of user registry or repository is not the local operating system, you must first configure the user registry or repository. Configuring the user registry or repository is normally done as part of enabling administrative security, restarting the servers, and then assigning users and groups to roles for all of your applications.

In addition to local operating system, LDAP, and Federated repository registries, WebSphere Application Server also provides a plug-in to support any registry by using the custom registry feature. The custom registry feature enables you to configure any user registry that is not made available through the security configuration panels of the WebSphere Application Server.

Configuring the correct registry or repository is a prerequisite to assigning users and groups to roles for applications. When a user registry or repository is not configured, the local operating system registry is used by default. If your choice of user registry is not the local operating system registry, you need to first configure the registry or repository, which is normally done as part of enabling security, restart the servers, and then assign users and groups to roles for all your applications.

WebSphere Application Server supports the following types of user registries:
  • Federated repository
  • Local operating system [z/OS]such as SAF-based
    Restriction: Configuring a transparent LDAP server under the local operating system registry and having authentication of users take place through that local operating system using LDAP is unsupported.
  • Standalone Lightweight Directory Access Protocol (LDAP) registry
  • Stand-alone custom registry
The UserRegistry interface is used to implement both the custom registry and the federated repository options for the user account repository. The interface is very helpful in situations where the current user and group information exists in some other formats, for example, a database, and cannot move to local operating system or LDAP registries. In such a case, you can implement the UserRegistry interface so that WebSphere Application Server can use the existing registry for all the security-related operations. The process of implementing a custom registry is a software implementation effort, and it is expected that the implementation does not depend on WebSphere Application Server resource management for its operation. For example, you cannot use an Application Server data source configuration; generally you must invoke database connections and dictate their behavior directly in your code.
Note: WebSphere Application Server has implemented a user registry proxy by using the UserRegistry interface. However, the return values are little different from the interface. For example, getUniqueUserId returns the uniqueID with the realm name wrapped. You cannot use the return value to pass to getUserSecurityName, as shown in the following example:
// Retrieves the default InitialContext for this server.
javax.naming.InitialContext ctx = new javax.naming.InitialContext();

// Retrieves the local UserRegistry object.
com.ibm.websphere.security.UserRegistry reg =
         (com.ibm.websphere.security.UserRegistry) ctx.lookup("UserRegistry");

// Retrieves the registry uniqueID based on the userName that is specified
     // in the NameCallback.
String uniqueid = reg.getUniqueUserId(userName);
// Strip the realm name and get real uniqueID
String uid = com.ibm.wsspi.security.token.WSSecurityPropagationHelper.getUserFromUniqueID (uniqueID);

// Retrieves the security name from the user registry based on the uniqueID.
String securityName = reg.getUserSecurityName(uid);
You can use a Service Provider Interface (SPI) for this parsing function.
After the applications are assigned users and groups and you need to change the user registries, delete all the users and groups, including any RunAs role, from the applications, and reassign them after changing the registry through the administrative console or by using wsadmin scripting. The following wsadmin command, which uses Jacl, removes all of the users and groups from any application:
$AdminApp deleteUserAndGroupEntries yourAppName
where yourAppName is the name of the application. Backing up the old application is advised before performing this operation. However, if both of the following conditions are true, you might be able to switch the registries without having to delete the users and groups information:
  • All of the user and group names, including the password for the RunAs role users, in all of the applications match in both user registries.
  • The application bindings file does not contain the access IDs which are unique for each user registry even for the same user or group name.

By default, an application does not contain access IDs in the bindings file. These IDs are generated when the applications start. However, if you migrated an existing application from an earlier release, or if you used the wsadmin script to add access IDs for the applications to improve performance, you have to remove the existing user and group information and add the information after configuring the new user registry.

For more information on updating access IDs, see updateAccess IDs in the Commands for the AdminApp object article.

Attention: WebSphere Application Server supports a variety of user registries and repositories on different operating systems. During the user authentication process, you might use non-alphanumeric characters in your user name or password. Restrictions on the use of these non-alphanumeric characters depends on both the underlying operating system and the user registry type. For more information on which non-alphanumeric characters are not supported, see your operating system and user registry or repository documentation.
[AIX]For example, the following characters are not supported in a user name value:
  • ˋ
  • #
  • =
  • \
  • :
  • "
  • ,
  • /
  • ?
  • '
  • A space character

For a comprehensive list of the non-alphanumeric characters that are not supported, see the IBM AIX operating system documentation.

[HP-UX]For example, the following characters are not supported in a user name value:
  • ˋ
  • :
  • "
  • /
  • A space character

Complete one of the following steps to configure your user registry:

Procedure

What to do next

  1. If you are enabling security, make sure that you complete the remaining steps. Verify that the User account repository on the Global security panel is set to the appropriate registry or repository. As the final step, validate the user ID and the password by clicking Apply on the Global security panel. Save, stop and start all WebSphere Application Servers.
  2. For any changes in user registry panels to be effective, you must validate the changes by clicking Apply on the Global security panel. After validation, save the configuration and stop and start all WebSphere Application Servers, including the cells, nodes and all of the application servers. To avoid inconsistencies between the WebSphere Application Server processes, make sure that any changes to the registry or repository are done when all of the processes are running. If any of the processes are down, force synchronization to make sure that the process can start later.

    If the server or servers start without any problems, the setup is correct.

  3. [z/OS]If System Authorization Facility (SAF) through local operating system is selected as the registry or repository, the values in the bindings file are ignored with the exception of the user ID and password (or password phrase) for RunAs role users.