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 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 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.
- The current request is identical to the
original 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
 Copy Code |
|
|---|---|
<?xml version='1.0' encoding='utf-8'?> <xs:schema elementFormDefault='qualified' targetNamespace='http://schemas.microsoft.com/2006/11/ResourceManagement' xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:rm='http://schemas.microsoft.com/2006/11/ResourceManagement'> <xs:import namespace='http://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
| Element | Description |
|---|---|
|
SecurityTokenServiceAddress |
Provides the address of an STS 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 will be the address of the Security Token Service Endpoint of FIM. |
|
AuthenticationRequiredFault |
Wrapper |
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
| Copy Code |
|
|---|---|
<s:Envelope xmlns:s='http://schemas.xmlsoap.org/soap/envelope/' xmlns:ctx='http://schemas.microsoft.com/ws/2006/05/context'> <s:Header> <ctx:Context xmlns:ctx="http://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 xmlns="">s:Client</faultcode> <faultstring xml:lang="en-US" xmlns=""/> <detail xmlns=""> <AuthenticationRequiredFault xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <SecurityTokenServiceAddress> http://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.
| Asserted Attribute | Number | Structure |
|---|---|---|
|
Completion of a particular authentication process |
1 or more |
AttributeName: authenticationProcess AttributeNamespace: http://schemas.microsoft.com/2006/11/ResourceManagement AttributeValue Type: rm:GUID AttributeValue value: unique identifier of an authentication process the user has completed |
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.
| Copy Code |
|
|---|---|
<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='http://schemas.microsoft.com/2006/11/ResourceManagement' > … <saml:AttributeStatement> <saml:Subject> … </saml:Subject> <saml:Attribute AttributeName='authenticationProcess' AttributeNamespace=' http://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='http://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).