Authentication

Every access to the CMS requires authentication. Which method is active is determined by the server configuration (httpAuth, see Operations):

httpAuth	Method
./auth/basic	Basic authentication with account and password (default)
./auth/oidc	OpenID Connect, additionally bearer tokens and still Basic

Independently of this, short-lived tokens and, if configured, header SSO always work.

Without valid authentication, the CMS responds with 401 or 403.

Basic

Account and password are transmitted in the Authorization header (Basic Authentication). The account must exist in cms/users.

curl -u 'CMS_User_01:<password>' https://cms.example.org/schema

const res = await fetch('https://cms.example.org/schema', {
    headers: { Authorization: 'Basic ' + btoa('CMS_User_01:<password>') },
})

If the account does not yet have a password, the one used for this sign-in is stored (see Passwords). This is not possible in OIDC mode: there, Basic only works for accounts that already have a password.

Short-lived tokens

GET /token returns a token as text for the signed-in account. It is valid for 5 minutes and can be used as often as needed during this time as the URL parameter token. This allows, for example, media files to be embedded directly in <img> or <video> elements, which cannot send an Authorization header.

const cms = 'https://cms.example.org'
const auth = { Authorization: 'Basic ' + btoa('CMS_User_01:<password>') }

const token = await fetch(`${cms}/token`, { headers: auth }).then((res) => res.text())

// Read record with ready-to-use file URLs (see data interface, ?exported)
const record = await fetch(`${cms}/data/tutorial/file/<id>?exported`, { headers: auth }).then((res) => res.json())

image.src = `${cms}${record.image.path}?token=${encodeURIComponent(token)}`

Tokens are only held in the server's memory and become invalid after a restart.

OIDC

With httpAuth: "./auth/oidc", the editing application signs in via an OpenID Connect provider, e.g. Keycloak or the NeuroomNet sign-in service. Applications can instead send a bearer token from the provider (Authorization: Bearer …).

In both cases, the CMS looks up the account in cms/users (field account) based on the claim email. With Microsoft ADFS, the email address is read from the access token if necessary.

• If no matching account exists and oidc.autoCreate is set, the CMS creates the account without rights.
• Rights always come from the CMS (account and roles in cms/users), not from the provider. An account that can sign in via OIDC therefore sees nothing until it has been given rights in the CMS.

Configuration (oidc in the server configuration):

Key	Meaning
issuer	URL of the provider
clientId, clientSecret	Credentials of the CMS at the provider
self	own externally reachable URL of the CMS (for the redirect back)
oidcResponseType	response type, default id_token
oidcResource	optional resource(s) for the request
autoCreate	automatically create accounts at first sign-in

Sign-out: /oidcLogout, then redirect to /bye.

Header SSO

For upstream sign-in systems (e.g. F5 BIG-IP), the CMS can trust a header containing the account's email address. So that not just anyone can set this header, a second header must contain a shared secret.

Key in headerSSO	Meaning
emailField	name of the header with the email address (= account)
secretField	name of the header with the secret
secret	expected value of the secret

Header SSO is only active if emailField and secretField are set.

Further endpoints

Endpoint	Result
GET /user	signed-in account: account, authentication method (auth), roles, and names of the rights collections
GET /version	version of the CMS and of the loaded extensions (text)
GET /logon?ret=<url>	After successful sign-in, redirect to <url>, provided this URL is entered as a record in the API cms/apps (field url). This lets applications trigger a sign-in in the browser.