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
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
<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=‘http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:wst=‘http://schemas.xmlsoap.org/ws/2005/02/trust' xmlns:wsu=‘http://schemas.xmlsoap.org/ws/2002/07/utility'> <s:Header> <wsa:Action> http://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>
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).