Design and Implementation

System Architecture and Flow

Refer Business Use Cases Feasible Using Third Party OAuth2.0 Token

Sequence Flow Diagram

Implementation Details

1. The user or client sends a third-party OIDC token in the Authorization header of the API call, along with the API Management Key.

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

3. If the API call is successfully authenticated at Cloud API Management, the connector searches for the ID token in the Authorization header; otherwise, the request is blocked by Cloud API Management, and an error response with a message is returned.

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

5. If the default OIDC ID token validation endpoint is not specified in pre-inputs, then an error response with a message is returned.

6. The response is retrieved from the OIDC UserInfo endpoint. If http_proxy_server and http_proxy_port are specified in pre-input, then the call to the OIDC token validation endpoint goes through the proxy server.

7. If the response code is not 200, then an error response with a message is returned.

8. If the response code is 200, then 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.

9. The connector injects request headers based on the inject headers configuration using JSONPath. For JSONPath, the response from the OAuth token validation endpoint should be valid JSON and should contain a proper content type header value related to JSON. Refer JSONPath and XPath user guide for more information.

10. 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 the OIDC ID token upfront.

• The consuming app acts as a Relaying Party (RP) and is responsible for initiating OIDC token fetching.

• Third-party IDP (Authorization server) should support remote OIDC token validation by exposing the UserInfo endpoint.

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

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

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

Error Handling

Error Name	HTTP Status Code	Cause
InvalidAuthorizationHeaderValue	401	Either authorization header not present in request or its value is not defined in the request or its value does not start with 'Bearer' scheme.
InvalidPreInputConfigurationForUserInfoEndpointURI	401	Either UserInfo endpoint URI is not defined in pre-inputs or its value is not in proper required JSON format.
DefaultUserInfoURINotPresent	401	Default UserInfo endpoint URI not provided in pre-inputs configuration.
TargetEndpointError	401	Unable to retrieve response from UserInfo Endpoint.
<Error Status Message From OpenID IDP in case of token validation fails>	<Status Code returned by OpenID IDP>	Response code 200 not retrieved from UserInfo Endpoint.

UserInfo Error Response Handling

When an error occurs, the UserInfo endpoint returns an error response. The table below lists the possible error response handling scenarios.

Scenario	UserInfo Endpoint Response	Pre-input Configurations	Gateway Response to User Client	Additional Notes
UserInfo Endpoint returns 401 Unauthorized Error Response with details in WWW-Authenticate Header.	HTTP/1.1 401 Unauthorized. WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"	error_metadata_location: ResponseHeaders. error_header_name: WWW-Authenticate	HTTP Status Code - 401. HTTP Status Message - Unauthorized. HTTP Status Response Body - error="invalid_token", error_description="The Access Token expired"	Response body is retrieved from WWW-Authenticate header as specified in pre-input configuration.
UserInfo Endpoint returns 403 Forbidden Error Response with details in WWW-Authenticate Header.	HTTP/1.1 403 Forbidden. Expires: 0. WWW-Authenticate: Bearer error="insufficient_scope", error_description="The Access Token must provide access to at least one of the scopes - profile, email, address or phone"	error_metadata_location: ResponseHeaders. error_header_name: WWW-Authenticate	HTTP Status Code - 403. HTTP Status Message - Forbidden. HTTP Status Response Body - Bearer error="insufficient_scope", error_description="The Access Token must provide access to at least one of the scopes - profile, email, address or phone"	Response body is retrieved from WWW-Authenticate header as specified in pre-input configuration.
UserInfo Endpoint returns 401 Unauthorized Error Response with details in response Body.	HTTP/1.1 401 Unauthorized. Content-Type: application/json. Cache-Control: no-store. Pragma: no-cache. {"error": "invalid_token", "errorMessage": "The access token expired"}	error_metadata_location: ResponsePayload. error_header_name: $.errorMessage	HTTP Status Code - 401. HTTP Status Message - Unauthorized. HTTP Status Response Body - The Access Token expired	Response body is retrieved using JSONPath expression from response payload as specified in pre-input configuration.
UserInfo Endpoint returns 401 Unauthorized Error Response with details in WWW-Authenticate Header but error_header_name not specified in pre-input configuration.	HTTP/1.1 401 Unauthorized. WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"	error_metadata_location: ResponseHeaders. error_header_name: not specified	HTTP Status Code - 401. HTTP Status Message - Unauthorized. HTTP Status Response Body - Error Response retrieved from UserInfo endpoint. Response Code - 401	As error_header_name is not specified, response body is default message from the connector.
UserInfo Endpoint returns 403 Forbidden Error Response with details in response body but error_payload_location not specified in pre-input configuration.	HTTP/1.1 403 Forbidden. Expires: 0. {"error": "invalid_token", "errorMessage": "The access token expired"}	error_metadata_location: ResponsePayload. error_payload_location: not specified	HTTP Status Code - 403. HTTP Status Message - Forbidden. HTTP Status Response Body - {"error": "invalid_token", "errorMessage": "The access token expired"}	As error_payload_location is not specified, complete error response from OpenIDP is set as response body which is sent to user client.
UserInfo Endpoint returns 400 Bad Request Error Response with details in response body but error_metadata_location not specified or invalid value specified in pre-inputs.	HTTP/1.1 400 Bad Request. Content-Type: application/json. Cache-Control: no-store. Pragma: no-cache. {"error": "invalid_request", "errorMessage": "Request does not contain valid authorization header"}	error_metadata_location: not specified or invalid	HTTP Status Code - 400. HTTP Status Message - Bad Request. HTTP Status Response Body - Error Response retrieved from UserInfo endpoint. Response Code - 400	As error_metadata_location is not specified, response body is default message from the connector.
UserInfo Endpoint returns 403 Forbidden Error Response with details in WWW-Authenticate Header but invalid value specified in error_header_name	HTTP/1.1 403 Forbidden. Expires: 0. WWW-Authenticate: Bearer error="insufficient_scope", error_description="The Access Token must provide access to at least one of the scopes - profile, email, address or phone"	error_metadata_location: ResponseHeaders. error_header_name: ErrorHeader	HTTP Status Code - 403. HTTP Status Message - Forbidden. HTTP Status Response Body - Error Response retrieved from UserInfo endpoint. Response Code - 403	As "ErrorHeader" is not present in OpenIDP Error Response, response body is default message from the connector.
UserInfo Endpoint returns 401 Unauthorized Error Response with details in response Body but invalid jsonpath specified in pre-input configuration.	HTTP/1.1 401 Unauthorized. Content-Type: application/json. Cache-Control: no-store. Pragma: no-cache. {"error": "invalid_token", "errorMessage": "The access token expired"}	error_metadata_location: ResponsePayload. error_header_name: $.message	HTTP Status Code - 401. HTTP Status Message - Unauthorized. HTTP Status Response Body - Error Response retrieved from UserInfo endpoint. Response Code - 403	As invalid JSONPath is specified for error_payload_location, response body is default message from the connector.
UserInfo endpoint returns 500 Server Error response with no payload and error_metadata_location specified as ResponsePayload.	HTTP/1.1 500 Server Error	error_metadata_location: ResponsePayload	HTTP Status Code - 500. HTTP Status Message - ServerError. HTTP Status Response Body - Error Response retrieved from UserInfo endpoint. Response Code - 500	In case no response body is retrieved from OpenID IDP, response body is default message from the connector.

HTTP status code and status message is always returned to the User Client which is retrieved from OpenID IDP in case of error response from OpenID IDP.