UserRegistry.java files

// 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 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". It is recommended 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 administrative 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 WebSphere Application Server V5.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.
   * However, for backward compatibility if one needs the display name to
   * be returned set the property WAS_UseDisplayName to true.
   *
   * 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 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 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 registy. 
   * The maximum number of groups returned is defined by the limit
   * argument.
   * This method is called by the administrative 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 IDd 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 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 administrative 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 if you are working with a registry where getting all of
   * the users from any of your groups is not practical (for example if 
   * a large number of users exist) one can throw the NotImplementedException
   * for that particular groups. Make sure that if the WebSphere Business 
   * Integration Server Foundation Process Choreographer is installed (or 
   * if installed later) that are not modeled using these particular groups. 
   * If no concern exists about the staff assignments returning the users from 
   * groups in the registry it is recommended 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 throw 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 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;
}