Machine-to-Machine Client Configuration

Backend services, shop connectors and other integrations can call the OMN APIs without anyone logging in, using the OAuth 2.0 Client Credentials Grant. This page describes how an administrator sets up and operates such a machine-to-machine (M2M) client. How an integration obtains tokens and calls the OMN API is described in Authentication → Machine-to-machine access in the API documentation.

How it works

Each integration gets its own Keycloak client. Keycloak automatically links a technical user, the service account, to that client. You then create an OMN user with the same name, which is where the integration’s OMN permissions are configured.

OMN identifies the caller by the token’s preferred_username claim. For a client credentials token this is always service-account-<client-id>. Every API call made with the client’s token therefore runs as this OMN user, so OMN always knows which integration performed an action: it is recorded under the service-account user name (for example as the user who checked out an asset).

You set up and operate M2M clients yourself: creating clients, granting permissions, storing and rotating secrets, and disabling clients that are no longer needed. Treat a client secret like a password with the permissions of the linked OMN user.

Prerequisites

  • Administrator access to the Keycloak admin console of your OMN installation (https://<OMN_SERVER>/auth), realm OMN. The credentials can be found in the keycloak.env file on the OMN server.

  • An OMN user with permission to manage users (System Configuration → Authentication → Users).

Create a separate client, and therefore a separate OMN user, for every integration. This keeps permissions minimal, makes every action traceable to one integration, and lets you rotate or revoke the access of one integration without affecting the others.

Step 1: Create the client in Keycloak

  1. In the Keycloak admin console, switch to the realm OMN and open Clients.

  2. Click Create client.

  3. General settings:

    • Client type: OpenID Connect

    • Client ID: a descriptive, unique name per integration, for example shop-export. The ID becomes part of the OMN user name (service-account-shop-export) that appears wherever OMN records who performed an action, so choose one that is easy to recognize. Use lowercase letters, digits and hyphens: Keycloak stores user names in lowercase.

    • Name and Description (optional): what the integration does and who owns it.

  4. Capability config:

    • Client authentication: On (confidential client with a secret)

    • Authorization: Off

    • Authentication flow: enable only Service accounts roles. Disable Standard flow, Direct access grants, Implicit flow, OAuth 2.0 Device Authorization Grant and all other flows.

  5. Login settings: leave all URLs empty.

  6. Click Save.

When Service accounts roles is enabled, Keycloak automatically creates the service account user service-account-<client-id>.

Step 2: Check the client scopes

Open the Client scopes tab of the new client and make sure that profile is assigned with the type Default. This scope adds the preferred_username claim, which OMN uses to identify the user. Without it, API calls cannot be attributed to the OMN user.

Keycloak always adds all Default scopes to a token, so the integration does not have to request any scope. You can remove scopes the integration does not need, for example email, but keep profile.

Step 3: Create the OMN user and assign permissions

In OMN, open System Configuration → Authentication → Users and click Add user (see also Users):

  • User Name: exactly service-account-<client-id>, for example service-account-shop-export. OMN links the new user to the existing Keycloak service-account user instead of creating a new one.

  • Password / Confirm password: the form requires a value. Enter any value that satisfies the password policy. It has no effect: Keycloak does not allow passwords for service-account users, so the user can never log in with a password.

  • E-Mail: preferably a functional mailbox of the team that owns the integration, for example shop-export@example.com.

  • First Name / Last Name: optional, for example the name of the integration.

  • Roles / Groups: assign the roles and/or groups the integration actually needs. The integration gets exactly the permissions of this user. Follow the principle of least privilege, and do not assign administrator roles unless the integration really needs them.

Save the user. E-mail, first name, last name and group memberships are synchronized to the Keycloak service-account user.

The Activated switch of the OMN user only controls interactive login. It does not block API access with a client credentials token. To disable an integration, use Keycloak (see Disable or remove an integration).

Step 4 (optional): Set the access token lifespan

A new client inherits the access token lifespan of the realm OMN (for example 36000 seconds, 10 hours). If an integration needs a different lifespan, for example a shorter one for an integration with broad permissions, set it for this client only:

  1. Open Clients → <client> → Advanced in Keycloak.

  2. Scroll to the section Advanced settings (or use Jump to section → Advanced settings).

  3. In the drop-down list next to Access Token Lifespan, change Inherits from realm settings to Expires in.

  4. Enter the lifespan and select the unit, for example 30 Minutes.

  5. Click Save at the bottom of the Advanced settings section.

To return to the realm value, select Inherits from realm settings again and save.

Do not change the realm-wide access token lifespan for an integration. It applies to all clients that inherit it.

Step 5: Hand over the credentials

Open the Credentials tab of the client. Make sure Client Authenticator is set to Client Id and Secret, then copy the Client Secret.

Hand the following over to the developers of the integration, the secret through a secure channel:

  • Token endpoint: https://<OMN_SERVER>/auth/realms/OMN/protocol/openid-connect/token

  • Client ID, for example shop-export

  • Client secret

The integration must store the secret in a secret store, never in source code.

Rotate the client secret

  1. Open Clients → <client> → Credentials in Keycloak.

  2. Click Regenerate next to Client Secret and confirm.

  3. Deploy the new secret to the integration.

By default the previous secret becomes invalid immediately: token requests with it fail with 401 and "error": "unauthorized_client". Plan the rotation together with the deployment of the integration. Access tokens that were issued before the rotation stay valid until they expire.

Disable or remove an integration

  • Disable temporarily: open Clients → <client> → Settings in Keycloak and switch Enabled to Off. Keycloak issues no new tokens for the client until you enable it again.

  • Block new tokens with the current secret: regenerate the client secret (see above). Token requests with the old secret fail immediately.

  • Remove permanently: delete the client in Keycloak (this also deletes the service-account user in Keycloak) and delete the OMN user service-account-<client-id>.

An access token that has already been issued cannot be revoked. OMN accepts an access token as long as its signature is valid and it has not expired; it does not check with Keycloak whether the client has been disabled, its secret regenerated or its users deleted. None of the actions above therefore invalidates access tokens that were issued before: they remain valid until they expire.

If a client secret has been compromised, regenerate the secret or disable the client right away, and take into account that tokens obtained with it can still be used for up to one access token lifespan. For integrations with broad permissions, keep this window short by setting a shorter client-specific lifespan (see Step 4 (optional): Set the access token lifespan).

Find the service-account user in Keycloak

Keycloak does not show service-account users in the Users list or in the user search. To open it, go to Clients → <client> → Service accounts roles and click the link to the service-account user. Do not add credentials (passwords, OTP) to this user: the client secret is its only credential.

Welcome to the AI Chat!

Write a prompt to get started...