Stroom – authentication

Docs: Calling an API

Tue, 17 Jan 2023 00:00:00 +0000

Authentication

In order to use the API endpoints you will need to authenticate. Authentication is achieved 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... or 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....

You will either need to create an API key for your personal Stroom user account or for a shared processing user account. Whichever user account you use it will need to have the necessary permissions for each API endpoint it is to be used with.

To create an API key (token) for a user:

In the top menu, select:

Click Create.
Enter a suitable expiration date. Short expiry periods are more secure in case the key is compromised.
Select the user account that you are creating the key for.
Click OK
Select the newly created API Key from the list of keys and double click it to open it.
Click Copy Key to copy the key to the clipboard.

To make an authenticated API call you need to provide a header of the form Authorization:Bearer ${TOKEN}, where ${TOKEN} is your API Key as copied from Stroom.

Calling an API method with `curl`

This section describes how to call an API method using the command line tool curl as an example client. Other clients can be used, e.g. using python, but these examples should provide enough help to get started using another client.

HTTP Requests Without a Body

Typically HTTP GET requests will have no body/payload Often PUT and DELETE requests will also have no body/payload.

The following is an example of how to call an HTTP GET method (i.e. a method that does not require a request body) on the API using curl.

TOKEN='API KEY GOES IN HERE' \
curl \
  --silent \
  --insecure \
  --header "Authorization:Bearer ${TOKEN}" \
  https://stroom-fqdn/api/node/v1/info/node1a

Example output:

{"discoverTime":"2022-02-16T17:28:37.710Z","buildInfo":{"buildDate":"2022-01-19T15:27:25.024677714Z","buildVersion":"7.0-beta.175","upDate":"2022-02-16T09:28:11.733Z"},"nodeName":"node1a","endpointUrl":"http://192.168.1.64:8080","itemList":[{"nodeName":"node1a","active":true,"master":true}],"ping":2}

Warning

The --insecure argument is used in this example which means certificate verification will not take place. It is recommended not to use this argument and instead supply curl with client and certificate authority certificates to make a secure connection.

TOKEN='API KEY GOES IN HERE' \
curl \
  --silent \
  --cert /path/to/client-cert \
  --key /path/to/client-key \
  --cacert /path/to/ca-cert \
  --header "Authorization:Bearer ${TOKEN}" \
  https://stroom-fqdn/api/some/path

You can either call the API via Nginx (or similar reverse proxy) at https://stroom-fqdn/api/some/path or if you are making the call from one of the stroom hosts you can go direct using http://localhost:8080/api/some/path. The former is preferred as it is more secure.

Requests With a Body

A lot of the API methods in Stroom require complex bodies/payloads for the request. The following example is an HTTP POST to perform a reference data lookup on the local host.

Create a file req.json containing:

{
  "mapName": "USER_ID_TO_STAFF_NO_MAP",
  "effectiveTime": "2024-12-02T08:37:02.772Z",
  "key": "user2",
  "referenceLoaders": [
    {
      "loaderPipeline" : {
        "name" : "Reference Loader",
        "uuid" : "da1c7351-086f-493b-866a-b42dbe990700",
        "type" : "Pipeline"
      },
      "referenceFeed" : {
        "name": "STAFF-NO-REFERENCE",
        "uuid": "350003fe-2b6c-4c57-95ed-2e6018c5b3d5",
        "type" : "Feed"
      }
    }
  ]
}

Now send the request with curl.

TOKEN='API KEY GOES IN HERE' \
curl \
  --json @req.json \
  --request POST \
  --header "Authorization:Bearer ${TOKEN}" \
  http://localhost:8080/api/refData/v1/lookup
(out)staff2

This API method returns plain text or XML depending on the reference data value.

Note

This assumes you are using curl version 7.82.0 or later that supports the --json argument. If not you will need to replace --json with --data and add these arguments:

--header "Content-Type: application/json"
--header "Accept: application/json"

Handling JSON

jq is a utility for processing JSON and is very useful when using the API methods.

For example to get just the build version from the node info endpoint:

TOKEN='API KEY GOES IN HERE' \
curl \
    --silent \
    --insecure \
    --header "Authorization:Bearer ${TOKEN}" \
    https://localhost/api/node/v1/info/node1a \
  | jq -r '.buildInfo.buildVersion'
(out)7.0-beta.175

Docs: User Accounts

Fri, 01 Nov 2024 00:00:00 +0000

TODO

The Users, Groups and Permissions screens are undergoing significant change in Stroom v7.6. Therefore this section will be updated with more detail in v7.6.

Note

If 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… (e.g. Azure Active Directory or AWS Cognito) then all user accounts are managed within that 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… and the Manage Accounts screen in Stroom will not be available. For more details about external Identity Providers, see Open ID Connect.

Accounts vs Stroom Users

See Accounts vs Users for details on the difference between a Stroom User Account and a Stroom User.

Creating User Accounts

User accounts can only be created by a user that holds 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....

Create a new user account by selecting

from the main menu.

As a minimum a user account must have a unique identifier that will be used to identify them in Stroom.

If the user’s email address is added then Stroom will be able to email the user to reset their password. This functionality is configured using the properties starting with this prefix stroom.security.identity.email..

Account Flags

User accounts have a number of flags that can be set by an administrator or automatically by Stroom.

Enabled - Enables/disables the account. A disabled account cannot login. Useful for disabling a user that is temporarily on leave.
Locked - Set when a user has too many failed login attempts (controlled by the property stroom.security.identity.failedLoginLockThreshold). Can be un-set by a user with Manage Users 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.... A locked account cannot login.
Inactive - Set automatically in one of these cases:
- A brand new account has not been used for a duration greater than stroom.security.identity.passwordPolicy.neverUsedAccountDeactivationThreshold.
- An account has not been used for a duration greater than stroom.security.identity.passwordPolicy.unusedAccountDeactivationThreshold. An inactive account cannot login.

Docs: Authentication

Fri, 09 Jul 2021 00:00:00 +0000

Docs: Token Authentication

Fri, 30 Dec 2022 00:00:00 +0000

As an alternative to using SSL certificates 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

Docs: Setting up Stroom with an Open ID Connect IDP

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

Warning

This section is currently work in progress so may contain incorrect information.

Docs: Login

Fri, 09 Jul 2021 00:00:00 +0000

Assumptions

The following assumptions are used in this document.

for manual login, we will log in as the user admin whose password is set to admin and the password is pre-expired
for PKI Certificate login, the Stroom deployment would have been configured to accept PKI Logins

Within the Login panel, enter admin into the User Name: entry box and admin into the Password: entry box as per

Stroom UI Login - logging in as admin

When you press the Login button, you are advised that your user’s password has expired and you need to change it.

Stroom UI Login - password expiry

Press the OK button and enter the old password admin and a new password with confirmation in the appropriate entry boxes.

Stroom UI Login - password change

Again press the OK button to see the confirmation that the password has changed.

Stroom UI Login - password change confirmation

On pressing Close you will be logged in as the admin user and you will be presented with the Main Menu (Item Tools Monitoring User Help), and the Explorer and Welcome panels (or tabs).

Stroom UI Login - user logged in

We have now successfully logged on as the admin user.

The next time you login with this account, you will not be prompted to change the password until the password expiry period has been met.

To login using a PKI Certificate, a user should have their Personal PKI certificate loaded in the browser (and selected if you have multiple certificates) and the user just needs to go to the Stroom UI URL, and providing you have an account, you will be automatically logged in.

Docs: Logout

Fri, 09 Jul 2021 00:00:00 +0000

Assumptions

The following assumptions are used in this document.

the user admin is currently logged in

Log out of UI

To log out of the UI, select the User item of the Main Menu and to bring up the User sub-menu.

Stroom UI - User Sub-menu

and select the Logout sub-item and confirm you wish to log out by selecting the OK button.

Stroom UI - User Logout

This will return you to the Login page.

Stroom UI Login Page

Stroom – authentication

Docs: Calling an API

Authentication

Calling an API method with curl

HTTP Requests Without a Body

Warning

Requests With a Body

Note

Handling JSON

Docs: User Accounts

TODO

Note

Accounts vs Stroom Users

Creating User Accounts

Account Flags

Docs: Authentication

Docs: Token Authentication

Docs: Setting up Stroom with an Open ID Connect IDP

Warning

Docs: Login

Assumptions

Manual Login

PKI Certificate Login

Docs: Logout

Assumptions

Log out of UI

Calling an API method with `curl`