Use OAuth2 to protect API calls

[vliefooghe]

We are willing to use OpenIDM with a100% API use, for user creation and life-cycle and role management. But our customer would like to use OAuth2 to authenticate and authorize the API calls.
Would it be possible to add this feature for authentication or authorization ?

[vharseko]

• The Trusted Servlet Filter Sample
• Trusted Servlet Filter Sample
• OPENAM_SESSION Module Configuration Options
• docs: Add OAUTH authentication module documentation #136
• docs: Add OPENID_CONNECT authentication module documentation #137
• docs: Add SOCIAL_PROVIDERS authentication module documentation #138

[vliefooghe]

That's really good news ! Is there a target for 7.0.3. release ? Could I help in testing or whatever ?

[vharseko]

Functionality is available in 7.0.2 missing documentation added

[vharseko]

OpenIDM (v7.0.3-SNAPSHOT) already ships with built-in OAuth2 and OpenID Connect (OIDC) authentication modules in openidm-authnfilter. The work needed is primarily configuration — enabling and wiring the correct auth module in authentication.json, provisioning managed user records linked to OAuth subjects, and assigning the right roles. No core Java code changes are required for the common cases.

---

Architecture

API Client ──(1) get token──▶ OAuth2 Authorization Server
                                     │
API Client ──(2) Bearer token──▶ OpenIDM (/openidm/*)
                                     │
                              Auth Filter (authnfilter)
                                     │
                    ┌────────────────┴──────────────┐
                    │  OAUTH or OPENID_CONNECT       │
                    │  auth module                   │
                    └──────────┬─────────────────────┘
                               │ (3) validate token
                               ▼
                    OAuth2 Authorization Server
                    (userinfo endpoint)
                               │
                    (4) subject returned
                               │
                    ┌──────────▼────────────┐
                    │  query managed/user   │
                    │  (or managed/oauth)   │
                    │  by OAuth subject     │
                    └──────────┬────────────┘
                               │
                    (5) roles resolved → request authorized

---

Recommended OAuth2 Flow for Headless / Pure-API Use

For 100% API usage with no browser interaction, use the OAuth2 Client Credentials Grant (RFC 6749 §4.4):

POST /oauth2/token
  grant_type=client_credentials
  &client_id=<id>
  &client_secret=<secret>
  &scope=<scopes>

→ {"access_token": "...", "token_type": "Bearer", "expires_in": 3600}

The client then calls OpenIDM with:

Authorization: Bearer <access_token>

---

Step-by-Step Implementation Plan

Phase 1 — Set Up the OAuth2 Authorization Server

Choose an AS. The existing code uses a userinfo endpoint for token validation, so any standards-compliant AS works:

• OpenAM
• Keycloak
• Okta / Azure AD / Auth0
• Any AS supporting RFC 7662 Token Introspection or the OIDC userinfo endpoint

Configuration steps:

1. Create an OAuth2 Client (Resource Server) in the AS representing OpenIDM.
2. Create API client credentials (client_id / client_secret) for each calling application.
3. Define scopes (openidm:read, openidm:write, etc.) to later enforce fine-grained authorization.
4. Enable the userinfo endpoint (required by the built-in OAuthResolverImpl).
5. Make note of:
   • authorization_endpoint (not used for client_credentials, but required in config)
   • token_endpoint
   • userinfo_endpoint
   • well-known (for OIDC auto-discovery)

---

Phase 2 — Configure OpenIDM Authentication Module

Edit openidm-zip/src/main/resources/conf/authentication.json.

Option A: OAuth2 (userinfo-based token validation)

Use this when the AS is NOT OpenID Connect or you want explicit control over the userinfo endpoint call.

{
  "serverAuthContext": {
    "sessionModule": {
      "name": "JWT_SESSION",
      "properties": {
        "keyAlias": "&{openidm.https.keystore.cert.alias}",
        "privateKeyPassword": "&{openidm.keystore.password}",
        "keystoreType": "&{openidm.keystore.type}",
        "keystoreFile": "&{openidm.keystore.location}",
        "keystorePassword": "&{openidm.keystore.password}",
        "maxTokenLifeMinutes": "120",
        "tokenIdleTimeMinutes": "30",
        "sessionOnly": true,
        "isHttpOnly": true
      }
    },
    "authModules": [
      {
        "name": "OAUTH",
        "properties": {
          "authTokenHeader": "Authorization",
          "authResolverHeader": "X-OAuth-Provider",
          "resolvers": [
            {
              "name": "my-as",
              "type": "OAUTH",
              "userinfo_endpoint": "https://as.example.com/oauth2/userinfo",
              "authenticationId": "sub",
              "client_id": "openidm-resource-server",
              "client_secret": "secret"
            }
          ],
          "queryOnResource": "managed/user",
          "propertyMapping": {
            "authenticationId": "oauthSubject",
            "userRoles": "authzRoles"
          },
          "defaultUserRoles": ["openidm-authorized"],
          "augmentSecurityContext": {
            "type": "text/javascript",
            "source": "require('auth/customAuthz').setProtectedAttributes(security)"
          }
        },
        "enabled": true
      },
      {
        "name": "INTERNAL_USER",
        "properties": {
          "queryId": "credential-internaluser-query",
          "queryOnResource": "repo/internal/user",
          "propertyMapping": {
            "authenticationId": "username",
            "userCredential": "password",
            "userRoles": "roles"
          },
          "defaultUserRoles": []
        },
        "enabled": true
      }
    ]
  }
}

How the OAUTH module works (from source code):

Config Property	Purpose
authTokenHeader	HTTP header carrying the Bearer token (use "Authorization")
authResolverHeader	HTTP header indicating which resolver/provider to use (e.g. "X-OAuth-Provider")
resolvers[].userinfo_endpoint	URL the module calls with Authorization: Bearer <token> to validate it
resolvers[].authenticationId	Field name in the userinfo response that holds the user's unique ID (commonly "sub")
queryOnResource	OpenIDM resource where the resolved subject is looked up (e.g. managed/user)
propertyMapping.authenticationId	Field on the managed user object that stores the OAuth subject
propertyMapping.userRoles	Field on the managed user object that determines roles
defaultUserRoles	Roles assigned to all successfully authenticated OAuth users

Option B: OpenID Connect (OIDC, with auto-discovery)

Preferred when the AS supports OIDC (Keycloak, ForgeRock AM, Okta, Azure AD, etc.). This uses the well-known endpoint for auto-discovery.

{
  "name": "OPENID_CONNECT",
  "properties": {
    "resolvers": [
      {
        "name": "my-oidc-provider",
        "type": "OPENID_CONNECT",
        "well-known": "https://as.example.com/.well-known/openid-configuration",
        "client_id": "openidm-client",
        "client_secret": "secret",
        "scope": ["openid", "profile", "email"],
        "authenticationId": "sub",
        "enabled": true
      }
    ],
    "queryOnResource": "managed/user",
    "openIdConnectHeader": "authToken",
    "propertyMapping": {
      "authenticationId": "oauthSubject",
      "userRoles": "authzRoles"
    },
    "defaultUserRoles": ["openidm-authorized"],
    "augmentSecurityContext": {
      "type": "text/javascript",
      "source": "require('auth/customAuthz').setProtectedAttributes(security)"
    }
  },
  "enabled": true
}

---

Phase 3 — Extend the Managed User Schema

The managed user schema (managed.json) must store the OAuth subject (sub) so OpenIDM can look up the right account after token validation.

Add a field to the managed user object in openidm-zip/src/main/resources/conf/managed.json:

{
  "name": "oauthSubject",
  "type": "string",
  "title": "OAuth Subject",
  "viewable": false,
  "searchable": true,
  "userEditable": false
}

Also add a query to repo.jdbc.json (or repo.orientdb.json) so OpenIDM can query by oauthSubject:

"credential-oauth-query": {
    "query": "SELECT * FROM ${unquotedtable} WHERE oauthSubject = ${uid}",
    "table": "managed_user",
    "useType": "managed/user"
}

Alternatively, use the generic filter query (_queryFilter=oauthSubject eq "<sub>") which works without schema changes.

---

Phase 4 — Create Managed User Accounts for API Clients

Each OAuth2 API client (or human user) needs a corresponding managed user entry in OpenIDM with:

• The OAuth sub claim stored in oauthSubject
• The appropriate authzRoles set

Create via API:

curl -X POST https://openidm.example.com/openidm/managed/user \
  -H "Content-Type: application/json" \
  -H "X-OpenIDM-Username: openidm-admin" \
  -H "X-OpenIDM-Password: openidm-admin" \
  -d '{
    "userName": "api-client-1",
    "oauthSubject": "client-credentials-sub-from-as",
    "authzRoles": [
      { "_ref": "repo/internal/role/openidm-admin" }
    ]
  }'

For the client_credentials flow, the sub claim in the userinfo response is typically the client_id. Verify this with your AS.

---

Phase 5 — Role-Based Authorization

OpenIDM's built-in roles control what operations are allowed on each resource:

Role	Permissions
openidm-admin	Full access to all resources
openidm-authorized	Standard end-user access (read own profile)
openidm-cert	Certificate-based access
openidm-reg	Self-registration access
Custom roles	Defined via managed/role objects

Recommended approach for API clients:

1. Create a dedicated managed role for each type of API consumer:

   curl -X POST https://openidm.example.com/openidm/managed/role \
     -H "Content-Type: application/json" \
     -H "X-OpenIDM-Username: openidm-admin" \
     -H "X-OpenIDM-Password: openidm-admin" \
     -d '{
       "name": "api-user-manager",
       "description": "Can create and manage users via API"
     }'

2. Assign the role to the API client's managed user account.

3. Configure access control using OpenIDM's policy engine (policy.json or access.js). The access.js script (in openidm-zip/src/main/resources/script/) controls which roles can perform which CREST operations on which resources.

---

Phase 6 — API Call Flow (End-to-End)

Once configured, the API client flow is:

# Step 1: Get an access token from the AS
TOKEN=$(curl -s -X POST https://as.example.com/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=my-api-client" \
  -d "client_secret=my-secret" \
  -d "scope=openid" \
  | jq -r .access_token)

# Step 2: Call OpenIDM API with the Bearer token
# (also send the provider header so OpenIDM knows which resolver to use)
curl -X GET https://openidm.example.com/openidm/managed/user \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-OAuth-Provider: my-as"

# Step 3: Create a user
curl -X POST https://openidm.example.com/openidm/managed/user \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-OAuth-Provider: my-as" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "newuser",
    "givenName": "New",
    "sn": "User",
    "mail": "newuser@example.com",
    "password": "Passw0rd!"
  }'

# Step 4: List roles
curl -X GET "https://openidm.example.com/openidm/managed/role?_queryFilter=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-OAuth-Provider: my-as"

---

Phase 7 — Optional: JWT Introspection for Better Performance

The current OAuthResolverImpl makes a synchronous HTTP call to the userinfo endpoint on every request. For high-throughput API scenarios, this is a bottleneck.

Options to mitigate:

1. Use OIDC with JWT Access Tokens: If the AS issues signed JWT access tokens (RFC 9068), OpenIDM can validate them locally using the AS's JWKS endpoint — no round-trip per request. This requires configuring the OPENID_CONNECT module's well-known endpoint (which provides jwks_uri).

2. Cache userinfo responses: Add a caching layer in a custom augmentSecurityContext script that caches the token→subject mapping in a short-lived in-memory store.

3. Use Token Introspection (RFC 7662): Some AS implementations support introspection as an alternative to userinfo. Similar in performance but returns richer metadata. Would require extending OAuthResolverImpl.

---

Phase 8 — Disable Unused Authentication Modules

For pure OAuth2 API access with no UI, disable the modules that are no longer needed to reduce the attack surface:

{ "name": "STATIC_USER",   "enabled": false },
{ "name": "MANAGED_USER",  "enabled": false }

Keep INTERNAL_USER enabled if you need an emergency backdoor admin account.
Keep CLIENT_CERT if mutual TLS (mTLS) is used.

---

Configuration File Checklist

File	Change
conf/authentication.json	Add OAUTH or OPENID_CONNECT auth module, configure resolvers
conf/managed.json	Add oauthSubject field to managed user schema
conf/access.js	Configure role-based access per resource/operation
conf/repo.jdbc.json / conf/repo.orientdb.json	Add credential-oauth-query if needed
conf/policy.json	(Optional) Add policy rules for OAuth-authenticated users
script/auth/customAuthz.js	(Optional) Customize authorization logic in augmentSecurityContext

---

Key Source Files for Reference

File	Description
openidm-authnfilter/src/main/java/.../auth/modules/oauth/OAuthModule.java	Core OAuth auth module (implements AsyncServerAuthModule)
openidm-authnfilter/src/main/java/.../auth/modules/oauth/resolvers/OAuthResolverImpl.java	Token validation via userinfo endpoint
openidm-authnfilter/src/main/java/.../auth/modules/IDMAuthModuleWrapper.java	Property mapping, role resolution, augmentation scripts
openidm-zip/src/main/resources/conf/authentication.json	Main authentication configuration (to be edited)
openidm-zip/src/main/resources/conf/managed.json	Managed object schema (add oauthSubject field)
openidm-zip/src/main/resources/script/access.js	Role-based access control rules
openidm-zip/src/main/resources/conf/endpoint-oauthproxy.json	OAuth proxy endpoint (for browser-based flows)