Today we’re going to explore the ways in which API gateways can integrate with ISAM, their different OAuth roles, and the interfaces for token validation and verification exposed by ISAM as an authorization server.
ISAM has both an Authorization Server available in the form of API protection, as well as a resource server, the Web Reverse proxy.
API Gateways – Resource Servers
An API gateway is responsible for fronting APIs and performing various roles, such as audit, validation, and security measures. The focus of this article is on the security aspects of API Gateways. The API gateway, upon receiving a request to a protected API will check for the presence of an access token in the request and verify it. The result of this verification will be used to make a decision about whether the client performing the request is indeed allowed to access the protected API.
API Gateways are usually not capable of fine grained authorisation decisions beyond basic validation of the presented OAuth access token. As a compensation for this, API Gateways often expose interfaces and features that enable protected resource servers to obtain additional token metadata. This metadata can enable finer grained authorisation decision at the resources. An example might be the evaluation of scopes which might have been permitted by the resource owner and associated with the access token.
The API Gateway is a critical part of an OAuth deployment. The Gateway provides the front end point of contact for API calls performed by OAuth clients. To use the terminology defined by the OAuth authorization framework, this makes the API gateway the Resource Server, responsible for verifying a token and making a decision about whether or not a user is allowed access.
There are two common ways in which an API gateway will validate an access token depending on the type of token presented. Two common access token types exist:
- An opaque token acting as a reference to the grant which exists on the authorization server.
- An encapsulated token, the steps to validate the token will be agreed upon by the two entities in an out of band fashion.
When using an opaque token, the resource server may communicate directly with the authorization server in order to validate an access token. In the initial specification for OAuth 2.0, no provisions were made for the mechanism for a resource server to request validation of an access token. OAuth introspection (RFC 7662) was created to provide a well defined interface for clients and resource servers to discover the validity and metadata of an OAuth token from an authorization server.
ISAM – Authorization Server
ISAM can be configured to issue either opaque or encapsulated access tokens. These concepts are covered in this earlier article. In this earlier article, I also touched on the two methods which ISAM supports for token validation. Token Introspection which was added to ISAM in version 9.0.3.0 and the WS-Trust interface which has long been used by the ISAM Web Reverse Proxy to validate access tokens.
The preferred method for API gateways to validate tokens on ISAM is OAuth token introspection. This is a standardized interface. This is the core integration point between the two entities fulfilling OAuth roles.
On ISAM, both resource servers which are performing token introspection, and clients who are making requests to authorize on behalf of a user take the role of an API protection client. This API protection client can act in both capacities.
The introspect flow.
Token Introspection
As I mentioned earlier token introspection was introduced to ISAM in version 9.0.3.0. ISAM offers a specification compliant endpoint, which allows for token validation. Here is an example of usage:
POST /mga/sps/oauth/oauth20/introspect HTTP/1.1
Host: www.myidp.ibm.com
Authorization: Basic dGVzdF9jbGllbnQ6dGVzdF9jbGllbnRfc2VjcmV0
Content-Type: application/x-www-form-urlencoded
token=my_access_token
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-store, no-cache=set-cookie
{
"scope": "openid email",
"active": true,
"token_type": "bearer",
"exp": 1536554492,
"iat": 1536550902,
"client_id": "test_client",
"username": "testuser"
}
Note: Formatting added for readability
The JSON response includes:
- Who the resource owner is.
- The client which the token was issued to
- The scope of the token
- The token validity period.
When using introspection on ISAM. There are some configurations available to you:
- Token introspection can be enabled and disabled by the advanced configuration
oauth20.introspectEndpointEnabled
- For confidential clients token introspection requires a client secret to be presented.
- By default non-confidential clients without a secret cannot perform introspection, this follows the RFC which states introspection must be authenticated with client credentials. Introspection for non-confidential clients can be enabled by modifying the pre-token mapping rule to set the value of variable
only_allow_conf_client_introspect to false
- By default the client performing the introspection must be the client to whom the token was issued to. This can be disabled to allow any client introspect any other clients token by setting the value of variable
must_client_own_token_introspect to false in the post-token mapping rule.
The introspection response on ISAM is quite flexible, the JSON response can be modified to include, remove or modify the response values. This may be combined with a HTTP callout or associated attributes to enrich the response. Here is an example of adding a response attribute:
stsuu.addContextAttribute(new Attribute("static_attribute", "urn:ibm:names:ITFIM:oauth:response:attribute", "example_value"));
This will produce the output:
{
"scope": "openid email",
"active": true,
"token_type": "bearer",
"exp": 1536555492,
"iat": 1536550902,
"client_id": "test_client",
"username": "testuser",
"static_attribute": "example_value"
}
This represents a powerful tool. The ability to share OAuth grant information can enable the API gateway to perform and execute in accord with business and security policies.
Introspection allows for either an access_token or a refresh_token to be presented in the introspect request. If the type of the token is known then the parameter token_type_hint may be presented in order to optimise the lookup of the token.
The client performing introspection may choose to authenticate with BA as the above example demonstrates, or the client_id and client_secret may be provided via post parameters:
POST /mga/sps/oauth/oauth20/introspect HTTP/1.1
Host: www.myidp.ibm.com
Content-Type: application/x-www-form-urlencoded
token=my_access_token&client_id=test_client&client_secret=test_client_secret
Limiting Introspection
Introspection in may not be a desirable permission or capability for all clients. For example, you may wish to limit introspection to an API gateway which is acting as a resource server to performing introspection. In 9.0.5.0, arbitrary client metadata was added to API protection clients. By leveraging this feature, it is possible to limit which clients are able to perform introspection. This solution takes an approach in two parts. First, in the pre-token rule the following logic needs to be added:
if (request_type == "introspect") {
var strData = oauth_client.getExtendedData(); // oauth_client is defined by the execution context. getExtendedData() returns a String.
var clientExtData = {};
if(strData != null && "" != ""+strData.trim()) {
clientExtData = JSON.parse(strData);
}
var allowed_to_introspect = clientExtData.allow_introspect;
if(!allowed_to_introspect) {
OAuthMappingExtUtils.throwSTSAccessDeniedMessageException("Forbidden");
}
}
Note: This will only work on version 9.0.5.0 onwards.
Once this has been added, the client definition just needs to be updated to reflect whether or not they’re able to perform introspection. The following video shows adding the property to the client and show how clients will subsequently be restricted from introspecting without intervention from an administrator. There is one caveat here, which is if dynamic registration is enabled, then the individual registering clients will be presenting the client payload. In this instance its important that validation of the client properties be performed, to strip the property allow_introspect.
Token Validation with WS-Trust
ISAM also exposes a WS-Trust interface which allows for validation of access tokens. This is a very well known and long lived interface, introduced in TFIM and maintained in ISAM. It has the client authenticate to the STS (via a repository of credentials configured on ISAM, not client credentials.) and present a STSUniversalUser containing the token, and any other request information relevant to the attempted access to a protected resource. Here is an example request:
POST /TrustServerWS/SecurityTokenServiceWST13 HTTP/1.1
Authorization: Basic ZWFzdXNlcjpwYXNzdzByZA==
Content-Type: text/xml
<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" xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<SOAP-ENV:Body>
<wst:RequestSecurityToken>
<wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType>
<wst:Issuer>
<wsa:Address>urn:ibm:ITFIM:oauth20:token:bearer</wsa:Address>
</wst:Issuer>
<wsp:AppliesTo>
<wsa:EndpointReference>
<wsa:Address>https://localhost/sps/oauth/oauth20/</wsa:Address>
</wsa:EndpointReference>
</wsp:AppliesTo>
<wst:Base>
<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>fdbagffcaededefefcg</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:ContextAttributes>
</stsuuser:STSUniversalUser>
</wst:Base>
</wst:RequestSecurityToken>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The response for the above WS-Trust request, as well as in depth documentation on the WS-Trust integration point is well documented here. I’d suggest this resource if you want to learn more about this interface.
In this article we’ve touched on:
- API Authorization with OAuth
- Types of Bearer tokens
- The relationship between a resource server and authorization server
- Token introspection support on ISAM
- WS-Trust as a method of validating an ISAM access token
In closing, don’t hesitate to reach out to inquire more about integrating ISAM with 3rd party API gateways, or any other topic.
#ISAM