The following file is a custom property that is used with a custom user registry.
For more information, see Configuring custom user 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 WebSphere Application Server 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 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 WebSphere Application Server Version 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 WebSphere Application Server Version 5.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 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 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 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 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 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 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 WebSphere Application Server
* 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;
}
Related tasks
Configuring custom user registries
Related reference
getRemoteUser and getAuthType methods