Secure OIC APIs with OAuth2 using IDCS & OCI API Gateway
Whenever we build any REST API on Oracle Integration Cloud (OIC), one of the most underrated subjects of discussion is security of the APIs.
To secure REST APIs created in OIC, we can use either Basic authentication with service accounts or OAuth 2.0 by leveraging Identity Cloud Service (IDCS). We can configure IDCS to protect OIC REST API endpoints directly and thus there is no absolute need to use OCI API Gateway. But we had our reasons to leverage OCI API Gateway as mentioned below:
- With API Gateway, we are able to easily send the access logs to OCI Logging for easy log analytics. Also, it is very useful for metering your APIs, in case you are looking at monetizing your APIs.
- With any suite of heterogeneous APIs, there are scenarios when a single task is achieved by multiple back end services (Microservices). In such cases, we can leverage OCI API Gateway to have a single front or facade for the entire task, also known as the API-Facade design pattern.
- With OCI API Gateway, we also get the luxury of abstracting the actual OIC host name from other third parties.
- OCI API Gateway also provides with a root CA TLS certificate by default, even if we do not specify a custom domain.
- Using direct OAuth 2 with OIC and IDCS, we cannot limit access of the token to certain APIs. So anyone with a valid token, will be able to access all of the OIC REST APIs, which is not a secure design.
Methodologies
To secure any OIC API using OAuth2.0 with IDCS and OCI API Gateway, there are a couple of design methodologies:
- Add OAuth 2 authentication and authorization on the OCI API Gateway layer and invoke the back end OIC APIs with basic credentials as Authorization header.
- Use OAuth2 for both the OCI API Gateway layer as well as the OIC layer.
The second option is more complex and involves the use of a custom authorization function as described here in this Oracle blog post and is not in scope of this article.
We are going to see how to secure the APIs using the first methodology here.
Prerequisites
Before going any further, the follow should be completed.
- You have to use an identity provider (like IDCS, Auth0, AD, etc.) that can issue a JSON Web Tokens (JWT).
- Provision OCI API Gateway service as documented in this Oracle Quick Start.
- Configure Authentication policy on you API Gateway deployment. Step by step detailed information is provided in this great guide.
Setup
Now that you have your OAuth2 setup done and Authentication policy is configured on OCI API Gateway deployment, we can go ahead and create the back end routes to OIC REST APIs with the Basic Authentication header.
Login to OCI Console → Developer Services → API Management → Gateways → Select the Gateway → Deployments → Select the Deployment → Click on Edit
Click on Show Route Request Policies → Header Transformations → Click on Add → Set the header name as Authorization → Set the value as base64 encoded basic credentials. Format : Base64Encode(UserName:Password)
Note : In OIC, it is mandatory to have an authentication mechanism. OIC does not allow turning off the authentication mechanism.
Now we can add up to 50 different routes in the same deployment and we would need to add this Basic credentials in the Header transformation section of each route to authorize each API call.
Now if you save this and try to invoke the API by concatenating the endpoint of the deployment with the route path and the OAuth credentials, you should be able to see the response from your back end OIC REST APIs in Postman or any other API Client.
Access Restriction
As mentioned above, there is another very important benefit to using OCI API Gateway. We can restrict access to certain APIs using the OAuth scopes in API Gateway deployment itself.
To achieve the same, first make a list of all the scopes that have been exposed in the IDCS Resource Server Application.
Now, go to OCI Console → Developer Services → API Management → Gateways → Select the Gateway → Deployments → Select the Deployment → Click on Edit → Click on Edit in the Authentication Request Policy
Click on the highlighted Show Advanced Options → Add scope as the Claim Key → Add all the scope values that we had copied earlier from IDCS Resource Application as separate entries in Claim Values → Click on Apply Changes
Note: Currently we can only add up to 5 Claim Values.
Go to the Next page → Click on Show Route Request Policies → Authorization → Click on Add → Select Any from the Type drop down → Add the scope from the above list that would have access to this route path → Click on Save Changes
Now we have successfully restricted access to the “/test” API. Clients who have access to the “/helloworld:read” scope as part of their client setup in IDCS Client Application will be able to access this API. All other clients, will get a HTTP 401 Unauthorized error.
Conclusion
With OCI API Gateway, we get a very powerful service which is cloud native and has very good support with other OCI Services. Due to the agnostic nature of the OCI API Gateway service, it helps in a very rapid setup of APIs and securing them is a breeze.