How to Integrate Okta OAuth 2.0 OIDC with MuleSoft (Mule 4)

by MuleTrains •
0

Security is the backbone of modern API management. In this guide, we will walk through the exact steps to integrate Okta as an Identity Provider (IdP) for MuleSoft Anypoint Platform using the OAuth 2.0 OIDC standard.

What is OAuth 2.0 OIDC?

Think of OIDC (OpenID Connect) as a digital ID card built on top of the OAuth 2.0 framework. While OAuth 2.0 handles access (like a ticket letting you into a concert), OIDC handles identity (confirming who you actually are). It allows clients to verify an End User's identity via an Authorization Server and safely retrieve basic profile information.

Prerequisites

Before we dive in, make sure you have the following ready:

  • An Anypoint Platform account. (You can sign up for one if you haven't already).
  • An Okta account.
  • A MuleSoft API active in API Manager.
  • Portal Access. Your APIs must be accessible via the developer portal or Exchange.
  • POSTMAN Client. We will use this for testing.

Phase 1: Setting Up Your Application in Okta

First, we need to create an integration in Okta that represents our web application (MuleSoft).

  1. Log in to Okta and navigate to the Applications menu.
  2. Click Create App Integration.
  3. Select OIDC - OpenID Connect as the Sign-in method.
  4. Select Web Application as the Application type.
  5. Click Next.

Configuring the App Details

  • On the next screen, you can enter a name for your app. You can leave the rest of the settings as they are.
  • Click Done.
Crucial Step: You will now see your Client ID and Client Secret. Copy these to a Notepad; you will need them shortly.

Refining Permissions

  1. Click the Edit button on your new app settings.
  2. Check the box for Client Credentials under "Grant type".
  3. Under "Controlled access", select Allow everyone in your organization to access.
  4. Click Save.

Phase 2: Creating Security Tokens and Servers in Okta

Step A: Create an SSWS Token

We need a secure way for MuleSoft to talk to Okta's API (management tasks).

  1. Go to Security -> API -> Authorization Servers.
  2. Switch to the Tokens tab.
  3. Click Create Token.
  4. Give your token a name and click Create Token.

Important: Copy this token value immediately. You won't be able to see it again.

Step B: Create an Authorization Server

Now we define who is actually authorizing the requests.

  1. Navigate to Security -> API -> Authorization Servers.
  2. Click Add Authorization Server.
  3. Enter a Name.
  4. Set the Audience to api://default.
  5. Click Save.

Step C: Define the Scope

  1. Click on the name of the Authorization Server you just created.
  2. Go to the Scopes tab and click Add Scope.
  3. In the popup:
    • Name: Enter mulescope.
    • Metadata: Check the box for "Include in metadata."
  4. Click Create.

Phase 3: Connecting Okta to MuleSoft Anypoint Platform

Now we bridge the two platforms together using the Dynamic Client Registration feature.

Step A: Register the Identity Provider

  1. Log into MuleSoft Anypoint Platform.
  2. Navigate to Access Management.
  3. Select Client Provider from the menu.
  4. Click Add Client Provider and choose OpenID Connect Dynamic Client Registration.

Step B: Retrieve Okta Metadata

We need to tell MuleSoft where to find Okta's details.

  1. Back in Okta, go to Security -> API -> Authorization Servers.
  2. Select your custom server.
  3. Click the metadata URL link to view the JSON data. Keep this tab open.

Step C: Fill the Dynamic Client Registration Form

In MuleSoft, fill out the form using the data from the Okta metadata JSON:

  • Issuer & Client Registration URLs: Paste these exactly from your metadata values.
  • Authorization Header: Click "Advanced Settings" below the Client Registration URL.
    • The value must be your SSWS token with a specific prefix.
    • Format: SSWS YourTokenValue (Ensure there is a single space after SSWS).
  • Client ID & Secret: Paste the values you copied from your Okta Web App creation (Phase 1).
  • URLs: Fill in the Authorization URL, Token URL, and Token Introspection URL from your metadata.

Step D: Activate the Policy in Your Environment

  1. Still in Access Management, go to Business Groups.
  2. Select the Environment (e.g., Sandbox) where you want to enforce this policy.
  3. In the settings, locate Client Provider.
  4. Select the provider you just created (e.g., 'Mule Trains Okta').

Phase 4: Enforcing the Policy in API Manager

Now that the connection exists, let's force the API to use it.

  1. Go to API Manager in Anypoint Platform.
  2. Click on the Active API you want to secure.
  3. Select Policies -> Apply New Policy.
  4. Choose OpenId Connect access token enforcement policy.
  5. Select the latest version (e.g., 1.6.0) and click Configure Policy.

Configuration

  • Scopes: Enter mulescope (This matches the scope we created in Okta).
  • Leave other parameters as default.
  • Click Apply.

Note: If you don't see the OpenID policy, go to the API settings in API Manager and ensure the correct Client Provider is selected.

Updating Your RAML

Don't Forget: After applying the policy, you must update your RAML in the API Specification to reflect the security requirements. Here is a standard snippet to include in your RAML:

securitySchemes:
  oauth_2_0:
    type: OAuth 2.0
    description: OAuth 2.0 with Okta
    describedBy:
      headers:
        Authorization:
          description: |
            Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
          type: string
      responses:
        401:
          description: Bad or expired token.
settings:
  authorizationUri: https://{yourOktaDomain}/oauth2/default/v1/authorize
  accessTokenUri: https://{yourOktaDomain}/oauth2/default/v1/token
  authorizationGrants: [client_credentials]

Phase 5: Registering the API and Testing

Step A: Register with Okta via Exchange

  1. Go to Mule Exchange (or your developer portal).
  2. Select the API you are securing.
  3. Click Request Access.
  4. Select Create new application.
  5. Provide an App Name.
  6. Select Authorization Code Grant and Client Credentials Grant.
  7. Click Create.

Important: This will generate a new Client ID and Secret specific to this API instance.

Group Assignment Note: In Okta, find this new application, click the gear icon, and assign it to the relevant groups (e.g., "Assign to Everyone").

Step B: Generate an Access Token (Postman)

  1. Open Postman.
  2. Create a POST request to your Token URL (found in your Okta metadata).
  3. Headers: Set Content-Type to application/x-www-form-urlencoded.
  4. Auth: Use Basic Authentication.
    • Username: The Client ID from the Exchange registration (Step A above).
    • Password: The Client Secret from the Exchange registration.
  5. Body (x-www-form-urlencoded):
    • grant_type: client_credentials
    • scope: mulescope
  6. Send the request. You should receive a Bearer Token.

Step C: Test the API

Now, call your actual MuleSoft API endpoint. Add the token to your headers:

  • Key: Authorization
  • Value: Bearer {your_generated_token}

Troubleshooting Common Errors

Error Message Fix
unauthorized_client "The client is not authorized to use the provided grant type." Check your application in Okta. Ensure "Client Credentials" is checked in the Grant Type settings.
access_denied "Policy evaluation failed for this request." Go back to your integration app settings and update the policy configuration to ensure scopes match.

You have now successfully linked Okta OAuth 2.0 with the MuleSoft Anypoint Platform!

Tags:
Post a Comment (0)
Previous Post Next Post