API Key Authentication

Tags:

• authentication
• token

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.

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.