Integration Tokens

How a machine gets its own long-lived credential for your catalog, from issuing and naming an offline token to seeing what it did and revoking it when the system it belonged to is retired.

Credentials for machines

An ERP that publishes products into your catalog every night has to prove who it is on every call. Giving it a person's username and password looks like a shortcut, and it causes three problems that all surface later. Passwords expire, and the nightly job stops at 3 a.m. People leave, and their account goes with them. And when something publishes a wrong price, the audit trail names a colleague who was asleep at the time.

An integration token belongs to a system and is named after it. Issued as the sections below describe, it can be revoked on its own without affecting anything else. Every OpenEPCIS connector authenticates with one, including the UnoPim route, the ERPNext route and the Odoo add-on.

What the token actually is

The token is an offline token, an OAuth refresh token issued with the offline_access scope, and this is what makes long-running integrations possible. An ordinary refresh token ends with the session that created it, so an integration built on one runs for a few minutes after you set it up and then stops. That failure looks like a bug in the connector, although the connector works as intended.

The integration never sends the offline token to the catalog. It exchanges it at the identity provider for a short-lived access token and uses that. The long-lived value therefore sits in one place, the integration's own configuration, while the credential that travels with every request expires within minutes.

Issuing one

Open Profile in DDM and use the integration-tokens card. It takes you through the identity provider's own login and consent screen and then back to a page that shows the token. Three aspects of this flow are worth knowing before you start.

The identity provider asks for your consent even though you are already logged in. An offline token outlives the session that made it, and possibly the person who made it, so you are asked once, explicitly, to allow that.

The token is shown exactly once. Neither DDM nor the resolver stores it. Afterwards your list keeps a row with the name, the issue time and the time of last use. If you close the page before copying the value, nothing is broken: issue another token and revoke the one you abandoned.

Name the token after the system that uses it. unopim-production and odoo-nightly are useful names, while a name like sven-token-2 defeats the purpose of a per-system token, which is to retire one system without wondering what else you might break. You can supply the name when you start the flow or rename the token afterwards. A flow started without a name produces an unnamed row, and you can name it later.

Issuing a second one: log out first

This step surprises many people, and getting it wrong silently removes the independent revocability that the mechanism exists for.

A token is bound to a session at the identity provider. If you run the flow twice in the same browser without logging out, the second run reuses the session you are already in, and you get two different token values that belong to one session. The list then shows a single row, and revoking that row invalidates both tokens at once, so retiring one system would take down two integrations.

When you need one token per system, end the session between issues by logging out or by running the second flow in a private window. Each run then gets its own session, the list shows one row per token, and revoking one leaves the other running.

Two tokens that already share a session keep working; they just cannot be revoked independently. To fix this, issue fresh tokens with separate sessions and revoke the shared row afterwards.

Putting it into a connector

In the connectors' configuration the token is a single property, the target.offline-token of a connection.

openepcis.connectors.connections.pim1.target.offline-token=<the value>

In a cluster the same key arrives as an environment variable, upper-cased and with every non-alphanumeric character turned into _.

OPENEPCIS_CONNECTORS_CONNECTIONS_PIM1_TARGET_OFFLINE_TOKEN

Keep the token in a Kubernetes secret mounted into the deployment; a properties file on disk is not a safe place for it. How a connector works describes the rest of a connection's configuration.

A token is bound to the realm, the client and the person who issued it. People run into this when they build a second environment: a token issued on one environment does not work on another. Copying the value from a staging deployment into production, or the reverse, produces an authentication failure that looks like a typo. Issue one token per environment.

Seeing what a token has been doing

The list on the Profile page shows metadata only and never shows a token value again. Each row carries the name, the issue time and the last used time, and the last column is the most informative one. A token that has never been used points to an integration that was configured but never started. A token that stopped being used weeks ago points to a system that was retired without anyone revoking its credential, and such a credential should be revoked.

You only see your own tokens. The list is tied to the account that issued them, so you cannot inspect or revoke a colleague's integration tokens, and they cannot inspect or revoke yours.

Each row stands for one session, which is why the previous section matters: if two tokens share a session, the list has nothing that tells them apart.

Revoking

Revoking deletes the offline session behind the token. Since the session is the unit of revocation, this is a second reason to keep one session per token. The integration's next attempt to exchange its token for an access token fails with invalid_grant, and it keeps failing until someone gives the integration a new token. This is intended: a credential you decided to withdraw stops working immediately.

Revoke a token when its system is retired, when the token has been exposed, or when the list shows one nobody can account for. Revoking does not "refresh" a token; there is nothing to refresh, and the integration stops until it is reconfigured.

When the card is not there

The feature is off until a deployment turns it on, and the identity provider's client must be configured for it. If the Profile page shows no integration-tokens card, or the flow reports that it is unavailable, the deployment has not enabled it. An administrator has to enable it; retrying will not help.

Two failures have a specific cause:

  • "This is not an offline token." The flow only hands over offline tokens, because any other refresh token would work for just a few minutes. The client needs the offline_access scope allowed.
  • An expired or unrecognised request. A started flow has to be finished within a short window, ten minutes by default. If you leave the consent screen open over lunch, you have to start again.
Last updated: