Note:
- This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
- It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.
Use Microsoft Entra ID to Secure OCI API Gateway Using OAuth and OpenID Connect
Introduction
Oracle Cloud Infrastructure (OCI) API Gateway is a serverless fully-managed service in OCI that can be used to protect API endpoints and web applications. It provides many security functionalities like rate limiting, authorization enforcement, dynamic routing, SSL enforcement, and so on. We have seen a lot of requests coming in from our customers asking how Microsoft Entra ID OAuth tokens can be used to protect APIs running behind OCI API Gateway or how can we leverage Microsoft Entra ID tokens to authenticate against OCI API Gateway. For more information about OCI API Gateway authentication, see Validating Tokens to Add Authentication and Authorization to API Deployments.
Objectives
- Integrate OCI API Gateway and Microsoft Entra ID using OAuth and OpenID Connect (OIDC). We will see how we can use Microsoft Entra ID token to authenticate with OCI API Gateway in a secure manner.
Prerequisites
-
Access to OCI and Microsoft Entra ID tenancies.
-
A JSON Web Token (JWT) from Microsoft Entra ID, this JWT can be retrieved using Postman, curl or any other API client.
Task 1: Configure Microsoft Entra ID as an OAuth Identity Provider (IdP)
On the Microsoft Entra ID side, we need to configure two client applications in Microsoft Entra ID: one which will be used to authenticate to Microsoft Entra ID, another client app will be used to expose an API on Microsoft Entra ID and we will retrieve a token for this exposed API using the client ID, secret of the first app via Postman. We will examine this token and use the audience (aud) and the issuer fields to be imported in the OCI API Gateway configuration.
To create and set up the two client apps on Microsoft Entra ID, follow these steps:
-
To create first app, open the Microsoft Entra ID portal, click App Registrations and New Registration to register a new application.
-
Enter the following information and click Register.
- Name: Enter the application name.
- Supported account types: Select Accounts in this organizational directory only (Default Directory only - Single tenant).
-
Click Expose an API to expose this to client apps by adding application ID URI and click Add a scope to add scope. For this tutorial, we have provided test values as shown in the following images to expose an API and to add a scope.
By registering web API and exposing it through scopes, assigning an app role, you can enter permissions-based access to its resources to authorized users and client apps that access your API.
Note: Note down the application ID URI, this will be used later on while grabbing a token from Microsoft Entra ID.
-
Click App roles to add an app role and that is it for the first application.
-
To create the second app, open Microsoft Entra ID portal, click App Registrations and New Registration to register a new application.
-
Enter the following information and click Register.
- Name: Enter the application name.
- Supported account types: Select Accounts in this organizational directory only (Default Directory only - Single tenant).
-
Note down the Application (client) ID, since we will use it as a credential in token generation API to get a token for the first client app exposed as an API.
-
Click Certificates & secrets, New client secret and enter the following information and then click Add.
- Description: Enter a short secret description.
- Expires: Select the expiry. By default, the expiration of the secret is set to six months.
Note: Note down the secret by copying value field.
The secret will go in pair with application (client) ID from above.
-
Click API permissions and Add a permission for
Api_App
. In Select an API section, select APIs my organization uses and select the API that was exposed while configuring the first app. -
Select Application permission and the exposed permission and then click Add permissions.
-
Click Overview, Endpoints and copy the OAuth 2.0 token endpoint (v1) URL, which will be used for the issuance of JWT tokens.
-
In Endpoints, we will grab the well-known OpenID endpoint URL which contains the remote JWKS URI.
We are done with the Microsoft Entra ID part and now we move towards configuring the OCI API Gateway. However, before configuring the API Gateway in OCI, we will collect the necessary details from the JWT and the openid-configuration
from Microsoft Entra ID using Postman. We will need to collect the below details:
- JWT Issuer: This can be obtained from the token -
iss
field in the token. - JWT Allowed Audiences: This is also obtained from the token -
aud
field in the token. - The remote JWKS URI: This is available from the OpenID Connect Metadata document. This is the remote JWKS URI:
https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys
.
Get an access token from Microsoft Entra ID using Postman. Note the scope value, it should be your application ID URI created under Expose an API section of your Api_App and add the /.default
to the end as shown in the following image.
Use Postman to retrieve the JWT token from Microsoft Entra ID. Enter token API URL https://login.microsoftonline.com/{tenant-id}/oauth2/token
, while replacing {tenant-id}
with your Azure tenant ID. Send a request and copy access_token
value.
Now, we can decode the JWT token to grab some values like the JWT Allowed Issuer and JWT Allowed Audience.
We will use JSON Web Token (JWT) issued by Microsoft Entra ID for the stock response configured under OCI API Gateway.
Task 2: Configure an OCI API Gateway
-
Go to OCI API Gateway and under the Authentication section, select Single Authentication and enter the following information.
- Authentication type:
OAuth 2.0/ OpenID Connect
. - Token location:
Header
. - JWT token header name:
Authorization
. - Authentication scheme:
Bearer
.
- Authentication type:
-
In the Additional JWT validation section, define allowed Issuers and Audiences. Since we used v1 token API, Allowed issuers should be set to
https://sts.windows.net/{tenant-id}/
. Replace{tenant-id}
with your Azure tenant ID. Allowed audiences should containaud
claim value obtained in Task 1. -
In the Validation type section, enter JWKS URI that you obtained from Microsoft Entra ID well known OpenID endpoint.
-
To create a route, enter the following information and click Next.
- Path: Define a path.
- Methods: Select a method.
- Select Add a single backend.
- Backend Type: Select Stock response.
- Status code: Enter status code.
- Body: Define a simple body.
Note: For simplicity purposes we are exposing a stock response as the backend type for the API Gateway. This typically would be an API protected via API Gateway, however the configuration for Microsoft Entra ID OIDC authentication is similar.
-
In the Review section, review the deployment and click Create. Wait till deployment is in
Active
state and copy the endpoint URL.
Use Postman to test the secured API endpoint. Enter endpoint and suffix it with route path. Add Authorization header, use the Bearer scheme, and paste the JWT token that you got from Microsoft Entra ID.
Your OCI API Gateway deployment is now secured with Microsoft Entra ID.
Related Links
Acknowledgments
- Author - Aqib Javid Bhat (Senior Cloud Engineer)
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Use Microsoft Entra ID to Secure OCI API Gateway Using OAuth and OpenID Connect
F93864-01
March 2024