Network Deployment (Distributed operating systems), v8.0 > Reference > Developer detailed usage information
UserRegistry.java files
The following file is a custom property used with a custom user registry.
See Configuring stand-alone custom registries.
// 5639-D57, 5630-A36, 5630-A37, 5724-D18 // (C) COPYRIGHT International Business Machines Corp. 1997, 2005 // All Rights Reserved * Licensed Materials - Property of IBM // // DESCRIPTION: // // This file is the UserRegistry interface that custom registries in WebSphere // Application Server implement to enable WebSphere security to use the custom // registry. // package com.ibm.websphere.security; import java.util.*; import java.rmi.*; import java.security.cert.X509Certificate; import com.ibm.websphere.security.cred.WSCredential; /** * Implementing this interface enables WAS Security * to use custom registries. This interface extends java.rmi.Remote because the * registry can be in a remote process. * * Implementation of this interface must provide implementations for: * * initialize(java.util.Properties) * checkPassword(String,String) * mapCertificate(X509Certificate[]) * getRealm * getUsers(String,int) * getUserDisplayName(String) * getUniqueUserId(String) * getUserSecurityName(String) * isValidUser(String) * getGroups(String,int) * getGroupDisplayName(String) * getUniqueGroupId(String) * getUniqueGroupIds(String) * getGroupSecurityName(String) * isValidGroup(String) * getGroupsForUser(String) * getUsersForGroup(String,int) * createCredential(String) **/ public interface UserRegistry extends java.rmi.Remote { /** * Initializes the registry. This method is called when creating the * registry. * * @param props the registry-specific properties with which to * initialize the custom registry * @exception CustomRegistryException * if there is any registry specific problem * @exception RemoteException * as this extends java.rmi.Remote **/ public void initialize(java.util.Properties props) throws CustomRegistryException, RemoteException; /** * Checks the password of the user. This method is called to authenticate a * user when the user's name and password are given. * * @param userSecurityName the name of the user * @param password the password of the user * @return a valid userSecurityName. Normally this is * the name of same user whose password was checked but if the * implementation wants to return any other valid * userSecurityName in the registry it can do so * @exception CheckPasswordFailedException if userSecurityName/ * password combination does not exist in the registry * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String checkPassword(String userSecurityName, String password) throws PasswordCheckFailedException, CustomRegistryException, RemoteException; /** * Maps a certificate (of X509 format) to a valid user in the registry. * This is used to map the name in the certificate supplied by a browser * to a valid userSecurityName in the registry * * @param cert the X509 certificate chain * @return the mapped name of the user userSecurityName * @exception CertificateMapNotSupportedException if the particular * certificate is not supported. * @exception CertificateMapFailedException if the mapping of the * certificate fails. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String mapCertificate(X509Certificate[] cert) throws CertificateMapNotSupportedException, CertificateMapFailedException, CustomRegistryException, RemoteException; /** * Returns the realm of the registry. * * @return the realm. The realm is a registry-specific string indicating * the realm or domain for which this registry * applies. For example, for OS400 or AIX this would be the * host name of the system whose user registry this object * represents. * If null is returned by this method realm defaults to the * value of "customRealm". IBM recommends that you use * your own value for realm. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getRealm() throws CustomRegistryException, RemoteException; /** * Gets a list of users that match a pattern in the registry. * The maximum number of users returned is defined by the limit * argument. * This method is called by admin console and by scripting (command * line) to make available the users in the registry for adding them (users) * to roles. * * @parameter pattern the pattern to match. (For example., a* will match all * userSecurityNames starting with a) * @parameter limit the maximum number of users that should be returned. * This is very useful in situations where there are thousands of * users in the registry and getting all of them at once is not * practical. A value of 0 implies get all the users and hence * must be used with care. * @return a Result object that contains the list of users * requested and a flag to indicate if more users exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public Result getUsers(String pattern, int limit) throws CustomRegistryException, RemoteException; /** * Returns the display name for the user specified by userSecurityName. * * This method is called only when the user information displays * (information purposes only, for example, in the administrative console) and not used * in the actual authentication or authorization purposes. If there are no * display names in the registry return null or empty string. * * In WAS v4.0 custom registry, if you had a display * name for the user and if it was different from the security name, the display name * was returned for the EJB methods getCallerPrincipal() and the servlet methods * getUserPrincipal() and getRemoteUser(). * In WAS v6.0 for the same methods the security * name is returned by default. This is the recommended way as the display name * is not unique and might create security holes. * * See the documentation for more information. * * @parameter userSecurityName the name of the user. * @return the display name for the user. The display name * is a registry-specific string that represents a descriptive, not * necessarily unique, name for a user. If a display name does * not exist return null or empty string. * @exception EntryNotFoundException if userSecurityName does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getUserDisplayName(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Returns the unique ID for a userSecurityName. This method is called when * creating a credential for a user. * * @parameter userSecurityName the name of the user. * @return the unique ID of the user. The unique ID for a user is * the stringified form of some unique, registry-specific, data * that serves to represent the user. For example, for the UNIX * user registry, the unique ID for a user can be the UID. * @exception EntryNotFoundException if userSecurityName does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getUniqueUserId(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Returns the name for a user given its unique ID. * * @parameter uniqueUserId the unique ID of the user. * @return the userSecurityName of the user. * @exception EntryNotFoundException if the uniqueUserID does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getUserSecurityName(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Determines if the userSecurityName exists in the registry * * @parameter userSecurityName the name of the user * @return true if the user is valid. false otherwise * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public boolean isValidUser(String userSecurityName) throws CustomRegistryException, RemoteException; /** * Gets a list of groups that match a pattern in the registry. * The maximum number of groups returned is defined by the limit * argument. * This method is called by the admin console and scripting * (command line) to make available the groups in the registry for adding * them (groups) to roles. * * @parameter pattern the pattern to match. (For e.g., a* will match all * groupSecurityNames starting with a) * @parameter limit the maximum number of groups to return. * This is very useful in situations where there are thousands of * groups in the registry and getting all of them at once is not * practical. A value of 0 implies get all the groups and hence * must be used with care. * @return a Result object that contains the list of groups * requested and a flag to indicate if more groups exist. * @exception CustomRegistryException if there is any registry-specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public Result getGroups(String pattern, int limit) throws CustomRegistryException, RemoteException; /** * Returns the display name for the group specified by groupSecurityName. * * This method may be called only when the group information displayed * (for example, the administrative console) and not used in the actual * authentication or authorization purposes. If there are no display names * in the registry return null or empty string. * * @parameter groupSecurityName the name of the group. * @return the display name for the group. The display name * is a registry-specific string that represents a descriptive, not * necessarily unique, name for a group. If a display name does * not exist return null or empty string. * @exception EntryNotFoundException if groupSecurityName does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getGroupDisplayName(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Returns the unique ID for a group. * @parameter groupSecurityName the name of the group. * @return the unique ID of the group. The unique ID for * a group is the stringified form of some unique, * registry-specific, data that serves to represent the group. * For example, for the UNIX user registry, the unique ID might * be the GID. * @exception EntryNotFoundException if groupSecurityName does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getUniqueGroupId(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Returns the unique IDs for all the groups that contain the unique ID of * a user. * Called during creation of a user's credential. * * @parameter uniqueUserId the unique ID of the user. * @return a list of all the group unique IDs that the unique user ID * belongs to. The unique ID for an entry is the stringified * form of some unique, registry-specific, data that serves * to represent the entry. For example, for the * UNIX user registry, the unique ID for a group could be the GID * and the unique ID for the user could be the UID. * @exception EntryNotFoundException if unique user ID does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public List getUniqueGroupIds(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Returns the name for a group given its unique ID. * * @parameter uniqueGroupId the unique ID of the group. * @return the name of the group. * @exception EntryNotFoundException if the uniqueGroupId does not exist. * @exception CustomRegistryException if there is any registry-specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public String getGroupSecurityName(String uniqueGroupId) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Determines if the groupSecurityName exists in the registry * * @parameter groupSecurityName the name of the group * @return true if the groups exists, false otherwise * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public boolean isValidGroup(String groupSecurityName) throws CustomRegistryException, RemoteException; /** * Returns the securityNames of all the groups that contain the user * * This method is called by admin console and scripting * (command line) to verify the user entered for RunAsRole mapping belongs * to that role in the roles to user mapping. Initially, the check is done * to see if the role contains the user. If the role does not contain the user * explicitly, this method is called to get the groups that this user * belongs to so that checks are made on the groups that the role contains. * * @parameter userSecurityName the name of the user * @return a List of all the group securityNames that the user * belongs to. * @exception EntryNotFoundException if user does not exist. * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote **/ public List getGroupsForUser(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException; /** * Gets a list of users in a group. * * The maximum number of users returned is defined by the limit * argument. * * This method is used by the WebSphere Business Integration * Server Foundation process choreographer when staff assignments * are modeled using groups. * * In rare situations where you are working with a user registry and it is not * practical to get all of the users from any of your groups (for example if * a large number of users exist) you can create the NotImplementedException * for those particular groups. Make sure that if the WebSphere Business * Integration Server Foundation Process Choreographer is installed (or * if installed later) that the users are not modeled using these particular groups. * If no concern exists about the staff assignments returning the users from * groups in the registry IBM recommends that this method be implemented * without throwing the NotImplemented exception. * * @parameter groupSecurityName that represents the name of the group * @parameter limit the maximum number of users to return. * This option is very useful in situations where lots of * users are in the registry and getting all of them at * once is not practical. A value of 0 means get all of * the users and must be used with care. * @return a Result object that contains the list of users * requested and a flag to indicate if more users exist. * @deprecated This method will be deprecated in the future. * @exception NotImplementedException create this exception in rare situations * if it is not practical to get this information for any of the * groups from the registry. * @exception EntryNotFoundException if the group does not exist in * the registry * @exception CustomRegistryException if any registry-specific * problem occurs * @exception RemoteException as this extends java.rmi.Remote interface **/ public Result getUsersForGroup(String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException; /** * This method is implemented internally by the WAS * code in this release. This method is not called for the custom registry * implementations for this release. Return null in the implementation. * * Note that because this method is not called you can also return the * NotImplementedException as the previous documentation says. * **/ public com.ibm.websphere.security.cred.WSCredential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException; }
Configure stand-alone custom registries
Related
Servlet security methods