MuleSoft OAuth 2.0 Setup

OAuth 2.0 is the industry standard for API authorization. It lets client applications access resources on behalf of users without exposing credentials. MuleSoft acts as both an OAuth 2.0 client (when calling secured external APIs) and an OAuth 2.0 provider (when protecting your own APIs). This topic covers both roles and their setup.

OAuth 2.0 Roles

Resource Owner: The user or system that owns the data.
Client: The application requesting access to the data.
Authorization Server: Issues access tokens after verifying the client's identity.
Resource Server: The API that holds the protected data. Validates tokens before serving requests.

OAuth 2.0 Flow Diagram

       1. Client requests access
Client ──────────────────────────────────► Authorization Server
                                           (MuleSoft / Okta / Keycloak)
       2. Server issues access token
Client ◄──────────────────────────────────
  token = "eyJhbGci..." (expires in 3600s)

       3. Client calls API with token
Client ──── GET /orders ──────────────────► API Gateway (Resource Server)
           Authorization: Bearer eyJhbGci...

       4. Gateway validates token
API Gateway ─────── introspect token ──────► Authorization Server ✓

       5. API serves request
Client ◄──── 200 OK { orders: [...] } ────── Mule Application

OAuth 2.0 Grant Types

Client Credentials Grant (Most Common for Integrations)

No user is involved. The client application authenticates using its own client ID and client secret. Ideal for server-to-server integrations where a system calls another system.

Step 1: Get access token
POST https://auth.mycompany.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=a1b2c3d4
&client_secret=z9y8x7w6
&scope=read:orders write:orders

Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type":   "Bearer",
  "expires_in":   3600,
  "scope":        "read:orders write:orders"
}

Step 2: Use token in API call
GET /orders
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Authorization Code Grant (User-Facing Apps)

A user logs in through a browser, grants permission, and an auth code is issued. The client exchanges the code for an access token. Used for web and mobile apps where a real user grants consent.

1. App redirects user to login page:
   GET /oauth/authorize?client_id=a1b2&response_type=code&redirect_uri=https://app.com/callback

2. User logs in and approves → Authorization Server redirects:
   https://app.com/callback?code=AUTHCODE123

3. App exchanges code for token:
   POST /oauth/token
   grant_type=authorization_code&code=AUTHCODE123&client_id=a1b2&client_secret=z9y8

4. Server issues access token.

Calling OAuth-Protected APIs from MuleSoft

When your Mule application calls an external API protected by OAuth 2.0, configure the HTTP Request connector with an OAuth 2.0 token provider. MuleSoft fetches the token automatically, caches it, and refreshes it before expiry.

HTTP Request with OAuth 2.0 Client Credentials

HTTP Request Connector Configuration:
  Name: Salesforce_OAuth_Config
  Authentication: OAuth 2.0 Client Credentials
    Client ID:     ${oauth.clientId}
    Client Secret: ${oauth.clientSecret}
    Token URL:     https://login.salesforce.com/services/oauth2/token
    Scopes:        api refresh_token
    Response Access Token: #[payload.access_token]
    Token Expiry:  #[payload.expires_in]

In the flow:
[HTTP Request: GET /services/data/v60.0/sobjects/Contact]
  Config: Salesforce_OAuth_Config
  (MuleSoft automatically includes "Authorization: Bearer {token}" header)
  (automatically refreshes token when it expires)

Protecting Your API with OAuth 2.0 (MuleSoft as Resource Server)

Apply the OAuth 2.0 Access Token Enforcement policy in API Manager to protect your Mule API. The gateway validates every incoming token against the authorization server before passing requests to your application.

OAuth 2.0 Policy in API Manager

Policy: OAuth 2.0 Access Token Enforcement
  Authorization Server:   https://auth.mycompany.com
  Token Introspection URL: https://auth.mycompany.com/oauth/introspect
  Scopes:
    - read:orders   (required for GET endpoints)
    - write:orders  (required for POST/PUT/DELETE endpoints)

Validation behavior:
  Request with valid token and correct scope → 200 OK ✓
  Request with expired token                → 401 Unauthorized ✗
  Request with valid token but wrong scope  → 403 Forbidden ✗
  Request with no token                    → 401 Unauthorized ✗

JWT Token Validation

Many OAuth 2.0 implementations issue JWT (JSON Web Token) tokens. JWTs are self-contained — the gateway can validate them locally without calling the authorization server for every request. This reduces latency significantly in high-volume APIs.

JWT Structure

JWT = Header.Payload.Signature

Header (base64 decoded):
{ "alg": "RS256", "typ": "JWT" }

Payload (base64 decoded):
{
  "sub":   "client-a1b2c3",
  "scope": "read:orders",
  "iat":   1705315000,   (issued at)
  "exp":   1705318600    (expires at — 1 hour later)
}

Signature: cryptographic proof the token was issued by the auth server.
  Validated using the auth server's public key.
  If the signature is valid, the token is genuine (not forged).

API Manager Policy: JWT Validation
  JWT Origin:    HTTP Authorization Header (Bearer token)
  Signing Method: RSA
  JWK URL:       https://auth.mycompany.com/.well-known/jwks.json
  Clock Skew:    10 seconds (allows minor time differences between servers)

Token Refresh and Caching

Access tokens expire (typically in 1 hour). Refresh tokens last much longer (days or weeks) and let you get a new access token without user re-authentication. MuleSoft's OAuth 2.0 client configuration handles refresh automatically. Set a buffer time (e.g., 60 seconds before expiry) so the token refreshes before it expires during a long-running flow.

Token Lifecycle:
  t=0h:00m: Token issued (expires in 60 minutes)
  t=0h:59m: MuleSoft detects token expires in 60 seconds
            → automatically calls token endpoint
            → gets new token
  t=1h:00m: Old token expires (new token already in use)
  (no interruption to API calls during refresh)

Security Best Practices for OAuth 2.0

Always use HTTPS for all OAuth endpoints and API calls. Tokens transmitted over HTTP can be stolen.
Store client secrets in Anypoint Secrets Manager, not in code or plain-text configuration files.
Use the minimum required scopes. Request only the permissions your application actually needs.
Set short token expiry times (1 hour or less) in production. Shorter tokens reduce the window of damage if a token is compromised.
Validate all JWT claims — especially expiry (exp), issuer (iss), and audience (aud) — not just the signature.

Previous lesson

Back to course

Next lesson