IdAS Change Password

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

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

Alt 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"

Alt 2: Rather than adding a method, adopt the notion that the "secret" portion of any authentication materials must be represented by a single attribute (which is complex in cases where the secret portion is made up of multiple parts). This also solves a problem not yet described -- that is, when authentication materials are complex (multi-part) and one is able to have multiple values. In this case, we need a way to associate all related parts. A complex, multi-valued attr is perfect for this.

With this in mind, we only need a single URI (single attribute type) per authentication type for managing the secrets. For now, we could hard-code this type as a well-known constant URI in each authentication type. Later we may find that each CP should be free to define it's own type, and if so, we'll need to define a run-time discovery method. For now, a static URI per authN type is much simpler.

Alt 2 is the current proposal
Work

• Make credential management attribute discoverable in AuthN*Materials 201671
• Change AuthNSelfIssuedMaterials to use a single, multi-valued attr 201671

• • (if time) create a helper class or method for AuthNSelfIssuedMaterials which allows one to get at the hash

Issue #2

Alt 1:

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.

Alt 2: Ignore Issue #2.2 (it's not a hard requirement right now) and solve both Issue #2.1 and Issue#3 by allowing attributes and values to be deleted from a digital subject. This entails adding these two methods to IHasAttributes:

/**
 * Deletes the specified attrID. On one hand, this is a convenience method (in that the caller can
 * call this rather than fetching the attribute using {@link #getAttribute(URI)} and
 * then calling remove on that. More importantly however is that this method allows
 * an attribute to be removed when the caller has permissions to remove, but no permissions
 * to read that attribute.
 * @param attrID identifies the attribute to be removed
 */
public void removeAttribute (URI attrID);

/**
 * Deletes the specified value from the specified attrID. 
 * On one hand, this is a convenience method (in that the caller can
 * call this rather than fetching the attribute using {@link #getAttribute(URI)} and
 * then fetching the appropriate value, and then calling remove on that value.
 * More importantly however is that this method allows
 * an attribute value to be removed when the caller has permissions to remove values,
 * but no permissions to read that attribute or its values.
 * @param attrID identifies the attribute to be removed
 * @param value identifies the attribute value to be removed
 */
public void removeAttributeValue (URI attrID, Object value);

Note that remove AttributeValue could be overloaded to take an IAttribute as well

Alt 2 is the current proposal
Work

• Add methods above 193226
• CP's: implement Alt 2 methods above

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

Alt 1: 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."

Alt 2:

See Alt 2 for Issue #2. This is the current proposal.

Additional Work

• CP's: may have to special-code for the SECRET_URI values in the AuthN*Materials they support.
  • for example, the JNDI/LDAP cp needs to perform different operations depending on backing LDAP server type -- for OpenLDAP, it calls an extended "modifyPassword" operation, for eDirectory, it can simply map the attributes and perform the usual update operations.
  • Points of interest would include places where attributes are modified (added and deleted), and perhaps changes to the model (it should probably return these attributes as being valid on the subject types that allow credential secrets to be modified)