com.ibm.websphere.security
Interface UserRegistry
- All Superinterfaces:
- java.rmi.Remote
- public interface UserRegistry
- extends java.rmi.Remote
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)
Method Summary java.lang.String checkPassword(java.lang.String userSecurityName, java.lang.String password)
Checks the password of the user.WSCredential createCredential(java.lang.String userSecurityName)
This method is implemented internally by the WebSphere code in this release.java.lang.String getGroupDisplayName(java.lang.String groupSecurityName)
Returns the display name for the group specified by groupSecurityName.Result getGroups(java.lang.String pattern, int limit)
Gets a list of groups that match a pattern in the registy.java.lang.String getGroupSecurityName(java.lang.String uniqueGroupId)
Returns the name for a group given its uniqueId.java.util.List getGroupsForUser(java.lang.String userSecurityName)
Returns the securityNames of all the groups that contain the userjava.lang.String getRealm()
Returns the realm of the registry.java.lang.String getUniqueGroupId(java.lang.String groupSecurityName)
Returns the Unique id for a group.java.util.List getUniqueGroupIds(java.lang.String uniqueUserId)
Returns the Unique ids for all the groups that contain the UniqueId of a user.java.lang.String getUniqueUserId(java.lang.String userSecurityName)
Returns the UniqueId for a userSecurityName.java.lang.String getUserDisplayName(java.lang.String userSecurityName)
Returns the display name for the user specified by userSecurityName.Result getUsers(java.lang.String pattern, int limit)
Gets a list of users that match a pattern in the registy.java.lang.String getUserSecurityName(java.lang.String uniqueUserId)
Returns the name for a user given its uniqueId.Result getUsersForGroup(java.lang.String groupSecurityName, int limit)
Deprecated. This method will be deprecated in future.void initialize(java.util.Properties props)
Initializes the registry.boolean isValidGroup(java.lang.String groupSecurityName)
Determines if the groupSecurityName exists in the registryboolean isValidUser(java.lang.String userSecurityName)
Determines if the userSecurityName exists in the registryjava.lang.String mapCertificate(java.security.cert.X509Certificate[] cert)
Maps a Certificate (of X509 format) to a valid user in the Registry.
Method Detail initialize
public void initialize(java.util.Properties props) throws CustomRegistryException, java.rmi.RemoteException
- Initializes the registry. This method is called when creating the registry.
- Parameters:
- props - the registry-specific properties with which to initialize the custom registry
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
checkPassword
public java.lang.String checkPassword(java.lang.String userSecurityName, java.lang.String password) throws PasswordCheckFailedException, CustomRegistryException, java.rmi.RemoteException
- Checks the password of the user. This method is called to authenticate a user when the user's name and password are given.
- Parameters:
- userSecurityName - the name of user
- password - the password of the user
- Returns:
- 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
- Throws:
- CheckPasswordFailedException - if userSecurityName/ password combination does not exist in the registry
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
- PasswordCheckFailedException
mapCertificate
public java.lang.String mapCertificate(java.security.cert.X509Certificate[] cert) throws CertificateMapNotSupportedException, CertificateMapFailedException, CustomRegistryException, java.rmi.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
- Parameters:
- cert - the X509 certificate chain
- Returns:
- the mapped name of the user userSecurityName
- Throws:
- CertificateMapNotSupportedException - if the particular certificate is not supported.
- CertificateMapFailedException - if the mapping of the certificate fails.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getRealm
public java.lang.String getRealm() throws CustomRegistryException, java.rmi.RemoteException
- Returns the realm of the registry.
- Returns:
- 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".
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUsers
public Result getUsers(java.lang.String pattern, int limit) throws CustomRegistryException, java.rmi.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.
- Parameters:
- pattern - the pattern to match. (For e.g., a* will match all userSecurityNames starting with a)
- 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.
- Returns:
- a Result object that contains the list of users requested and a flag to indicate if more users exist.
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUserDisplayName
public java.lang.String getUserDisplayName(java.lang.String userSecurityName) throws EntryNotFoundException, CustomRegistryException, java.rmi.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.
- Parameters:
- userSecurityName - the name of the user.
- Returns:
- 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.
- Throws:
- EntryNotFoundException - if userSecurityName does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUniqueUserId
public java.lang.String getUniqueUserId(java.lang.String userSecurityName) throws EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Returns the UniqueId for a userSecurityName. This method is called when creating a credential for a user.
- Parameters:
- userSecurityName - the name of the user.
- Returns:
- 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.
- Throws:
- EntryNotFoundException - if userSecurityName does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUserSecurityName
public java.lang.String getUserSecurityName(java.lang.String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Returns the name for a user given its uniqueId.
- Parameters:
- uniqueUserId - the UniqueId of the user.
- Returns:
- the userSecurityName of the user.
- Throws:
- EntryNotFoundException - if the uniqueUserId does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
isValidUser
public boolean isValidUser(java.lang.String userSecurityName) throws CustomRegistryException, java.rmi.RemoteException
- Determines if the userSecurityName exists in the registry
- Parameters:
- userSecurityName - the name of the user
- Returns:
- true if the user is valid. false otherwise
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getGroups
public Result getGroups(java.lang.String pattern, int limit) throws CustomRegistryException, java.rmi.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.
- Parameters:
- pattern - the pattern to match. (For e.g., a* will match all groupSecurityNames starting with a)
- 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.
- Returns:
- a Result object that contains the list of groups requested and a flag to indicate if more groups exist.
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getGroupDisplayName
public java.lang.String getGroupDisplayName(java.lang.String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, java.rmi.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.
- Parameters:
- groupSecurityName - the name of the group.
- Returns:
- 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.
- Throws:
- EntryNotFoundException - if groupSecurityName does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUniqueGroupId
public java.lang.String getUniqueGroupId(java.lang.String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Returns the Unique id for a group.
- Parameters:
- groupSecurityName - the name of the group.
- Returns:
- 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.
- Throws:
- EntryNotFoundException - if groupSecurityName does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUniqueGroupIds
public java.util.List getUniqueGroupIds(java.lang.String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Returns the Unique ids for all the groups that contain the UniqueId of a user.
Called during creation of a user's credential.
- Parameters:
- uniqueUserId - the uniqueId of the user.
- Returns:
- 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.
- Throws:
- EntryNotFoundException - if uniqueUserId does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getGroupSecurityName
public java.lang.String getGroupSecurityName(java.lang.String uniqueGroupId) throws EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Returns the name for a group given its uniqueId.
- Parameters:
- uniqueGroupId - the UniqueId of the group.
- Returns:
- the name of the group.
- Throws:
- EntryNotFoundException - if the uniqueGroupId does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
isValidGroup
public boolean isValidGroup(java.lang.String groupSecurityName) throws CustomRegistryException, java.rmi.RemoteException
- Determines if the groupSecurityName exists in the registry
- Parameters:
- groupSecurityName - the name of the group
- Returns:
- true if the groups exists, false otherwise
- Throws:
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getGroupsForUser
public java.util.List getGroupsForUser(java.lang.String userSecurityName) throws EntryNotFoundException, CustomRegistryException, java.rmi.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.
- Parameters:
- userSecurityName - the name of the user
- Returns:
- a List of all the group securityNames that the user belongs to.
- Throws:
- EntryNotFoundException - if user does not exist.
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
getUsersForGroup
public Result getUsersForGroup(java.lang.String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- Deprecated. This method will be deprecated in future.
- Gets a list of users in a group.
The maximum number of users returned is defined by the limit argument.
This method is being 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(s). Make sure that if the WAS Choreographer in 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.
- Parameters:
- groupSecurityName - the name of the group
- 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.
- Returns:
- a Result object that contains the list of users requested and a flag to indicate if more users exist.
- Throws:
- NotImplementedException - throw this exception in rare situations if it is not pratical to get this information for any of the group(s) from the registry.
- EntryNotFoundException - if the group does not exist in the registry
- CustomRegistryException - if there is any registry specific problem
- java.rmi.RemoteException - as this extends java.rmi.Remote
createCredential
public WSCredential createCredential(java.lang.String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, java.rmi.RemoteException
- This method is implemented internally by the WebSphere code in this release. 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.
- NotImplementedException
- EntryNotFoundException
- CustomRegistryException
- java.rmi.RemoteException
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.
AIX is a trademark of the IBM Corporation in the United States, other countries, or both.