IBM Tivoli Federated Identity Manager, Version 6.2.2.7

OAuth STS Interface for Authorization Enforcement Points

Use the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Tivoli® Federated Identity Manager to validate a request for an OAuth protected resource. An OAuth enforcement point intercepts requests for OAuth protected resources. The OAuth enforcement point also validates the request with Tivoli Federated Identity Manager, and passes the request through, if it is valid. If the request is not valid, the enforcement point denies access to the protected resource.

OAuth STS overview

You can develop your own customized policy enforcement point to work with the Security Token Service (STS) trust chain through the STS interface. Some examples of existing customized policy enforcement points are WebSphere® Servlet Filter, Trust Association Interceptor (TAI), and a reverse proxy such as WebSEAL. As Tivoli Federated Identity Manager supports both OAuth 1.0 and OAuth 2.0 federations, you can develop customized policy enforcement points to work with either type of the OAuth federations. The following diagram illustrates the relationship between the OAuth STS trust chain and other OAuth components.

Figure 1. OAuth STS trust chain workflow

This section describes the process an OAuth enforcement point undertakes to transform an HTTP request for an OAuth protected resource into a WS-Trust message.

The transformation makes it possible for the Tivoli Federated Identity Manager STS to validate the request. It also describes the possible responses an enforcement point can receive from the STS and how to deal with them.

The interface and message structure is the same for both OAuth 1.0 and OAuth 2.0. However, this document provides distinct examples of each case to highlight the different requirements.

The following information about the policy decision point in Tivoli Federated Identity Manager must be made available to the enforcement point:

Authorization decision request (OAuth 1.0)

Configuration

For OAuth 1.0 requests, the enforcement point must additionally know the Tivoli Federated Identity Manager OAuth 1.0 issuer address prefix (urn:ibm:ITFIM:oauth:consumer:).

HTTP request

When an OAuth 1.0 client retrieves a protected resource with its access token, it constructs a request similar to the following examples. These three examples are logically the same request.
OAuth 1.0 Example 1 (authorization header)
POST /fimivt/oauth/sfprotected.jsp?username=steve HTTP/1.1
  Host: idp.tfim622.com:9443
  Content-Type: application/x-www-form-urlencoded
  Authorization: OAuth oauth_consumer_key="YvMhsjmtEEi2gjv8Tqsl",
	      oauth_token="YPxa78JggdW7hvcFRJph",
	      oauth_signature_method="HMAC-SHA1",
	      oauth_timestamp="1302828764",
	      oauth_nonce="xWlY1PbsxjpiSZ4lVGVf",
	      oauth_signature="Jpo6apiLE9hVSa8GqBSHUjFt7lg="
OAuth 1.0 Example 2 (post body)
POST /fimivt/oauth/sfprotected.jsp?username=steve HTTP/1.1
  Host: idp.tfim622.com:9443
  Content-Type: application/x-www-form-urlencoded

    oauth_consumer_key=YvMhsjmtEEi2gjv8Tqsl&oauth_token=YPxa78JggdW7hvcFRJph& 
    oauth_signature_method=HMAC-SHA1&oauth_timestamp=1302828764& 
    oauth_nonce=xWlY1PbsxjpiSZ4lVGVf&oauth_signature=Jpo6apiLE9hVSa8GqBSHUjFt7lg%3D
OAuth 1.0 Example 3 (query string)
POST /fimivt/oauth/sfprotected.jsp?username=steve&
    oauth_consumer_key=YvMhsjmtEEi2gjv8Tqsl&oauth_token=YPxa78JggdW7hvcFRJph&     
    oauth_signature_method=HMAC-SHA1&oauth_timestamp=1302828764&     
    oauth_nonce=xWlY1PbsxjpiSZ4lVGVf&oauth_signature=Jpo6apiLE9hVSa8GqBSHUjFt7lg%3D HTTP/1.1   
  Host: idp.tfim622.com:9443   
  Content-Type: application/x-www-form-urlencoded  

Authorization decision request

The OAuth 1.0 enforcement point is responsible for the following actions:
  • Transform the HTTP request into a WS-Trust SOAP message.
  • Send the WS-Trust SOAP message to the Tivoli Federated Identity Manager STS for request validation.
The HTTP request is transformed into the following WS-Trust SOAP message:

OAuth 1.0 Token Validate Request (Request Security Token)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws
        /2005/02/trust">
            <wst:RequestType xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
            </wst:RequestType>
            <wst:Issuer xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08
                /addressing">
                    urn:ibm:ITFIM:oauth:consumer:YvMhsjmtEEi2gjv8Tqsl
                </wsa:Address>
            </wst:Issuer>
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap.org
                /ws/2004/08/addressing">
                    <wsa:Address>https://idp.tfim622.com:9443/sps/oauth10fed
                    /oauth10</wsa:Address>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:Base xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM
                :1.0:stsuuser">
                    <stsuuser:Principal/>
                    <stsuuser:AttributeList/>
                    <stsuuser:ContextAttributes>
                        <stsuuser:Attribute name="oauth_token" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="port" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>9443</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="method" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>POST</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username" 
                          type="urn:ibm:names:ITFIM:oauth:query:param">
                            <stsuuser:Value>steve</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="path" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>/fimivt/oauth/sfprotected.jsp
                             </stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="scheme" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>https</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_nonce" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>xWlY1PbsxjpiSZ4lVGVf</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="host" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>idp.tfim622.com</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_timestamp" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>1302828764</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_consumer_key" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>YvMhsjmtEEi2gjv8Tqsl</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_signature" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>Jpo6apiLE9hVSa8GqBSHUjFt7lg=
                            </stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_signature_method" 
                        type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>HMAC-SHA1</stsuuser:Value>
                        </stsuuser:Attribute>
                    </stsuuser:ContextAttributes>
                </stsuuser:STSUniversalUser>
            </wst:Base>
        </wst:RequestSecurityToken>
    </soapenv:Body>
</soapenv:Envelope>

The following attributes are defined by the WS-Trust specification. They are used by Tivoli Federated Identity Manager to identify the federation associated with this request and to identify the OAuth 1.0 client.

The issuer address element (highlighted in italics) must be set to the Tivoli Federated Identity Manager OAuth 1.0 issuer address prefix (urn:ibm:ITFIM:oauth:consumer:) with the consumer key appended to the end.

The AppliesTo address element (highlighted with underline) must be set to the Provider ID of the OAuth 1.0 federation at Tivoli Federated Identity Manager. This element can be found on the federation properties page.

The following attributes are defined by the OAuth 1.0 protocol. The attributes that are not marked as optional are mandatory in the WS-Trust message that is sent to Tivoli Federated Identity Manager.

The attributes must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token, and must have the type urn:ibm:names:ITFIM:oauth:param. If one of the mandatory parameters is missing from the request from the OAuth 1.0 client, the enforcement point does not validate the request with Tivoli Federated Identity Manager. It can instantly return an HTTP 400 Bad Request status code, and can also include a description of the error in the body.

The following attributes are defined by the OAuth 2.0 protocol. The attributes are mandatory in the WS-Trust message sent to Tivoli Federated Identity Manager. The attributes are also used to reconstruct the original signature base string URI of the request.

The attributes must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token, and must have the type urn:ibm:names:ITFIM:oauth:request.

Any additional parameters that the OAuth 1.0 enforcement point finds in the request must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token. Additional parameters can be a query, or post body parameters that are not of OAuth 1.0. The type value is determined by the following table.

HTTP parameter location Attribute type value
URL Query String Parameters urn:ibm:names:ITFIM:oauth:query:param
HTTP Request Body Parameters urn:ibm:names:ITFIM:oauth:body:param

Post body parameters must be included only if the following conditions are met:

Authorization decision request (OAuth 2.0)

Configuration

For OAuth 2.0 requests, the enforcement point must additionally know the Tivoli Federated Identity Manager OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:).

HTTP request

When an OAuth 2.0 client retrieves a protected resource with its access token, it constructs a request similar to any of the following examples. Each of these three examples are logically the same request. All that differs is the transmission mechanism (HTTP header, query string, post body) for sending the OAuth 2.0 bearer access token:

OAuth 2.0 Example 1 (Access token in authorization header)
POST /fimivt/oauth/sfprotected.jsp HTTP/1.1
  Host: idp.tfim622.com:9443
  Authorization: Bearer YPxa78JggdW7hvcFRJph
  Content-Type: application/x-www-form-urlencoded

username=steve
OAuth 2.0 Example 2 (Access token in post body)
POST /fimivt/oauth/sfprotected.jsp HTTP/1.1
  Host: idp.tfim622.com:9443
  Content-Type: application/x-www-form-urlencoded

username=steve&access_token=YPxa78JggdW7hvcFRJph   
OAuth 2.0 Example 3 (Access token in query string)
POST /fimivt/oauth/sfprotected.jsp?access_token=YPxa78JggdW7hvcFRJph HTTP/1.1
  Host: idp.tfim622.com:9443
  Content-Type: application/x-www-form-urlencoded

username=steve

Authorization decision request

The OAuth 2.0 enforcement point is responsible for the following actions:
  • Transform HTTP requests into a WS-Trust SOAP message.
  • Send the WS-Trust SOAP message to the Tivoli Federated Identity Manager STS for request validation.
The HTTP request is transformed into the following WS-Trust SOAP message:

OAuth 2.0 Token Validate Request (Request Security Token)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
            <wst:RequestType xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
            </wst:RequestType>
            <wst:Issuer xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004
                /08/addressing">
                    urn:ibm:ITFIM:oauth20:token:bearer
                </wsa:Address>
            </wst:Issuer>
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004
            /09/policy">
                <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap
                .org/ws/2004/08/addressing">
                    <wsa:Address>https://idp.tfim622.com:9443/sps/oauth20fed/oauth20</wsa:Address>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:Base xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
                    <stsuuser:Principal/>
                    <stsuuser:AttributeList/>
                    <stsuuser:ContextAttributes>
                        <stsuuser:Attribute name="access_token" 
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username" 
                          type="urn:ibm:names:ITFIM:oauth:body:param">
                            <stsuuser:Value>steve</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="port" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>9443</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="method" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>POST</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="path" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>/fimivt/oauth/sfprotected.jsp</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="scheme" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>https</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="host" 
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>idp.tfim622.com</stsuuser:Value>
                        </stsuuser:Attribute>                    
                   </stsuuser:ContextAttributes>
                </stsuuser:STSUniversalUser>
            </wst:Base>
        </wst:RequestSecurityToken>
    </soapenv:Body>
</soapenv:Envelope>

The following attributes are defined by the WS-Trust specification. They are used by Tivoli Federated Identity Manager to identify the federation associated with this request and to identify the type of OAuth 2.0 access token being used.

The access_token attribute with type urn:ibm:names:ITFIM:oauth:param is mandatory in the WS-Trust message sent to Tivoli Federated Identity Manager. It must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token.

If access_token attribute is missing from the request from the OAuth 2.0 client, the enforcement point does not validate the request with Tivoli Federated Identity Manager. It can instantly return an HTTP 400 Bad Request status code and optionally can include a description of the error in the body.
Note: If the access token is included in the authorization header in the Authorization: Bearer <token> format, the token must still be added to the ContextAttributes section of the STSUU. The same format must be used as if the access token was sent through a query string or post body.

The following attributes are not mandatory in the WS-Trust message sent to Tivoli Federated Identity Manager for OAuth 2.0. However, they might be useful to a custom mapping rule that is being ran by Tivoli Federated Identity Manager.

The following attributes must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token, and must have the type urn:ibm:names:ITFIM:oauth:request.
  • method - the HTTP method of the request (GET/POST)
  • scheme - (http/https)
  • host - host header from the request
  • port - the port number on the host (only if it is a non-standard port. For example, not 80 if the method is HTTP or not 443 if the method is HTTPS)
  • path - the requested path

Any additional parameters that the OAuth 2.0 enforcement point finds in the request, such as query or post body parameters that are not of OAuth 2.0, must be appended to the Context Attribute section of the STSUniversalUser within the WS-Trust Request Security Token. The type value is determined by the following table.

In an OAuth 1.0 request, additional request parameters are required to be appended to the STSUniversalUser to calculate the correct request signature. In OAuth 2.0 requests, these parameters are NOT required. However, they might be useful to a custom mapping rule being ran by Tivoli Federated Identity Manager, and so must be appended.

HTTP Parameter Location Attribute Type Value
URL Query String Parameters urn:ibm:names:ITFIM:oauth:query:param
HTTP Request Body Parameters urn:ibm:names:ITFIM:oauth:body:param

Post body parameters must be included only if the following conditions are met:

Authorization decision response (OAuth 1.0 and OAuth 2.0)

The SOAP message response from Tivoli Federated Identity Manager (regardless of OAuth version) echoes all the context attributes sent in the original request and some extra response context attributes.

OAuth Token Validate Response (RSTR)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <wst:RequestSecurityTokenResponse wsu:
        Id="uuid56a54e7c-012f-1207-9133-c24cad886d75"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401
        -wss-wssecurity-utility-1.0.xsd">
            <wsp:AppliesTo xmlns:wsa="http://schemas.xmlsoap.org/ws/2004
            /08/addressing"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                <wsa:EndpointReference>
                    <wsa:Address>https://idp.tfim622.com:9443/sps/oauth10fed
                    /oauth10</wsa:Address>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:RequestedSecurityToken>
                <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names
                :ITFIM:1.0:stsuuser">
                    <stsuuser:Principal/>
                    <stsuuser:AttributeList/>
                    <stsuuser:ContextAttributes>                        
                        <stsuuser:Attribute name="authorized" 
                        type="urn:ibm:names:ITFIM:oauth:response:decision">
                            <stsuuser:Value>TRUE</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="expires" type="urn:ibm
                        :names:ITFIM:oauth:response:decision">
                            <stsuuser:Value>2011-04-22T00:52:18Z</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="scope" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                                <stsuuser:Value>email</stsuuser:Value>
                                <stsuuser:Value>first</stsuuser:Value>
                                <stsuuser:Value>last</stsuuser:Value>
                        </stsuuser:Attribute>                       
                        <stsuuser:Attribute name="username" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>wasadmin</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username_is_self" 
                        type="urn:ibm:names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>FALSE</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_token" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="recovered_state" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>State storage time was: 
                            2011-04-15T00:52:18Z</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="state_id" type="urn:ibm
                        :names:ITFIM:oauth:state">
                            <stsuuser:Value>2cJsZ3QhXV5rDVZHNePp</stsuuser:Value>
                        </stsuuser:Attribute>                                                                        
                    </stsuuser:ContextAttributes>
                    <stsuuser:AdditionalAttributeStatement id=""/>
                </stsuuser:STSUniversalUser>
            </wst:RequestedSecurityToken>
            <wst:Status>
                <wst:Code>http://schemas.xmlsoap.org/ws/2005/02/trust/status
                /valid</wst:Code>
            </wst:Status>
        </wst:RequestSecurityTokenResponse>
    </soapenv:Body>
</soapenv:Envelope>

The following context attributes returned to the enforcement point by Tivoli Federated Identity Manager relate to the authorization decision. It also has the attribute type urn:ibm:names:ITFIM:oauth:response:decision highlighted in italics in the previous RSTR example. It is up to the enforcement point to decide whether to down-stream these attributes to the OAuth protected resource.

These attributes are primarily for the use of the enforcement point itself to determine the authorization status.

Context attributes Description
authorized The value is set to TRUE if the OAuth request is valid and authorized; FALSE if otherwise.
expires The UTC time that the access token used in the request is no longer valid. This attribute is not present for OAuth 1.0 two-legged as that flow does not use an access token.

The following context attributes returned to the enforcement point by Tivoli Federated Identity Manager must be down-streamed from the enforcement point to the OAuth protected resource. They might be appended to the original HTTP request in any way deemed suitable by the enforcement point and the protected resource. This way, the protected resource can retrieve them (for example, as additional HTTP headers).

These context attributes have the attribute type urn:ibm:names:ITFIM:oauth:response:attribute (highlighted in bold in the previous RSTR example).

Custom mapping rules that are ran after the OAuth trust chain might also append attributes with this type. Therefore, any attribute with this type must be down-streamed to the requested protected resource.

Context attributes Description
access_token (OAuth 2.0) The OAuth access token used in the protected resource request.
client_type (OAuth 2.0) The type of client that this token was issued to, can be either public or confidential. Public clients are clients that do not have client credentials and therefore cannot authenticate to the authorization server.
oauth_token_client_id (OAuth 2.0) The unique identifier of the client to which the current access token was issued. This parameter is not returned for OAuth 1.0 requests as the consumer key is sent in the initial request. Therefore, it is still in the STSUU with the name consumer_key and the type urn:ibm:names:ITFIM:oauth:request.
oauth_token (OAuth 1.0) The OAuth access token used in the protected resource request. This attribute is not present for OAuth 1.0 two-legged as that flow does not use an access token.
scope A list of strings that represents the resource scope authorized by the user at the OAuth resource owner authorization step. The OAuth protected resource can use this attribute to determine which resources to return in the response. This attribute is only present for OAuth flows that include a user authorization step.
username The name of the user who authorized the OAuth token to access their protected resources on their behalf. With OAuth flows that do not involve a separate resource owner, this value is the client identifier.

Additional attributes with the type urn:ibm:names:ITFIM:oauth:response:attribute are sometimes appended by a custom mapping rule, such is the case with recovered_state and username_is_self in the example.

The state_id context attribute returned to the enforcement point by Tivoli Federated Identity Manager is used by a custom mapping rule that is ran after the OAuth trust chain. It has the attribute type urn:ibm:names:ITFIM:oauth:state (highlighted with an underline) and can be ignored by the enforcement point.

The state_id attribute is a unique identifier for the current OAuth token used to store state information.

If the state_id attribute is required by the OAuth protected resource, a custom mapping rule can be implemented to make a copy of this attribute. The type can be changed to urn:ibm:names:ITFIM:oauth:response:attribute from the custom mapping rule to ensure that it is down-streamed to the resource.

Error responses

An OAuth enforcement point can do as much or as little validation of OAuth requests as it prefers. Any validation it performs is repeated by Tivoli Federated Identity Manager. Doing some validation before sending an authorization request to Tivoli Federated Identity Manager might improve performance. The following validation must be performed by the enforcement point before sending a request to Tivoli Federated Identity Manager.

The enforcement point must return an HTTP 401 Unauthorized status code to the OAuth client if the following scenarios occur:
  • The enforcement point sends an authorization request to Tivoli Federated Identity Manager.
  • The enforcement point receives a SOAP message with an authorized context attribute that has a value of FALSE.
The enforcement point must return an HTTP 503 Service Unavailable status code to the OAuth client if the following scenarios occur:
  • Tivoli Federated Identity Manager encounters an error.
  • Tivoli Federated Identity Manager does not return a constructed SOAP message or the SOAP message does not contain an authorized context attribute.

The enforcement point might also optionally return a WWW-Authenticate HTTP header to indicate its support for OAuth.

Flow chart

The following chart shows the expected workflow of an OAuth authorization enforcement point.

Figure 2. OAuth authorization enforcement point workflow


Feedback