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.

The sequence diagram depicts the overall flow of request and response.

Flow diagram of OAuth and Introspect URL

The Introspection URL can be configured in the OAuth security definition of the API. Entering a valid URL and optional TLS profile creates the following section in the API definition, conforming to the Open API (Swagger 2.0) specification:

x-tokenIntrospect:
 url: your_introspection_URL
 tls-profile: tls_profile_to_use

Note: 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.

A header prefix of 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

API Connect issues this POST request to the introspection endpoint that you specified in 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.

If the value of the 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",
       ...
    }

If the value of the 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.

If 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= ..

Note: If you need to contact the introspection end point with a credential that cannot be specified with any of the methods previously described, a proxy policy can be used to override the Basic Authorization Credential to the proper value. When you use a proxy policy you can export and share the OAuth provider swagger while maintaining the security of sensitive credential information.

If either, or both, of scope and 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.

For more information, see Scope.

By default the API Connect client ID and scope are sent to the third party OAuth provider. You can suppress this behavior in either of the following ways:

Supply a suppress-parameters header as follows:
```
suppress-parameters: client_id
```
```
suppress-parameters: scope
```
or
```
suppress-parameters: client_id scope
```
depending on which parameters you want to suppress.
Define an API property called suppress-parameters in the API definition itself, with one of the following string values:
```
client_id
```
```
scope
```
or
```
client_id scope
```
depending on which parameters you want to suppress. For information on how to define API properties, see Setting API properties.