Example: UserRegistry.java file
// 5639-D57, 5630-A36, 5630-A37, 5724-D18 // (C) COPYRIGHT International Business Machines Corp. 1997, 2002 // All Rights Reserved * Licensed Materials - Property of IBM // // DESCRIPTION: // // This is the UserRegistry interface that Custom Registries in WebSphere // should 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 WebSphere Security to use Custom * Registries. This should extend java.rmi.Remote as 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 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". * @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 administrative console and wsadmin to * make available the users in the registry for adding them (users) to roles. * * @param pattern the pattern to match. (For e.g., a* will match all * userSecurityNames starting with a) * @param 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 may be called only when the user information is displayed * (i.e information purposes only, for example, in GUI) and hence 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 4.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 5.0 for the same methods the security name will be returned by * default. This is the recommended way as the display name is not unique * and might create security holes. * However, for backward compatability if one needs the display name to * be returned set the property WAS_UseDisplayName to true. * * See the Infocenter documentation for more information. * * @param 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 UniqueId for a userSecurityName. This method is called when * creating a credential for a user. * * @param userSecurityName the name of the user. * @return the UniqueId of the user. The UniqueId for an 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 UniqueId 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 uniqueId. * * @param uniqueUserId the UniqueId 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 * * @param 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 registy. * The maximum number of groups returned is defined by the limit * argument. * This method is called by GUI(adminConsole) and Scripting(Command Line) to * make available the groups in the registry for adding them (groups) to * roles. * * @param pattern the pattern to match. (For e.g., a* will match all * groupSecurityNames starting with a) * @param limit the maximum number of groups that should be returned. * 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 is displayed * (for example, GUI) and hence not used in the actual authentication or * authorization purposes. If there are no display names in the registry * return null or empty string. * * @param 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. * @param 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 could * 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 UniqueId of * a user. * Called during creation of a user's credential. * * @param uniqueUserId the uniqueId of the user. * @return a List of all the group UniqueIds that the uniqueUserId * 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 uniqueUserId 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 uniqueId. * * @param uniqueGroupId the UniqueId 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 * * @param 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 GUI(adminConsole) 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 check can be made on the groups that the role contains. * * @param 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 Application Server Enterprise * Process Choreographer (Enterprise Edition) when staff assignments are * modeled using groups. * * In rare situations if you are working with a registry where getting all * the users from any of your groups is not practical (for example if there * are a large number of users) you can throw the NotImplementedException * for that particualar group or groups. Make sure that if the WebSphere * Application Server Choreographer is installed (or if installed later) * the staff assignments are not modeled using these particular groups. * If there is no concern about returning the users from groups in the * registry it is recommended that this method be implemented without * throwing the NotImplemented exception. * * @param groupSecurityName the name of the group * @param limit the maximum number of users that should be returned. * * This is, however, used by some * of the WAS clients like Workflow. * * If you are working with a registry where getting all the users from * any of your groups is not practical (for example if there are a large * number of users) you can through the NotImplementedException. Also, * if you implement this method, you can still throw this exception if * the limit exceeds some practical value. * When the NotImplementedException is thrown the client program should fall * back to some default implementation which should be documented by the * client. * * @param groupSecurityName the name of the group * @param limit the maximum number of users that should be returned. * This is very useful in situations where there are lot 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. * @deprecated This method will be deprecated in future. * @exception NotImplementedException throw this exception if it is not * practical to get this information from your registry. * @exception EntryNotFoundException if the group does not exist in * the registry * @exception CustomRegistryException if there is any registry specific * problem * @exception RemoteException as this extends java.rmi.Remote * **/ public Result getUsersForGroup(String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException; /** * This method is implemented internally by the WebSphere code in Version 5. * This method is not called for the custom registry implementations * for this release. Return null in the implementation. * * Note that since this method is not called one 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; }