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 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 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
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
 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="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 |
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
| Copy Code |
|
|---|---|
<?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
| Copy Code |
|
|---|---|
<s:Envelope xmlns:s='http://schemas.xmlsoap.org/soap/envelope/' xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:ctx='http://schemas.microsoft.com/ws/2006/05/context'> <ctx:Context xmlns:ctx="http://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 xmlns=""> <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
| Copy Code |
|
|---|---|
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsc="http://schemas.microsoft.com/ws/2006/05/context" xmlns:rm="http://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> http://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="http://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
| Copy Code |
|
|---|---|
<?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement" xmlns:da="http://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> http://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="http://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
| Copy Code |
|
|---|---|
<?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement" xmlns:da="http://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> http://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).