Securing Custom REST API Endpoints

How to secure custom REST API endpoints in IntegrationManager using Basic Auth (partition credentials) or OAuth2 (JWT / opaque tokens).

Overview

When an external system calls IM's REST API (the Camel routes exposed via integration.rest.*), IM must verify who the caller is. Two authentication modes are supported:

Both modes enforce the same authorization rules defined by integration.rest.endpoints.secured, integration.rest.endpoints.roles, and integration.rest.doc.* properties.

Where to Configure

All authentication properties go into your instance's config/application.properties file. REST endpoints are defined as Camel routes in the routes/ directory.

/
├── config/
│   └── application.properties    # ← auth properties go here
├── routes/
│   └── my-rest-api.xml           # ← your REST endpoint routes
├── connections/
│   └── pricefx.json              # ← Pricefx connection (used by Basic Auth)
└── ...

For details on the IM project structure, see Project Structure.

Quick Start

Basic Auth (default):

integration.rest.enabled=true
# auth-mode defaults to "basic"
integration.rest.auth-mode=basic
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
# endpoints.roles defaults to ADMIN
integration.rest.endpoints.roles=ADMIN

OAuth2 with JWT:

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
# clear the default (ADMIN) — accept any authenticated user
integration.rest.endpoints.roles=
integration.rest.auth-mode=oauth2
# token-type defaults to "jwt"
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.issuer-uri=https://{your-idp-domain}/...

That's it — any valid token from your IdP will be accepted. To restrict access to specific roles/scopes, see Authorization Rules below.

Note: The default value for endpoints.roles is ADMIN (used by Basic Auth). When switching to OAuth2, you must either clear it (accept any authenticated user) or set it to a role/scope from your IdP along with roles-claim.

Authentication Modes

1. Basic Auth (Partition Credentials)

This is the default mode. Your external system sends Pricefx partition credentials with every request. IM validates the credentials against the Pricefx partition API using the connection defined in connections/pricefx.json (or via integration.pfx.* properties).

What your external system sends:

POST https://{im-host}/rest/myEndpoint
Authorization: Basic <base64-encoded username:password>
Content-Type: application/json

The username can be in two formats:

• username (e.g. admin) — authenticates against the default partition from the pricefx connection

• partition/username (e.g. company/admin) — authenticates against the specified partition (overrides the connection)

Minimal configuration:

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
# endpoints.roles defaults to ADMIN — caller must have ADMIN role on the partition

With custom role:

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
integration.rest.endpoints.roles=DATAINTEGRATION

2. OAuth2 (JWT)

Your external system obtains a token from your Identity Provider (Azure AD, Okta, Keycloak, etc.) and sends it to IM as a Bearer token. IM validates the token locally using your IdP's public keys — no per-request calls to the IdP.

What your external system sends:

POST https://{im-host}/rest/myEndpoint
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json

What IM needs from you:

• The IdP's issuer URI or JWKS endpoint URL

Minimal configuration

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
integration.rest.endpoints.roles=
integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.issuer-uri=https://{your-idp-domain}/...

Or with a direct JWKS endpoint (preferred — avoids OIDC discovery):

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
integration.rest.endpoints.roles=
integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.jwk-set-uri=https://{your-idp-domain}/.well-known/jwks.json

Property details

Note: If both jwk-set-uri and issuer-uri are set, jwk-set-uri takes precedence for key retrieval. The issuer-uri is still used for issuer validation.

Examples by Identity Provider

Azure AD:

integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.jwk-set-uri=https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys
integration.rest.oauth2.jwt.issuer-uri=https://login.microsoftonline.com/{tenant-id}/v2.0

Okta:

integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.issuer-uri=https://{your-domain}.okta.com/oauth2/default

Keycloak:

integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=jwt
integration.rest.oauth2.jwt.jwk-set-uri=https://{host}/realms/{realm}/protocol/openid-connect/certs
integration.rest.oauth2.jwt.issuer-uri=https://{host}/realms/{realm}

3. OAuth2 (Opaque Token / Introspection)

Instead of validating the token locally, IM forwards it to your IdP's introspection endpoint on every request. The IdP confirms whether the token is valid and returns its scopes.

This mode is useful for testing or when your IdP doesn't expose a JWKS endpoint.

Important — Token format restriction: The Bearer token must conform to the RFC 6750 b64token format. Only the following characters are allowed: A-Z a-z 0-9 - . _ ~ + / and = for padding. Tokens containing other characters (e.g. !, #, @) will be rejected with a 401 Unauthorized error and the message Bearer token is malformed. This affects providers like Salesforce, whose opaque tokens use the format orgId!sessionId. Salesforce tokens are not compatible with this mode.

Minimal configuration:

integration.rest.enabled=true
integration.rest.endpoints.path=/rest
integration.rest.endpoints.secured=true
integration.rest.endpoints.roles=
integration.rest.auth-mode=oauth2
integration.rest.oauth2.token-type=opaque
integration.rest.oauth2.opaque.introspection-uri=https://{your-idp}/oauth2/introspect
integration.rest.oauth2.opaque.client-id=im-client
integration.rest.oauth2.opaque.client-secret={{oauth2.client.secret}}

Authorization Rules

By default, REST endpoints require the ADMIN role (configured via integration.rest.endpoints.roles=ADMIN). To change this, configure audience validation and/or role/scope requirements below.

Audience validation (JWT only)

Ensures the token was issued for your IM instance, not for a different application:

integration.rest.oauth2.jwt.audience=api://my-im-app-id

Restricting by role/scope

For OAuth2 JWT — set the JWT claim containing roles and the required value:

integration.rest.oauth2.jwt.roles-claim=scp
integration.rest.endpoints.roles=im.call

The roles-claim property tells IM where to find roles in the JWT token. It depends on your IdP:

For OAuth2 opaque tokens — roles come from the scope field in the introspection response automatically. No roles-claim needed:

integration.rest.endpoints.roles=im.call

For Basic Auth — roles come from the Pricefx user's role assignments automatically:

integration.rest.endpoints.roles=DATAINTEGRATION

Authorization logic

# REST endpoints — require authentication and specific role
integration.rest.endpoints.secured=true
integration.rest.endpoints.roles=DATAINTEGRATION

# API documentation — public access
integration.rest.doc.secured=false

Role matching is case-insensitive. endpoints.roles=im.call matches a token scope of im.call, IM.CALL, or Im.Call.

Choosing Between OAuth2 and Basic Auth

Recommendation: Use OAuth2 JWT when you have an Identity Provider. Use Basic Auth for simple setups.

Troubleshooting

Tip: Enable logging.level.org.springframework.security=DEBUG in application.properties to see detailed authentication/authorization decisions in the logs.

Complete Property Reference