Stroom – token

Docs: Sessions and Tokens

Wed, 29 Jul 2026 00:00:00 +0000

Signing in to Stroom creates a session, and Stroom issues tokens that are used to prove who a user is, both to Stroom itself and between the nodes of a cluster. This page describes how sessions and tokens are ended, both by users for themselves and by administrators.

Ending Your Own Sessions

Any user can end their own sessions other than the one they are currently using, by selecting

from the main menu.

This is useful after signing in from a machine that is no longer under their control. It applies across every browser and device, and across every node in the cluster.

Completing a password reset also ends all of that user’s sessions, including the one being used at the time. See Signing In.

The User Access Screen

A user holding the Manage Users or Administrator Application permission Application permission This is a permission that is not specific to a single document. It applies to all documents or is not related to documents in any way.Click to see more details... can see and end the access held by other users by selecting

from the main menu.

The screen lists users along with how many sessions and tokens each currently holds, and shows the sessions held for the selected user across every node in the cluster.

Two actions are available.

End this user’s sessions and revoke their tokens does exactly that, across the whole cluster rather than just the node serving the request. It does not withdraw their access: the account is untouched and they can sign in again.
Open this user opens the selected user, where they can be disabled. This is offered alongside revocation because the two are easily confused and do quite different things, as described below.

Revoking, Disabling, and the Difference between Them

Three actions are easy to confuse, and each does something different. To stop someone using Stroom completely and immediately, you need the last two together.

Action	Ends sessions and tokens	Prevents signing in again
End sessions and revoke tokens, on the User Access screen	Yes	No
Disable the Stroom User User Refers to a Stroom User that is linked to either an Account in Stroom’s internal Identity Provider or a user account in an external Identity Provider. A Stroom User is primarily concerned with authorisation (i.e. application/document permissions and group memberships) rather than authentication, though disabling one also refuses that person at authentication and ends any access they currently hold.Click to see more details..., on the Users screen	Yes	Yes
Disable the account, on the Manage Accounts screen	No	Yes

Ending sessions and revoking tokens does both of those things and no more. It deliberately leaves the account alone, so the password still works and the user can sign in again. Every token revoked this way is dead permanently, but their access as a whole is not withdrawn. It forces re-authentication rather than shutting anybody out, which makes it the right action when you want to be certain that whoever is currently signed in has to prove who they are again.

Disabling the Stroom User User Refers to a Stroom User that is linked to either an Account in Stroom’s internal Identity Provider or a user account in an external Identity Provider. A Stroom User is primarily concerned with authorisation (i.e. application/document permissions and group memberships) rather than authentication, though disabling one also refuses that person at authentication and ends any access they currently hold.Click to see more details... does everything the above does, and additionally refuses them at authentication, whether they are signing in interactively or presenting a token. This is the action to take when someone must be stopped, and is what the Open this user button on the User Access screen is for.

Disabling the account, which only applies when Stroom is its own Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details..., stops them authenticating at all. It does not disturb a session that is already running. See User Accounts.

Warning

This matters most when Stroom is configured to use an external Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details…. Revoking a user’s sessions and tokens does not touch the session they hold with that provider, so their next request is likely to sign them straight back in automatically, without their even being asked for a password.

To prevent access when using an external Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details…, disable the account at that provider, in Stroom, or both.

Token Lifetimes

These are the defaults, and are configurable under stroom.security.identity.token..

Token	Property	Default
Access token	`accessTokenExpiration`	60 minutes
Refresh token	`refreshTokenExpiration`	30 days
Password reset link	`emailResetTokenExpiration`	10 minutes
API key	`defaultApiKeyExpiration`	365 days

Refresh tokens can be used only once, and each use issues a replacement. If a refresh token is presented a second time, which suggests it has been copied, Stroom withdraws that token and every token descended from it.

Docs: Signing Keys

Wed, 29 Jul 2026 00:00:00 +0000

When Stroom acts as its own Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details... it signs the tokens it issues with a key that it creates and replaces by itself. Nodes and Stroom-Proxy check that signature to satisfy themselves that a token really came from Stroom.

This screen exists so that a key believed to have been exposed can be withdrawn. It is not needed for day to day running, because keys are replaced automatically.

Note

This screen requires the Administrator Application permission Application permission This is a permission that is not specific to a single document. It applies to all documents or is not related to documents in any way.Click to see more details…, rather than Manage Users which is enough for most other security screens. Withdrawing a signing key affects everybody using Stroom at once, so it is treated as an application wide action.

Reach the screen by selecting

from the main menu.

What the Screen Shows

Each key is listed with its status and the date it was issued, and nothing else. Nothing that identifies a key or describes its contents is shown, because the stored key includes the private half that produces signatures.

Status	Meaning
Active	New tokens are being signed with this key.
Retired	No longer signing new tokens, but still trusted so that tokens already issued keep working. Shown with the date that trust ends.
Expired	No longer trusted. Removed automatically shortly afterwards.
Revoked	Withdrawn by an administrator. Anything signed with it is already refused.

The active key has no end date. Keys here do not expire on a schedule. Rotation replaces the active key when it is old enough, and only at that point does the key it replaced gain a date on which it stops being trusted.

Automatic Rotation

Stroom replaces the active signing key every stroom.security.identity.token.jwkRotationInterval, which is thirty days by default.

Rotation is invisible to users. The key being replaced continues to be trusted for long enough that every token already signed with it expires naturally, so nobody is signed out and nothing needs to be restarted.

Revoking a Key

Revoking withdraws a key immediately. Any token signed with it stops being accepted, and a replacement signing key is created at the same moment so that Stroom can carry on issuing tokens.

There are two actions.

Revoke withdraws the selected key.
Revoke all withdraws every key that is still trusted, for when a key is believed to have been exposed but it is not known which.

Both actions ask for confirmation first, and the confirmation says what that particular key will cost, because the effect differs enormously between them. Revoking a retired key usually affects a handful of people, while revoking the active key affects everyone.

Warning

Revoking cannot be undone. There is no way to restore trust in a key that has been withdrawn.

Revoke a key only if you believe it may have been exposed. A key revoked by mistake costs everybody a fresh sign in, but no data is lost.

What to Expect after Revoking the Active Key

Everybody using Stroom is signed out and must authenticate again. For people at a browser this is quick, and they will be signed back in as soon as they do so.

Nodes and Stroom-Proxy hold their own tokens signed with the same key, and they replace those tokens as they expire rather than immediately. Parts of the cluster may therefore be unable to talk to one another for up to ten minutes. This resolves itself and needs no intervention, but it is worth expecting rather than being surprised by, and it is a good reason to reserve this action for a suspected compromise.

Revoking a retired or expired key has no such effect, as nothing is signing with it.

Docs: Tokens for API use

Fri, 25 Nov 2022 00:00:00 +0000

Note

We strongly recommend you install jq if you are working with JSON responses from the IDP. It allows you to parse and extract parts of the JSON response. https://stedolan.github.io/jq/

Creating a User Access Token

If a user wants to use the REST API they will need to create a token for authentication/authorisation in API calls. Any calls to the REST API will have the same permissions that the user has within Stroom.

The following excerpt of shell commands shows how you can get an access/refresh token pair for a user and then later use the refresh token to obtain a new access token. It also shows how you can extract the expiry date/time from a token using jq.

get_jwt_expiry() {
  jq \
    --raw-input \
    --raw-output \
    'split(".") | .[1] | @base64d | fromjson | .exp | todateiso8601' \
    <<< "${1}"
}

# Fetch a new set of tokens (id, access and refresh) for the user
response="$( \
  curl \
    --silent \
    --request POST \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=admin-cli' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'scope=openid' \
    --data-urlencode 'username=jbloggs' \
    --data-urlencode 'password=password' \
    'http://localhost:9999/realms/StroomRealm/protocol/openid-connect/token' )"

# Extract the individual tokens from the response
access_token="$( jq -r '.access_token' <<< "${response}" )"
refresh_token="$( jq -r '.refresh_token' <<< "${response}" )"

# Output the tokens
echo -e "\nAccess token (expiry $( get_jwt_expiry "${access_token}")):\n${access_token}"
echo -e "\nRefresh token (expiry $( get_jwt_expiry "${refresh_token}")):\n${refresh_token}"

# Fetch a new access token using the stored refresh token
response="$( \
  curl \
    --silent \
    --request POST \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=admin-cli' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode "refresh_token=${refresh_token}" \
    'http://localhost:9999/realms/StroomRealm/protocol/openid-connect/token' )"

access_token="$( jq -r '.access_token' <<< "${response}" )"
refresh_token="$( jq -r '.refresh_token' <<< "${response}" )"

echo -e "\nNew access token (expiry $( get_jwt_expiry "${access_token}")):\n${access_token}"
echo -e "\nNew refresh token (expiry $( get_jwt_expiry "${refresh_token}")):\n${refresh_token}"

The above example assumes that you have created a user called jbloggs and a client ID admin-cli.

Access tokens typically have a short life (of the order of minutes) while a refresh token will have a much longer life (maybe up to a year). Refreshing the token does not require re-authentication.

Creating a Service Account Token

If you want another system to call one of Stroom’s APIs then it is likely that you will do that using a non-human service account (or processing user account).

Creating a New Client ID

The client system needs to be represented by a Client ID in KeyCloak. To create a new Client ID, assuming the client system is called System X, do the following in the KeyCloak admin UI.

Click Clients in the left pane.
Click Create client.
Set the Client ID to be system-x.
Set the Name to be System X.
Click Next.
Enable Client Authentication.
Enable Service accounts roles.
Click Save.

Note

By enabling Service accounts role, KeyCloak will create a service account user called service-account-system-x. Tokens will be created under this non-human user identity.

Open the Credentials tab and copy the Client secret for use later.

To create an access token run the following shell commands:

response="$( \
  curl \
    --silent \
    --request POST \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_secret=k0BhYyvt6PHQqwKnnQpbL3KXVFHG0Wa1' \
    --data-urlencode 'client_id=system-x' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=openid' \
    'http://localhost:9999/realms/StroomRealm/protocol/openid-connect/token' )"

access_token="$( jq -r '.access_token' <<< "${response}" )"
refresh_token="$( jq -r '.refresh_token' <<< "${response}" )"

echo -e "\nAccess token:\n${access_token}"

Where client_secret is the Client secret that you copied from KeyCloak earlier.

This access token can be refreshed in the same way as for a user access token, as described above.

Using Access Tokens

Access tokens can be used in calls to Stroom’s REST API or its datafeed API. The process of including the token in a HTTP request is described in API Authentication

Docs: API Key Authentication

Wed, 23 Sep 2026 00:00:00 +0000

As an alternative to a certificate or an Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details... token, data can be sent to the /datafeed endpoint using an API Key API Key API Keys are a form of authentication token that are created within Stroom for use by Stroom-Proxy instances or other clients that want to use Stroom’s API. It is an encrypted string that contains details of the user and the expiration date of the token. Possession of a valid API Key for a user account means that you can do anything that the user can do in the user interface via the API.Click to see more details... created within Stroom.

An API Key belongs to a Stroom user, and carries that user’s permissions, so it should be protected as carefully as a password. Create one as described in Calling the API, then attach it to the request with the HTTP header Authorization, exactly as a token would be:

Bearer YOUR_API_KEY_GOES_HERE

API Keys have the form sak_<hash>_<random>, and it is that sak_ prefix that lets Stroom-Proxy tell them apart from Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details... tokens arriving in the same header.

The Flow

Stroom can check an API Key against its own records. Stroom-Proxy holds no user accounts, so it asks its downstream Stroom, or the next Stroom-Proxy in the chain, and caches the answer.

Sending data with an API Key

Two consequences worth knowing when sending to a Stroom-Proxy:

The first request with a given key is slower than the rest, because it waits on the downstream call. Afterwards the key is served from memory for downstreamHost.maxCachedKeyAge.
A key that has been verified before goes on working through a downstream outage, because Stroom-Proxy falls back to its local file of verified keys, for as long as the entry there is younger than downstreamHost.maxPersistedKeyAge. That file survives a restart of the proxy. A key used for the first time during an outage cannot be verified and is refused, though it is not remembered as invalid and will be verified once the downstream returns.

Docs: Token Authentication

Wed, 23 Sep 2026 00:00:00 +0000

As an alternative to using SSL certificates or an API Key for authentication when sending data to the /datafeed endpoint, you can use a JSON Web Token Token Typically refers to an authentication token that may be used for user authentication. A Stroom API Key is a form of authentication token.Click to see more details.... Using a token for authentication requires that Stroom or Stroom-Proxy have been configured with identityProviderType set to EXTERNAL_IDP (see External IDP for details on the configuration for an external IDP and how to generate a token).

To attach a token to the request you just need to set the HTTP header Authorization with a value of the form

Bearer YOUR_TOKEN_GOES_HERE

The Flow

The sending system obtains a token from the Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details... for its own identity, then presents it with each request. Stroom or Stroom-Proxy verifies that token against the IDP’s published signing keys, exactly as it would verify any other bearer token.

Obtaining a token and sending data with it

Tokens are short lived, typically around an hour, so a sender must obtain a fresh one when the old one expires rather than caching one indefinitely.

Stroom – token

Docs: Sessions and Tokens

Ending Your Own Sessions

The User Access Screen

Revoking, Disabling, and the Difference between Them

Warning

Token Lifetimes

See Also

Docs: Signing Keys

Note

What the Screen Shows

Automatic Rotation

Revoking a Key

Warning

What to Expect after Revoking the Active Key

See Also

Docs: Tokens for API use

Note

Creating a User Access Token

Creating a Service Account Token

Creating a New Client ID

Note

Using Access Tokens

Docs: API Key Authentication

The Flow

See Also

Docs: Token Authentication

The Flow

See Also