Authentication methods for REST API

The REST API supports different methods of authentication. This section describes necessary configuration and methods.

1 Session Identification

When using the REST API, a session is identified by the session secret cookie and the session id, which must be sent as query parameter sid. This ensures that

  • A session can never be fully identified by URLs (because the session secret is not part of the URL)
  • One client may have multiple sessions. They share the same session secret, but use different session ids

2 Authentication with credentials

To login with credentials, the client must

POST /rest/auth/login
  "login": ...,
  "password": ...

The response will be of the form

  "sid" : "1022",
  "user" : {
    "id" : 34,
    "description" : "",
    "login" : "editor",
    "email" : "",
    "firstName" : "Max",
    "lastName" : "No-Publish"
  "responseInfo" : {
    "responseCode" : "OK",
    "responseMessage" : "Successfully performed login"

Note that the “User-Agent” has to be set in the header of the request as it will be saved in the session, otherwise the login will fail.

Additionally, the session secret cookie will be set to the client.

3 SSO with Keycloak

3.1 Configuration

Activate the Keycloak feature and add configuration for user creation callbacks and initial groups:


  keycloak: true
  user_created_callback: your.companyname.custom.SsoUserCreated
  sync_groups: true
  init_groups: |
    if(attr.roles.realm CONTAINSONEOF 'admin-user-role',
      if(attr.roles.resource.gcms CONTAINSONEOF 'editor-user-role',

Place the `keycloak.json` generated for the CMS in the UI configuration directory (default: `ui-conf`).

The optional settings user_created_callback is the full class name of a callback implementing SsoUserCreatedCallback. When a new user is created by the SSO process, the callback will be executed with the data of the new user. The attributes map contains the following information:

  • firstname: the “given name” claim in the access token
  • lastname: the “family name” claim in the access token
  • email: the “email” claim in the access token
  • roles: a map containing
    • realm: the list of realm roles for the user
    • resource: a mapping from resource names to the respective resource roles for the user

The init parameter initGroups is an expression that must return the IDs of the initial groups, new users shall be put in. The expression can resolve systemuser attributes via user.* or claims from the access token via attr.* (the most interesting attributes probably being the realm roles attr.roles.realm, and the resource specific roles attr.roles.resource.RESOURCENAME).

For security reasons, it is not possible to add users to groups 1 or 2.

3.2 Client side implementation

The same restrictions apply as for the client side implementation for CAS.

4 Synchronizing group IDs

Setting `sync_groups` to `true` in the Keycloak configuration section will cause synchronization of user groups on every login


  sync_groups: true
Name Description Default
keycloak.init_groups Expression that will return the group IDs for the users. All attributes passed along by the authenticating system will be available in the object attr
keycloak.sync_groups When set to true, groups will be synchronized on every login request, not only when the user is created false

4.1 Restricting group assignments to nodes

In order to restrict group assignments to nodes/channels, the group IDs must be encoded like [groupId]|[nodeId]~[nodeId]~[nodeId]....

The following example shows the definition of the initial groups statically set to the group 17 (restricted to nodes 8 and 11) and the group 18 (not restricted to specific nodes):

  init_groups: '["17|8~11", 18]'

5 Logout

A logout can be performed with the following request

POST /rest/auth/logout/{sid}

in the response, the session secret cookie is removed.