Introduction

In modern cloud architectures, OAuth 2.0 client credentials flow is widely used to securely invoke backend systems such as Oracle Integration Cloud (OIC).
However, OAuth introduces a subtle challenge – SCOPEs.

Although the OAuth RFC treats scopes as optional, many enterprise platforms (including OCI IAM) enforce scopes as an additional security control to ensure that tokens are issued only for explicitly authorized resources.

For most enterprise clients this works smoothly, but in one of our recent real-world project, we faced a unique challenge.

The Real Use Case

A well-known company XYZ, a leader in off-road racing suspension technology, undertook a major initiative to modernize its digital ecosystem. As part of this modernization, they exposed a set of REST APIs (hosted on a cloud integration platform) to both its customers and dealer network. The goal was to:

  • check suspension models
  • verify compatibility
  • track service requests
  • fetch performance tuning data
  • integrate with third-party dealer systems

To protect the APIs, the company used an OCI API Gateway with an OCI Authorizer Function

The API consumers included:

  • external dealers
  • resellers
  • service partners
  • OEM system integrators

These consumers were capable of generating OAuth client credential tokens with client_id and client_secret.

But here’s the catch…

The Problem: External Consumers Could NOT Use OAuth SCOPE

Although the OAuth 2.0 spec (RFC 6749) clearly states that Scope is optional, OCI IAM requires a scope to be sent when token generation is performed using the OAuth client credentials flow.

This became a problem for the external consumers:

  • They did not understand OIC-specific scopes
  • They did not have any mechanism to dynamically generate or construct scope strings
  • Their legacy systems were unable to add scopes into OAuth requests
  • Changing every consumer system would have required significant effort

In short → the consumers simply could not provide a scope, but the backend IAM service required it.

This mismatch led to token failures such as:

400 - invalid_scope
Required scope missing

The Solution: Hardcoding OIC Scope in OCI Authorizer Function

Instead of forcing every downstream consumer to modify their OAuth implementation, we moved the complexity upstream, into the OCI layer.

The solution:

  • The client sends a simple OAuth Basic header
    Authorization: Basic <base64(client_id:client_secret)>
  • The OCI API Gateway forwards the request to an Authorizer Function
  • The Function internally injects the required OIC integration scope
    This scope is impossible for external systems to guess:
    https://<OIC_HOST>:443urn:opc:resource:consumer::all
  • The function performs the token call on behalf of the client
    This way, the external clients do not have to worry about scopes at all.

Why This Works

  • OCI IAM allows a client-secret based token call using client credentials flow
  • The authorizer function is trusted
  • The function knows the exact OIC scope
  • The API gateway uses the function to validate/authenticate the caller
  • Downstream consumers get a valid IAM token without ever specifying a scope

    Here is the OCI function which was used in the implementation.

The Architecture

Here is the sequence diagram for this token-based authentication flow. In this setup, the Authorizer Function uses a hardcoded scope value when making a request to the OCI IAM Token Endpoint to validate or retrieve the token. The obtained token, whose permissions are governed by the hardcoded scope, is then used to determine authorization for the client’s request.

Once the token is validated, the Authorizer Function returns the authorization result to the API Gateway. If the request is authorized, the API Gateway forwards the client’s request to the OIC Integration APIs, passing along the validated token as proof of authentication. The response from the OIC Integration APIs then travels back through the API Gateway before being returned to the client, completing the secure and controlled request flow.

Outcome

This design ensures:

  • Zero breaking changes for customers. The design doesn’t force existing customers to change their integrations or code. Their current workflows will work as before; there’s backward compatibility.
  • Zero requirement to adopt OAuth scopes. Customers aren’t required to deal with configuring or managing OAuth scopes (which usually restrict what an application can access). The integration can work securely without customers taking extra steps to define or adopt new OAuth scope policies.
  • Full security using IAM tokens.
  • API Gateway enforces validation transparently. It automatically checks and enforces security policies (like authentication and authorization) without customers having to add extra validation code. This happens behind the scenes (“transparently“).
  • Hardcoded scope ensures correct resource access. The OCI function internally sets (hardcodes) the necessary OAuth scope for each request, ensuring that calls can only access the intended resources. This prevents accidental or unauthorized access without imposing extra setup on the customer.

The off-road racing suspension company achieved:

  • A secure, token-based integration
  • Zero changes required for external consumers
  • Fully OAuth-compliant implementation
  • Clean separation of authentication logic
  • A scalable, cloud-native token broker model

Consumers continue calling the APIs with just:
Authorization: Basic <credentials>

Everything else is handled internally in the Authorizer function.

Conclusion

This case study highlights how cloud-native extensibility in OCI (via API Gateway + Functions) can bridge compatibility gaps between industry standards and real-world client capabilities.
By pushing complexity into the infrastructure layer, we allowed hundreds of external systems to continue working without modification – while still delivering a fully secure OAuth-compliant token exchange flow.