Integrating third party OAuth provider
OAuth token validation can be offloaded to the third-party Open Authorization (OAuth)/Open ID Connect (OIDC) provider by using the Introspection URL. Clients can use a third-party OAuth or OIDC provider to obtain a token that is protected by IBM API Connect®. API Connect can use this feature along with the mentioned provider to protect access to the API.
You can use IBM API Connect to protect an API that is secured by using the third-party OAuth access token in accordance with the Introspection specification as defined in RFC 7662. In
addition to the specification, the x-Introspect-
header is provided to pass other
content to the third party as you require.
The x-introspect-basic-authorization-header
is available to provide a
user configured HTTP Basic authorization header.
x-tokenIntrospect:
url: your_introspection_URL
tls-profile: tls_profile_to_use
x-tokenIntrospect
only when connecting to a third party OAuth provider. Using
x-tokenIntrospect
with a native OAuth provider increases the time taken to complete
the security validation, and is unnecessary provided that the OAuth provider is not using an OAuth
token that was generated by a different OAuth provider.When an API is protected by this feature, API Connect extracts the
bearer token and issues an HTTP POST request to the introspection endpoint specified by
x-tokenIntrospect
.
The GET request is protected by APIC with this feature.
x-Introspect-
can be used to pass information to the
third-party provider as in the
example. GET /petstore/pet/123 HTTP/1.1
Host: apiconnect.com
x-Introspect-type: dog
x-Introspect-name: simon
x-custom-apic: petstore123
Authorization: Bearer tGzv3JOkF0XG5Qx2TlKWIA
x-IBM-Client-Id: xxx-xxx
x-tokenIntrospect
: POST /oauth/introspectURL HTTP/1.1
Host: apiconnect.ibm.com
Content-Type: application/x-www-form-urlencoded
x-Introspect-type: dog
x-Introspect-name: simon
x-custom-apic: petstore123
token_type_hint=access_token&token=tGzv3JOkF0XG5Qx2TlKWIA
When the request is successful, the third-party OAuth/OIDC provider responds with HTTP 200, and the token payload information. API Connect accepts the active claim as defined in the RFC specification.
active
claim is true, the token
is treated as
valid. HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{"active":true,
"token_type":"bearer",
"client_id":"xxx-xxx",
"username":"John Smith",
...
}
active
claim is false, the
token is treated as not
valid. HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"active":false
}
A response code other than HTTP 200
indicates failure to process the
request.
When the OAuth token is valid and active, context variables are populated with information from the introspect JSON response. For more information, see API Connect context variables.
When you contact the introspection endpoint, API Connect uses
client_id
/appId
and
client_secret
/appSecret
to construct the HTTP Basic authorization
header. If only client_id
is provided, it will be sent to the third-party provider
in the form body.
x-introspect-basic-authorization-header
exists, its value is used
for the HTTP Basic authorization header when the introspection endpoint is contacted. API Connect verifies that
the HTTP Basic authorization header value is Base64 encoded before it is sent. If the header is
already encoded it is sent unmodified, otherwise the header value is encoded as shown in the
following 2
examples.HTTP/1.1
x-introspect-basic-authorization-header: user:password
GET /petstore/pet/123 HTTP/1.1 Host: apiconnect.com x-introspect-basic-authorization-header: 3rd-party-client_id:3rd-party_client_secret
API Connect sends the
following.POST ..
Authorization: Basic M3JkLXBhcnR5LWNsaWVudF9pZDozcmQtcGFydHlfY2xpZW50X3NlY3JldA==token_type_hint=access_token&token= ..
scope validate url
are
configured, and if the response is an active token with a scope claim from the third-party OAuth
Provider introspection endpoint, API Connect would further enforce the scope validation in the
following order: - If
scope
is configured for the OAuth API protection: verify the third-party scope against the scope that is configured. - If
scope validation url
is configured: verify the third-party scope against the scope validation url.
- Supply a
suppress-parameters
header as follows:suppress-parameters: client_id
orsuppress-parameters: scope
depending on which parameters you want to suppress.suppress-parameters: client_id scope
- Define an API property called
suppress-parameters
in the API definition itself, with one of the following string values:client_id
orscope
depending on which parameters you want to suppress. For information on how to define API properties, see Setting API properties.client_id scope