Design and Implementation

System Architecture and Flow

Refer to the System Architecture Flow for Business Use Cases Feasible Using Third Party OAuth 2.0 Token Connector.

Sequence Flow Diagram

Implementation Details

• User client sends third-party OAuth token in the authorization header of the API call, along with the Cloud API Management Key

• The connector authenticates using an API key retrieved from the incoming API request.

• If the API call is successfully authenticated with Cloud API Management, the connector looks for a token in the authorization header; otherwise, the request is blocked by Cloud API Management, and an error response message is returned.

• If the OAuth token is present, the connector retrieves the OAuth token validation endpoint based on the region code header. If the OAuth token validation endpoint is not specified in the incoming region code header, the default OAuth token validation endpoint is retrieved from the pre-inputs.

• If the default OAuth token validation endpoint is not specified in the pre-inputs, an error response is returned.

• Response is retrieved from the OAuth token validation endpoint. If http_proxy_server and http_proxy_port are specified in pre-input, then the call to the OAuth token validation endpoint goes through the proxy server.

• If the response code is not 200, then an error response message is returned.

• If the response code is 200, the connector retrieves the inject_headers configuration based on the region code header. If the inject_headers configuration for a specific region code is not present, then the default inject_header configuration is retrieved.

• The connector injects request headers based on the inject headers configuration using JSONPath/XPath. For JSONPath, the response from the OAuth token validation endpoint should be valid JSON with a proper JSON content-type header. For XPath, the response from the OAuth token validation endpoint should be valid XML and include a proper XML content-type header.

• If block_authorization_header is set to true in the pre-input configuration, the authorization header is removed from the target request before it is sent to the target endpoint.

Business Rules and Assumptions

• The consuming app is responsible for acquiring an OAuth2.0 access token upfront.

• A third-party IDP (authorization server) should support remote OAuth2.0 access token validation by exposing an introspection endpoint.

  • The token validation endpoint must return a 200 OK response for successful validation.

  • Any !200 OK response code, including 401 Unauthorized, is considered unsuccessful token validation.

• Cloud API Management should be able to access the introspection endpoint remotely.

Error Messages

Error Name	HTTP Status Code	Cause
AuthorizationHeaderNotPresentInRequest	401	Either the authorization header is not present in the request, or its value is not defined in the request.
InvalidPreInputConfigurationForTokenValidationURI	401	Either the token validation URI is not defined in pre-inputs, or its value is not in the proper required JSON format.
DefaultTokenValidationURINotPresent	401	Default token validation URI not provided in pre-inputs configuration.
TargetEndpointError	401	Unable to retrieve response from OAuth Token Validation Endpoint.
TokenValidationFails	401	Response code 200 not retrieved from the OAuth Token Validation Endpoint.