Example: UserRegistry.java file

// 5722-IWE
// (C) COPYRIGHT International Business Machines Corp. 1997, 2003
// 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.
 *
 * To implement this interface, you 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 registy. 
   * The maximum number of users returned is defined by the limit
   * argument.
   * This method is called by GUI(adminConsole) and Scripting(Command Line) 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 servlet methods getUserPrincipal() and  getRemoteUser().
   * In WAS 5.1 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 role 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 not used by WebSphere Application Server - Express for
   * authenticating or authorization purposes. This is, however, used by some
   * of the WebSphere 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
   *            pratical 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;

  /**
   * Throw the NotImplementedException for this method.
   *
   * Create Credential for a user. 
   *
   * This will be implemented internally by WebSphere code and should NOT be 
   * implemented by the Custom Registry implementations. 
   *
   * @exception NotImplementedException Always throw this.
   **/
   public WSCredential createCredential(String userSecurityName)
      throws NotImplementedException,
      EntryNotFoundException,
             CustomRegistryException,
             RemoteException;
}