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 java.lang.String, java.lang.String)">checkPassword(java.lang.String userSecurityName, java.lang.String password)
Checks the password of the user.
 WSCredential java.lang.String)">createCredential(java.lang.String userSecurityName)
Throw the NotImplementedException for this method.
 java.lang.String java.lang.String)">getGroupDisplayName(java.lang.String groupSecurityName)
Returns the display name for the group specified by groupSecurityName.
 Result java.lang.String, int)">getGroups(java.lang.String pattern, int limit)
Gets a list of groups that match a pattern in the registy.
 java.lang.String java.lang.String)">getGroupSecurityName(java.lang.String uniqueGroupId)
Returns the name for a group given its uniqueId.
 java.util.List java.lang.String)">getGroupsForUser(java.lang.String userSecurityName)
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.
 java.lang.String getRealm()
Returns the realm of the registry.
 java.lang.String java.lang.String)">getUniqueGroupId(java.lang.String groupSecurityName)
Returns the Unique id for a group.
 java.util.List java.lang.String)">getUniqueGroupIds(java.lang.String uniqueUserId)
Returns the Unique ids for all the groups that contain the UniqueId of a user.
 java.lang.String java.lang.String)">getUniqueUserId(java.lang.String userSecurityName)
Returns the UniqueId for a userSecurityName.
 java.lang.String java.lang.String)">getUserDisplayName(java.lang.String userSecurityName)
Returns the display name for the user specified by userSecurityName.
 Result java.lang.String, int)">getUsers(java.lang.String pattern, int limit)
Gets a list of users that match a pattern in the registy.
 java.lang.String java.lang.String)">getUserSecurityName(java.lang.String uniqueUserId)
Returns the name for a user given its uniqueId.
 Result java.lang.String, int)">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 java.lang.String)">isValidGroup(java.lang.String groupSecurityName)
Determines if the groupSecurityName exists in the registry
 boolean java.lang.String)">isValidUser(java.lang.String userSecurityName)
Determines if the userSecurityName exists in the registry
 java.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

java.lang.String, java.lang.String)">

 

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

 

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 objec 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

java.lang.String, int)">

 

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 no 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

java.lang.String)">

 

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, no 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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String, int)">

 

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 no 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

java.lang.String)">

 

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, no 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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String)">

 

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

java.lang.String, int)">

 

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 not used by WebSphere Application Server (WAS) for authenticating or authorization purposes. 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.

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 no 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 if it is no pratical to get this information from your 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

java.lang.String)">

 

createCredential

public WSCredential 
createCredential
(java.lang.String userSecurityName)
                              throws NotImplementedException,
                                     EntryNotFoundException,
                                     CustomRegistryException,
                                     java.rmi.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.

Throws:

NotImplementedException - Always throw this.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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.