OAuth STS Interface for Authorization Enforcement Points

Edit online

Use the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Verify Identity Access 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 Verify Identity Access, 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 Verify Identity Access supports OAuth 2.0 federations, you can develop customized policy enforcement points to work with OAuth 2.0 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 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 following information about the policy decision point in Verify Identity Access must be made available to the enforcement point:

The absolute URL of the Verify Identity Access STS trust service endpoint. (For example: https://isam.com/TrustServer/SecurityTokenService)
The basic authentication user name and password for the Verify Identity Access STS trust service (if required).
The ProviderID of the Verify Identity Access federation the client belongs to, which is used as the AppliesTo address for WS-Trust requests. Optionally, the enforcement point accepts a provider ID from the OAuth client as a request parameter to serve more than one federation concurrently.

Authorization decision request

Configuration

For OAuth 2.0 requests, the enforcement point must know the Verify Identity Access 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 is 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 /oauth/protectedresource.jsp
  Host: isam.com
  Authorization: Bearer YPxa78JggdW7hvcFRJph
  Content-Type: application/x-www-form-urlencoded

username=steve

OAuth 2.0 Example 2 (Access token in post body)

POST /oauth/protectedresource.jsp
  Host: isam.com
  Content-Type: application/x-www-form-urlencoded

username=steve&access_token=YPxa78JggdW7hvcFRJph

OAuth 2.0 Example 3 (Access token in query string)

POST /oauth/protectedresource.jsp?access_token=YPxa78JggdW7hvcFRJph
  Host: isam.com
  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 Verify Identity Access 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://localhost/sps/oauth/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>/oauth/protectedresource.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>isam.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 Verify Identity Access to identify the federation that is associated with this request and to identify the type of OAuth 2.0 access token being used.

The Issuer address element (highlighted in bold) must be set to the Verify Identity Access OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:). The token type must be appended at the end and separated by a colon. Currently, the only token supported type is bearer, which means the issuer address must be set to urn:ibm:ITFIM:oauth20:token:bearer.
The AppliesTo address element (highlighted in italics) must match the Provider ID of the API Protection Definition within Verify Identity Access. The general form is https://localhost/sps/oauth/oauth20/{id}.

The access_token attribute with type urn:ibm:names:ITFIM:oauth:param is mandatory in the WS-Trust message sent to Verify Identity Access. 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 Verify Identity Access STS. 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 that is sent to Verify Identity Access STS for OAuth 2.0. However, they might be useful to a custom mapping rule that is executed by Verify Identity Access.

It is recommended to append the following attributes to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token and set the attribute type to 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

Append 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, 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 OAuth 2.0 requests, these parameters are not required. However, they might be useful to a custom mapping rule that is executed by Verify Identity Access. So it is recommended that you append them.


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:

The entity-body is single-part.
The entity-body follows the encoding requirements of the application/x-www-form-urlencodedcontent-type as defined by [W3C.REC-html40-19980424].
The HTTP request entity-header includes the Content-Type header field set to application/x-www-form-urlencoded.

Authorization decision response

The SOAP message response from Verify Identity Access (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://localhost/sps/oauth/oauth20/</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 Verify Identity Access 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 when the access token that is used in the request is no longer valid.

The following context attributes returned to the enforcement point by Verify Identity Access 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 executed 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	The OAuth access token that is used in the protected resource request.
client_type	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	The unique identifier of the client to which the current access token was issued.
scope	A list of strings that represents the resource scope that is 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 Verify Identity Access is used by a custom mapping rule that is executed 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 that is 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

You can customize the amount of OAuth request validation that the enforcement point performs. Any validation it performs is repeated by Verify Identity Access. Doing some validation before sending an authorization request to Verify Identity Access might improve performance. The following validation must be performed by the enforcement point before sending a request to Verify Identity Access.

Validate that some OAuth data is present. If not, return an HTTP 401 Unauthorized status code.
Validate that none of the required OAuth parameters are missing. If any of them are not present in the request, return an HTTP 400 Bad Request status code.
Validate that none of the required OAuth parameters occur more than once in the request. They must also occur only in the one component of the request; for example, the query string or the authorization header. If the validation fails, return an HTTP 400 Bad Request status code.

The enforcement point must return an HTTP 401 Unauthorized status code to the OAuth client if the following scenario occurs:

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:

Verify Identity Access encounters an error.
Verify Identity Access 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