OAuth introspection for third-party OAuth providers

You can use a header prefix to pass information to the third-party provider. The header prefix can include a regular expression and specifies the name pattern of the headers to use for sending additional information, such as x-introspect-*.

     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 will issue this POST request to the introspection endpoint specified in x-tokenIntrospect, as illustrated in the code sample:

     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

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 invalid.

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "active":false
     }

By default, if x-introspect-basic-authorization-header exists in the request, the value is used for the HTTP Basic authentication header when the introspection endpoint is contacted. API Connect verifies that the HTTP Basic authentication header value is Base64 encoded before it is sent, and encodes it if necessary as shown in the following example. If the header is already encoded, it is sent without modification.

GET /petstore/pet/123 HTTP/1.1
Host: apiconnect.com
x-introspect-basic-authorization-header: user:password

API Connect issues the following:

POST .. 
Authorization: Basic M3JkLXBhcnR5LWNsaWVudF9pZDozcmQtcGFydHlfY2xpZW50X3NlY3JldA==token_type_hint=access_token&token= ..

If you are using the DataPower API Gateway, you can specify your own value for the HTTP Basic authentication header by providing the required value in the Basic authentication request header name field in the third party OAuth provider configuration. The following rules determine what authentication data is passed to the introspection endpoint:

• If there is a basic authentication header in the request, the specified credentials are used. The value must be either a string in the format user:password, or the Base64 encoded equivalent; API Connect will Base64 encode the value if necessary before sending the request to the introspection endpoint.
• If there is no basic authentication header in the request but there are values specified in the Basic authentication username and Basic authentication password fields in the third party OAuth provider configuration, those values are used.
• If there is no basic authentication header in the request, and user name and password details are not supplied in the third party OAuth provider configuration, but client_id and client_secret values are supplied in the body of the request, these are used.
• Otherwise, an error is returned.

For third-party OAuth provider configuration details, see Configuring a third-party OAuth provider.

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 will further enforce the scope validation in the following order:

1. If scope is configured for the OAuth API protection, verify the third-party scope against the scope that is configured.
2. If scope validation url is configured, verify the third-party scope against the scope validation URL.
3. If the third-party OAuth provider introspection endpoint does not return a scope, the Gateway will not check the scope defined in the security definition of the API where the third-party OAuth provider resource is used. For details on configuring an OAuth security definition in an API, see Creating an OAuth security definition.

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.