Message-Specific Authorization

Article
06/14/2010

The FIM Service executes one or more workflow processes for authorizing a request based on who submitted the request, the particular objects to which the request pertains, and on exactly what is to be done to those objects. For example, a user could try to join a distribution list or try to access another user's private information. In either case, one or more workflow processes for authorizing the requests may apply. Those processes may require the approval of another user or require that the user supply some justification for the request.

The FIM Service complies with this requirement for authorizing requests based on the details of those requests in this manner:

FIM allows for users to associate authorization processes with requests to FIM based on who submits the request, 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 and authorization 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 authentication processes associated with the request, those authentication processes are handled as specified in Message-Specific Authentication.
Then, if there are any authorization 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 authorization processes that have been found to be associated with the request may be retrieved.
- The contents of the <Detail> element will signify that the request requires authorization before processing can continue.
- The <Detail> element will also provide a Web Services Addressing endpoint reference. That endpoint reference will contain the address of the Resource Endpoint of the FIM Service. The endpoint reference will also contain a reference property referring to a resource. That resource contains information about the authorization status of the original request. If the original request was a request to retrieve data, as soon as the request has been approved, the resource referred to by the reference property will also contain the requested data.
The client can use the endpoint reference provided by the SOAP fault, together with the context header, to query the status of the original request, and, if the request was for data, to retrieve that data. The client does that just by using the facilities provided by the FIM Resource Endpoint and Enumeration Endpoint endpoints.

This message-specific authorization processes are illustrated here.

Message-specific Authorization Process

Message-specific Data Retrieval Authorization Process

Message-specific Data Retrieval Auth Process

API

Exceptions

If an operation requires that an authorization process associated with a request authorization by another party is required, the operation will return a SOAP fault.

Context Header

Faults returned by the FIM Service 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 AuthorizationRequiredFaultType 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="AuthorizationRequiredFaultType">
    <xs:sequence>
      <xs:element 
      name="EndpointReference" 
      nillable="true" 
      type="wsa:EndpointReferenceType" />
    </xs:sequence>
  </xs:complexType>
  <xs:element 
    name="AuthorizationRequiredFault" 
    nillable="true" 
    type="rm:AuthorizationRequiredFaultType" />
</xs:schema>

AuthorizationRequiredFaultType Schema Elements

Element	Description
Endpoint Reference	A WS-Addressing endpoint reference that consists of an address and a reference property. The address will be the address of the Resource Endpoint of the FIM Service. The reference property value will be of the form defined by the ResourceReferenceProperty XML schema in the Resource Factory Endpoint document, and will refer to a resource that represents the original request for which authorization is required.
AuthorizationRequiredFault	Wrapper

Endpoint Reference

A WS-Addressing endpoint reference that consists of an address and a reference property. The address will be the address of the Resource Endpoint of the FIM Service. The reference property value will be of the form defined by the ResourceReferenceProperty XML schema in the Resource Factory Endpoint document, and will refer to a resource that represents the original request for which authorization is required.

AuthorizationRequiredFault

Wrapper

The <Detail> element of the SOAP fault will provide a WS-Addressing endpoint reference that contains a reference property that refers to resource representing the request for which authorization is required. The structure of that resource is defined by the Service Request XML Schema shown here. The elements of the schema are described in the subsequent table. The structure of the resource supports all these operations:

A user who can approve or reject the request does so by updating the <data> element of the resource with a <RequestAuthorizationData> element.
The user who submitted the request can determine the status of the request by retrieving the <Status> element.
The user who submitted the request can retrieve any data that was to have been retrieved by the original request by retrieving the <Data> element.
A user can retrieve all the requests that the user can approve by enumerating the requests in the Approvers collection that include the user's unique identifier.
A user can retrieve all the requests that the user submitted that required authorization by enumerating the requests in which the user's unique identifier equals the value of the <CreatedBy> element. The request resource inherits its data structure from the Resource schema.

FIM Service Request schema

<?xml version='1.0' encoding='utf-8'?>
<xsd:schema 
  xmlns:xsd='http://www.w3.org/2001/XMLSchema' 
  xmlns:rm='http://schema.microsoft.com/2006/11/ResourceManagement'
  targetNamespace='http://schema.microsoft.com/2006/11/ResourceManagement'>
  <xsd:simpleType name='RequestStatusType' >
    <xsd:restriction 
      base='xs:string'>
      <xsd:enumeration value='Cancelled' />
      <xsd:enumeration value='NotFound' />
      <xsd:enumeration value='Denied' />
      <xsd:enumeration value='Authenticating' />
      <xsd:enumeration value='Authenticated' />
      <xsd:enumeration value='Authorizing' />
      <xsd:enumeration value='Authorized' />
      <xsd:enumeration value='Processing' />
      <xsd:enumeration value='ProcessingEffects' />
      <xsd:enumeration value='Completed' />
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:complexType 
    name='RequestDetailsType'>
    <xsd:extension 
      base='Resource'>
      <xsd:sequence>
        <xsd:element 
          name='ReferenceProperty' 
          type='xs:string' 
          minOccurs='0' 
          maxOccurs='1'/>
        <xsd:element 
          name='Action' 
          type='xs:string' 
          minOccurs='1' 
          maxOccurs='1'/>
        <xsd:element 
          name='Body' 
          type='xs:string' 
          minOccurs='1' 
          maxOccurs='1'/>
      </xsd:sequence>
    </xsd:extension>
  </xsd:complexType>
  <xsd:complexType 
    name='ApprovalActionType'>
    <xsd:extension 
      base='Resource'>
      <xsd:sequence>
        <xsd:element 
          name='RequiredApproval' 
          type='xs:string' 
          minOccurs='1' 
          maxOccurs='1'/>
      </xsd:sequence>
    </xsd:extension>
  </xsd:complexType>
  <xsd:complexType 
    name='ProcessType'>
    <xsd:extension 
      base='Resource'>
      <xsd:sequence>
        <xsd:element 
          name='Actions' 
          type='xs:string' 
          minOccurs='0' 
          maxOccurs='1'/>
        <xsd:element 
          name='WorkflowDefinitionID' 
          type='xs:string' 
          minOccurs='1' 
          maxOccurs='1'/>
        <xsd:element 
          name='WorkflowStatus' 
          type='xs:string' 
          minOccurs='1' 
          maxOccurs='1'/>
      </xsd:sequence>
    </xsd:extension>
  </xsd:complexType>
  <xsd:complexType 
    name='RequestType'>
    <xsd:complexContent>
      <xsd:extension 
        base='Resource'>
        <xsd:sequence>
          <xsd:element 
            name='Status' 
            type='rm:RequestStatusType'
            minOccurs='1' 
            maxOccurs='1'/>
          <xsd:element 
            name='Details' 
            type='xs:string'
            minOccurs='1' 
            maxOccurs='1'/>
          <xsd:element 
            name='ApprovalProcesses' 
            type='xs:string'
            minOccurs='0' 
            maxOccurs='unbounded'/>
          <xsd:element 
            name='ApprovalResponses' 
            type='xs:string'
            minOccurs='0' 
            maxOccurs='unbounded'/>
           <xsd:element 
            name='AuthenticationProcesses' 
            type='xs:string'
            minOccurs='0' 
            maxOccurs='unbounded'/>
      <xsd:element 
            name='AuthorizationProcesses' 
            type='xs:string'
            minOccurs='0' 
            maxOccurs='unbounded'/>
          <xsd:element 
            name='Data' 
            type='xs:string' 
            minOccurs='0' 
            maxOccurs='1'/>
    <xsd:element 
            name='ErrorString' 
            type='xs:string' 
            minOccurs='1' 
            maxOccurs='1'/>
    <xsd:element 
            name='Operation' 
            type='xs:string' 
            minOccurs='1' 
            maxOccurs='1'/>
        </xsd:sequence>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>
  <xsd:element
    Name='Request'
    type='rm:RequestType' />
</xsd:schema>

Service Request Schema Elements

Element	Description
Status	The status of the original request.
Details	Description of the original request.
ApprovalProcesses	Unique identifiers of approval processes associated with the request.
ApprovalResponses	The unique identifiers of the ApprovalResponse structures defined in the FIM Request Management specification.
Data	Any data that was to have been retrieved by the original request.
ReferenceProperty	The WS-Addressing reference property that identifies the target of the original request.
Action	The Action header of the original request.
Body	The Body of the original request.
RequiredApproval	Unique identifier of an Approval.
Actions	The unique identifiers of the ApprovalActionType structures defined in the Request Schema.
Request	Wrapper for Status, Details, ApprovalProcesses and Data elements.

Examples

The following is a sample SOAP fault that may be returned if authorization by another party is required for a requested action. The <Detail> element of the fault is structured in compliance with the AuthorizationRequiredFaultType schema defined earlier in this topic. Elements specific to the FIM Service are differentiated from those defined by the SOAP specification using bold.

Sample SOAP fault with the <Detail> element signifying that authorization for a request is required

<s:Envelope 
  xmlns:s='https://schemas.xmlsoap.org/soap/envelope/'
  xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/08/addressing'
  xmlns:ctx='https://schemas.microsoft.com/ws/2006/05/context'>  <ctx:Context xmlns:ctx="https://schemas.microsoft.com/ws/2006/05/context">    <ctx:InstanceId>19bc8ea5-27f8-4136-97a2-3699697fd271</ctx:InstanceId>  </ctx:Context>
      <s:Code>        
<s:Value>s:Client</s:Value>
        <s:Subcode>
          <s:Value>rm:InteractionRequired</s:Value>
        </s:Subcode>
      </s:Code>
      <s:Reason>
        <s:Text xml:lang="en-US" />
      </s:Reason>
      <s:Detail >
        <AuthorizationRequiredFault           xmlns="http://schemas.datacontract.org/2004/07/ResourceManagement"          xmlns:i="http://www.w3.org/2001/XMLSchema-instance">          <EndpointReference>            <wsa:Address>              http://www.woodgrovebank.com:5725/IdentityManagementService/Resource</wsa:Address><wsa:ReferenceProperties><rm:ResourceReferenceProperty>03CED96B-BE01-4C18-95A5-FCD2FAA09C25</rm:ResourceReferenceProperty ></wsa:ReferenceProperties>          </EndpointReference>        </AuthorizationRequiredFault>
      </s:Detail>
    </s:Fault>
  </s:Body>
</s:Envelope>

The following SOAP sample shows how authorization by another party may be communicated. It shows a Put request to update the object that represents the request that is to be approved or rejected with the user's choice of response. The object that represents the request is defined in compliance with the Service Request schema shown earlier in this topic. The content of the sample message shown in ellipses in the following SOAP sample is unconstrained by the definition of the Put operation in the.

Sample submission of an authorization response

<s:Envelope 
  xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" 
  xmlns:wsc="https://schemas.microsoft.com/ws/2006/05/context"
  xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" >
  <s:Header>
    <wsa:ReplyTo>
      <wsa:Address> http://www.woodgrovebank.com/sender</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To> 
      http://www.woodgrovebank.com:5725/IdentityManagementService/Resource
    </wsa:To>
    <rm:ResourceReferenceProperty>
      03CED96B-BE01-4C18-95A5-FCD2FAA09C25
    </rm:ResourceReferenceProperty>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/transfer/Put
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
  </s:Header>
  <s:Body>
    <da:ModifyRequest 
Dialect="https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
      <da:Change Operation="add">
        <da:AttributeType>
          ApprovalResponses
        </da:AttributeType>
        <da:AttributeValue>
          …
        </da:AttributeValue>
      </da:Change>
    </da:ModifyRequest>
  </s:Body>
</s:Envelope>

The following example shows a subsequent request to determine the authorization status of the earlier request to which the fault in the example immediately above pertained. The values provided for the <Expression> elements defined by WS-Transfer IMO specification indicate that not only is the status of the original request to be returned, but also the data that the original request was meant to yield if that data has subsequently been authorized for retrieval.

Request to determine the state of a request for which authorization is required

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope 
  xmlns:s="http://www.w3.org/2003/05/soap-envelope"
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"  xmlns:da="https://schemas.microsoft.com/2006/11/IdentityManagement/DirectoryAccess"
  >
  <s:Header>
    <wsa:ReplyTo>
      <wsa:Address> http://www.woodgrovebank.com/sender</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To> 
      http://www.woodgrovebank.com:5725/IdentityManagementService/Resource
    </wsa:To>
    <rm:ResourceReferenceProperty>
      urn:uuid:03CED96B-BE01-4C18-95A5-FCD2FAA09C25
    </rm:ResourceReferenceProperty>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/transfer/Get
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
    <da:IdentityManagementOperation s:mustUnderstand="true"/>
  </s:Header>
  <s:Body>
    <da:BaseObjectSearchRequest Dialect="https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
      <da:AttributeType>
        Status
      </da:AttributeType>
    </da:BaseObjectSearchRequest>
  </s:Body>
</s:Envelope>

The following sample shows a response to the preceding query about the status of an original request. It shows that the original request has been approved and provides the data that the original request was to have obtained.

Hypothetical response to a query about the status of a Get operation

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
  xmlns:s="http://www.w3.org/2003/05/soap-envelope"
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"   xmlns:da="https://schemas.microsoft.com/2006/11/IdentityManagement/DirectoryAccess"
>
  <s:Header>
    <wsa:ReplyTo>
      <wsa:Address>http://www.woodgrovebank.com/sender</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>
      http://www.woodgrovebank.com:5725/ResourceManagementService/Resource
    </wsa:To>
    <rm:ResourceReferenceProperty>
      urn:uuid:03CED96B-BE01-4C18-95A5-FCD2FAA09C25
    </rm:ResourceReferenceProperty>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
  </s:Header>
  <s:Body>
    <da:BaseObjectSearchResponse>
      <da:PartialAttribute>
        <rm:Status>Completed</rm:Status>
      </da:PartialAttribute>
    </da:BaseObjectSearchResponse>
  </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).