Password Reset Endpoint

A client application may request that a user's password be reset by sending a Put message (see WS-Transfer: Identity Management Operations for Directory Access Extensions specification) to the Password Reset endpoint of the FIM Service. The message must be secured in compliance with WS-Security. The rm:ResourceReferenceProperty header element of the message must contain the NT4 Domain\username of the user on whose behalf the password is being reset. In order for a user to be eligible for self-service password reset, the Person resource must have both the domain and username attributes populated with data from Active Directory. The best practice way to populate this data is to configure the FIM Synchronization Service to flow the values (see Introduction to Inbound synchronization in the Forefront Identity Manager Technical Reference).

If the message does not incorporate a security token that confirms the identity of the user, then the Password Reset endpoint will respond with an AuthenticationRequired SOAP fault signifying that confirmation of the user's identity is required. The fault will provide the address of a Security Token Service (STS) located in the FIM Service from which the client application may obtain a security token signifying that the user was able to provide satisfactory proof of his or her identity.

The client application can send a request for a security token, created in compliance with the Web Services Trust Language (WS-Trust), to the STS identified by the SOAP fault. The Security Token Service Endpoint of the FIM Service uses WS-Security to secure the message contents.

Password Reset Completion

If the user successfully confirms his or her identity by responding to all of the STS's challenges, then the STS will yield a response to a request for a security token that incorporates a security token. The structure of the response and the properties of the security token are defined in Security Token Service Endpoint.

The client can now attach the security token it obtained from the STS to a request to the Password Reset endpoint to reset the user's password. Handling of that request will continue according to the specification of the message-specific authentication protocol defined in Message-Specific Authentication.

If the request is found to be in order, then the service will try to update the user's password in Microsoft Active Directory by way of the FIM Password Change Notification Service. If the password is rejected by Active Directory, then the service will respond with a SOAP fault. In that case, the client must restart the password reset process.

The behavior of the Password Reset endpoint is illustrated in the following figure.

Password Validation Fault

If a password submitted by an authenticated user is rejected by Active Directory, then the STS will respond with a SOAP fault. The <s:Text> element may also contain the text of any response from Active Directory.

The following is an example of the fault that may be returned when a user tries to set a password that Active Directory rejects.

<s:Envelope 
   xmlns:s=‘http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa=‘https://schemas.xmlsoap.org/ws/2004/08/addressing' 
  xmlns:wst=‘https://schemas.xmlsoap.org/ws/2005/02/trust'
  xmlns:wsu=‘https://schemas.xmlsoap.org/ws/2002/07/utility'>
  <s:Header>
    <wsa:Action>      
      https://schemas.xmlsoap.org/ws/2004/09/transfer/fault
    </wsa:Action>
      </s:Header>
  <s:Body>
    <s:Fault>
      <s:Code>
        <s:Value>s:Receiver</s:Value>
        <s:SubCode>InvalidRepresentation</s:SubCode>
      </s:Code>
      <s:Reason>
        <s:Text>The supplied attribute already exists.</s:Text>
      </s:Reason>
      <s:Detail/>
    </s:Fault>
  </s:Body>
</s:Envelope>

Remarks

The FIM web service only accepts UTF-8 encoding of strings and SOAP messages. Other encodings will be converted to UTF-8 if possible. If an encoding cannot be converted to UTF-8 then the web service will return wxf:InvalidRepresentationFault (see WS-Transfer: Identity Management Operations for Directory Access Extensions specification).