Message-Specific Authentication

The FIM Service executes one or more workflow processes for authenticating a user that apply based on the input that the user provides to an operation. So, depending on the particular objects to which a user's request pertains, and on exactly what the user is requesting to be done to those objects, a different process for confirming the user's identity may be required. For example, a user could request that someone be added to a privileged group. Given the nature of the group and who the user wishes to have added to the group, or either of those variables, a different process for confirming the user's identity may apply. Such a process may demand that the user provide multiple authentication factors to establish his or her identity.

FIM complies with the requirement for authenticating users based on the details of their requests in the following manner:

• FIM allows users to associate authentication processes with requests to FIM based on who the source of the request appears to be, the attributes of the specific objects to which the request pertains, and the nature of the operation requested.

• When the FIM Service receives any request, it identifies any authentication processes that are associated with the request based on who the source of the request appears to be, the attributes of the specific objects to which the request pertains, and the nature of the operation requested.

• If there are any such processes associated with the request, FIM returns a SOAP fault, as defined in the SOAP 1.2 specification. The SOAP fault will contain the following information:

  • The Context Header, which will contain an identifier by which the details of the request, and the authentication processes that have been found to be associated with the request, may be retrieved.

  • The contents of the <Detail> element will signify that the identity of the user on behalf of whom the request is being made must be further authenticated.

  • The contents of the <Detail> element will also provide the address of a Security Token Service (STS) in the FIM Service that can issue a security token to the user confirming that the user has successfully completed each authentication process associated with the request. The address provided for the STS will be the address of the Security Token Service Endpoint of FIM Service.

• The client that submitted the request to FIM may request a security token from the STS identified by the SOAP fault, as specified in the WS-Trust specification, but must also provide the Context header that was incorporated in the SOAP fault.

• The STS component of the FIM Service uses the Context Header to retrieve the authentication workflow processes that were found to be associated with the request.

• For each of those processes, the STS component of the FIM Service should issue challenges to the user for authenticating information as required by the authentication process. It should issue those challenges using the implementation of the challenge framework described in Section 10 of WS-Trust specification.

• The client application should respond to those challenges using the same implementation of the challenge framework described in Section 10 of WS-Trust specification.

• Once the STS has obtained all the authenticating information that is required by each authentication process that was found to be associated with the client's original request, the STS issues a security token to the client. That security token has the format defined in the Security Token Service Endpoint and contains SAML 1.1 Assertion elements that have unique identifiers for the authentication workflow processes that the client has completed.

• The client can then re-send another request with the same body as the original request to FIM. The request should include the security token obtained from the STS together with the Context header that was contained in the SOAP fault.

• FIM will use the Context Header of the request to retrieve the details of the original request. It will also examine the current request and identify the authentication processes associated with it. Processing of the request will continue provided that these two conditions are met:

  • The current request is identical to the original request.

  • A security token attached to the current request claims that the user on behalf of whom the request is being made has completed each authentication process associated with the current request.

This message-specific authentication process is illustrated here.

API

Exceptions

If an operation requires that additional information is required to authenticate the user of the client, the operation will return a SOAP fault.

Context Header

SOAP faults returned by FIM will incorporate the Context Header.

Detail Element

The <Detail> element will be structured according to the XML Schema shown here. The elements of that schema are explained in the subsequent table.

FIM Service AuthenticationRequiredFault Detail Schema

<?xml version='1.0' encoding='utf-8'?>
<xs:schema 
  elementFormDefault='qualified'   
  targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement' 
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/08/addressing'
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <xs:import 
    namespace='https://schemas.xmlsoap.org/ws/2004/08/addressing'/>
  <xs:complexType name='AuthenticationRequiredFaultType'>
    <xs:sequence>
      <xs:element
        name='SecurityTokenServiceAddress'
        type='wsa:Address'
        nillable='true'/>
    </xs:sequence>
  </xs:complexType>
  <xs:element 
    name='AuthenticationRequiredFault' 
    nillable='false' 
    type='rm:AuthenticationRequiredFaultType' />
</xs:schema>

FIM Service AuthenticationRequiredFault Detail Schema Elements

Example

The following SOAP message is an example of a SOAP fault that may be returned if additional information to authenticate the user of the client is required. The <detail> element of the fault must follow the schema listed earlier in this section. Elements specific to the FIM Service are shown in bold to differentiate them from elements defined by the SOAP specification.

Sample SOAP fault with the <detail> element signifying that additional confirmation of the identity of the user is required

<s:Envelope 
  xmlns:s='https://schemas.xmlsoap.org/soap/envelope/'
  xmlns:ctx='https://schemas.microsoft.com/ws/2006/05/context'>
  <s:Header>
    <ctx:Context xmlns:ctx="https://schemas.microsoft.com/ws/2006/05/context">      <ctx:InstanceId>19bc8ea5-27f8-4136-97a2-3699697fd271</ctx:InstanceId>    </ctx:Context>
  </s:Header>
  <s:Body>
    <s:Fault>
      <faultcode >s:Client</faultcode>
      <faultstring xml:lang="en-US" />
      <detail >
        <AuthenticationRequiredFault            xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement"               xmlns:i="http://www.w3.org/2001/XMLSchema-instance">         <SecurityTokenServiceAddress>           https://www.contoso.com:5726/IdentityManagementService/SecurityTokenService              </SecurityTokenServiceAddress>        </AuthenticationRequiredFault>
      </detail>
    </s:Fault>
  </s:Body>
</s:Envelope>

SAML 1.1 Attributes

The security tokens that an STS issues to confirm that the user of a client application has completed one or more authentication processes will be a SAML 1.1 token structured as defined in the Security Token Service Endpoint specification. That token will contain a SAML 1.1 <Assertion> element that has a SAML 1.1 <Subject> element identifying the user to whom the token was issued, and one or more SAML 1.1 Attribute elements attributing the completion of particular authentication processes to the user. Those Attribute elements will be structured in compliance with the following table.

Sample SAML 1.1 token attributing the completion of authentication processes to a user

A sample SAML 1.1 token that attributes the completion of an authentication process to a user is given here.

<saml:Assertion 
  MajorVersion='1' 
  MinorVersion='1' 
  AssertionID='_839c3252-a17c-4ada-9a7e-563e2792674b' 
  Issuer='Woodgrove' 
  IssueInstant='2007-03-10T19:34:16.654Z' 
  xmlns:saml='urn:oasis:names:tc:SAML:1.0:assertion'
  …
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement' >
  …
  <saml:AttributeStatement>
    <saml:Subject>
      …
    </saml:Subject>
    <saml:Attribute 
      AttributeName='authenticationProcess' AttributeNamespace=' https://schemas.microsoft.com/2006/11/ResourceManagement'>      <saml:AttributeValue Type='xs:string'>11111111-1111-1111-1111-111111111111</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute 
      AttributeName='authenticationProcess' AttributeNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'>      <saml:AttributeValue Type='xs:string'>22222222-2222-2222-2222-222222222222</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
  …
</saml:Assertion>

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 Extensions for Identity Management Operations specification).

See Also

Concepts

Web Services Overview