Note:

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

Prerequisites

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:

  1. To create first app, open the Microsoft Entra ID portal, click App Registrations and New Registration to register a new application.

  2. 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).

    Image 1

  3. 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.

    Image 2

    Image 3

  4. Click App roles to add an app role and that is it for the first application.

    Image 4

  5. To create the second app, open Microsoft Entra ID portal, click App Registrations and New Registration to register a new application.

  6. 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).

    Image 6

  7. 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.

    Image 5

  8. 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.

    Image 7

    Note: Note down the secret by copying value field.

    The secret will go in pair with application (client) ID from above.

    Image 8

  9. 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.

    Image 9

    Image 10

  10. Select Application permission and the exposed permission and then click Add permissions.

    Image 11

    Image 12

  11. Click Overview, Endpoints and copy the OAuth 2.0 token endpoint (v1) URL, which will be used for the issuance of JWT tokens.

    Image 13

  12. In Endpoints, we will grab the well-known OpenID endpoint URL which contains the remote JWKS URI.

    Image 14

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:

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.

Image 15

Now, we can decode the JWT token to grab some values like the JWT Allowed Issuer and JWT Allowed Audience.

Image 16

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

  1. 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.

    Image 17

  2. 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 contain aud claim value obtained in Task 1.

    Image 18

  3. In the Validation type section, enter JWKS URI that you obtained from Microsoft Entra ID well known OpenID endpoint.

    Image 19

  4. 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.

    Image 20

  5. In the Review section, review the deployment and click Create. Wait till deployment is in Active state and copy the endpoint URL.

    Image 21

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.

Image 22

Your OCI API Gateway deployment is now secured with Microsoft Entra ID.

Acknowledgments

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.