IdAS Change Password

Requirements

As described in bug 193223, we need a way to do the following:

1. Set a password for the first time
2. Reset an existing password
3. Specify an old password value when resetting
4. Cause the CP/backing store to generate and return a set/reset password

Proposal 1 (New API)

This was discussed on the Higgins Dev list at [1] [2] [3]

The resulting method looks like this:

/**
  * Adds or changes authentication materials.
  * @param oldMaterials May be null. Specifies the existing authentication materials
  *       which are being modified.
  *       The way in which this matches a known authentication identity and associated 
  *       materials is specified by the definition of the authentication materials object
  *       (that specification includes instructions as to which data in the materials are
  *       required to be present and which are not).
  *       When null, this operation is to be treated as a request to "add authentication materials".
  *       That is, the value of newMaterials will be used to create a new authentication
  *       identity and its associated materials.
  * @param newMaterials May be null. Specifies the value of the new authetication materials.  
  *       When null, oldMaterials must be specified, and this operation is treated as a request
  *       to "generate authentication materials"
  * @return May be null. When newMaterials is null, a generated authentication materials object
  *       is returned.  Otherwise the return value is null.
  * @throws IdASException
  */
public Object updateAuthNMaterials(Object oldMaterials, Object newMaterials) throws IdASException;

Consensus (follow the dev list thread) seemed to point to Proposal 2

Proposal 2 (Use existing APIs)

Treat authentication materials as attributes for purposes of management. This brings up the following issues:

1. Attribute types. How does an IdAS consumer know what attribute(s) to manage?
   1. One path is via standardization: Do we begin to propose some standardized attributes for this? For example, if someone wants to update their password, what attribute(s) do they update?
   2. Another path is discovery.
2. Design support for specialized behaviors: How do we do the things listed as sub-issues below? One suggestion is via controls (which are not yet designed). We also need to decide how to indicate different types of failures to the caller (the modification to userPassword didn't work because the CP requires the old password's value). Also, we need to decide whether to build in support (and if so, how) for feature discovery.
   1. When updating the <userPassword> attribute, we need to allow a way to specify the old password
   2. We need to allow a way for the caller to reset the password to an auto-generated value
3. We need to allow the caller to update attributes which are (for whatever reason) not returned. For example, some contexts will not return a "userPassword" attribute, but may allow that attribute to be written to.

Solutions to issues

Issue #1

This was suggested in [4]: One idea for making the updatable attribute types consistent and discoverable is that we could define/advertise them in the related authN materials used for open. Let's say we add a method to IAuthNAttributesMaterials called getManagementAttributes(); This returns the URI(s) of the attributes which are used to update the authn materials which correspond to the instance of IAuthNAttributesMaterials being used. For example, AuthNNamePasswordMaterials.getManagementAttributes() could return the URI for "http://www.eclipse.org/higgins/ontologies/2006/higgins#userPassword"

Issue #2

Begs for API Extensibility. See this bug. The current proposals there are:

1. add 1 param to every IdAS method: list of tuples{type-string/URI/etc, object}
2. using callbacks to get additional capabilities (may be issues related to multi-threading)
3. create one method per class. Something like

/**
 * @param method identifies the intended method to be called (such as the Method for IDigitalSubject.addAttribute)
 * @param methodArgs the arguments for method
 * @param extended args the additional arguments to be sent to the method
 */
public Object extendedOperation (Method method, Object[] methodArgs, Args[] extendedArgs);

I currently prefer the #3 option, as it doesn't require any bloat to existing methods, and can be used in a multi-threaded env.

Issue #2.1

Once we have API extensibility, This would be solved by defining the extended operation or control that would allow the old value to be passed in.

Issue #2.2

Solve the API Extensibility issue, then define the extensions needed to do this

Issue #3

This was suggested in [5]: Bug 193226 talks about this. I'm partial to solving this using the (1) proposal in that bug. This allows applications to continue their current behavior. I think this should only be allowed to happen on the IDigitalSubject.getAttribute() call, not on IDigitalSubject.getAttributes() call. The documented behavior would read something like: "When an attribute is returned and zero values exist in that attribute, this indicates that the caller may be able to populate values of that attribute. Where this may happen include the case where the caller has no read access for the values of the attribute, but is allowed to add values. Note that by returning an attribute with zero values does not indicate that such an attribute already exists on the subject, nor does it indicate that the attribute does not already exist. No determination can be made regarding the current state of the attribute. This prevents unwanted knowledge to be gained regarding the existence or non-existence of the attribute."