Authentication in EntryStore

EntryStore requires authenticated access to non-public resources. The following sections describe the various possibilities for sending credentials and authenticated requests.

Mechanisms

HTTP Basic

Credentials may be sent using HTTP Basic authentication. HTTP Basic is not active by default and needs to be activated with the following setting:

entrystore.auth.http-basic=on

A request to the following URL triggers a challenge response dialog in web browsers:

GET https://base/auth/basic

However, a login-procedure is not necessary with HTTP Basic as the credentials are sent with every request.

There is no specific logout procedure, but to invalidate the authentication token on the server side the resource at https://base/auth/logout can be called.

To perform unauthenticated requests, credentials must be omitted in the HTTP request header. This may be difficult in web browsers which remember HTTP Basic settings throughout browser sessions; there it helps to simply send wrong credentials to perform a "logout".

Cookies

To avoid logging of credentials in cleartext, the cookie authentication resource only supports POST requests.

To login and receive an authentication token as a cookie, a request has to be sent to the following URL:

POST https://base/auth/cookie

The following HTTP form parameters are required:

• auth_username
• auth_password

The parameter auth_maxage may be supplied to decide about the maximum age (in seconds) of the cookie. Default is 86400 seconds, i.e., 24 hours.

If the login is successful, the server will send a response with a cookie where auth_token is set. The token can be used in consecutive requests to authenticate the client.

The validity of cookie tokens are currently limited to EntryStore sessions. Tokens are stored in memory and will be lost if EntryStore is restarted; authenticated clients have to authenticate again if EntryStore is restarted before the authentication token expires. This will change in the future.

By default the path of the auth cookie is automatically generated based on the base URL. This behavior can be overridden (e.g. for testing purposes) with the following setting:

entrystore.auth.cookie.path=auto (default) or specific path like /

Other settings include the possibility to override security related cookie settings:

entrystore.auth.cookie.httponly=on|off (default: on)
entrystore.auth.cookie.secure=on|off (default: on)
entrystore.auth.cookie.samesite=none|lax|strict (default: strict) if set to "none": "secure" will be set to "on" too as this is a requirement
entrystore.auth.cookie.max-age=max cookie age in seconds; use -1 for session cookie (default: 86400)

SAML 2.0

In order for the SAML authentication to work properly, it is required that EntryStore receives the authenticated user's e-mail address (which is used as unique username in EntryStore) after successful login. This corresponds to the NameID property (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) in SAML which needs to be included in the IDP response.

Configuration

The following settings are required:

entrystore.auth.saml=on|off (default: off)
entrystore.auth.saml.relying-party-id=EntryStoreTest
entrystore.auth.saml.assertion-consumer-service.url=https://base/store/auth/saml
entrystore.auth.saml.idp-metadata.url=https://configserver/saml.xml

The settings for relying-party-id and assertion-consumer-service (ACS) must match the SAML IdP's configuration as a mismatch likely will result in a failed authentication process.

The idp-metadata setting points out a URL which must contain the SAML IdP's metadata in XML format. Both local (file:///) or remote (https://) URLs are supported.

The following optional settings can be used to fine tune the configuration:

entrystore.auth.saml.user-auto-provisioning=on|off (default: off)
entrystore.auth.saml.redirect-method=get|post (default: get)
entrystore.auth.saml.redirect-success.url=<absolute URL> (default: unset)
entrystore.auth.saml.redirect-failure.url=<absolute URL> (default: unset)
entrystore.auth.saml.idp-metadata.max-age (default: 604800; unit: seconds)
entrystore.auth.saml.max-age (default: entrystore.auth.cookie.max-age; unit: seconds)

The parameters for redirection upon success and failure are optional and can be used to redirect the client to the correct application URL after login success or failure, respectively.

IDP Metadata max age specifies after which period of time the IDP metadata should be reloaded from the IDP metadata URL. The metadata is reloaded on demand, i.e., as soon as the first SAML request after metadata expiration occurs.

Google as SAML IdP

Please refer to Google's documentation on how to setup a custom SAML application. After the initial configuration in the Google UI the metadata file can be downloaded an used by EntryStore without further modification.

Google provides a page with possible error conditions for trouble shooting problems with SAML login.

Caveat: if the authenticating client is logged into several Google accounts simultaneously, the SAML IdP may pick the wrong account and respond with a client authentication error because SAML support is not enabled for that specific user. There is currently no reliable way of showing an account chooser the same way as it is possible when authenticating using OAuth 2.0 in Google. The currently recommended workaround is to logout of all Google accounts except for the one that should be used for signing into the service.

ADFS

SAML login has been successfully tested with ADFS. It may be necessary to set the redirect method to post in EntryStore.

CAS and SAML 1.1

This section is valid for both CAS v1-3 and SAML v1.1.

Configuration

The following settings are required:

entrystore.auth.cas=on
entrystore.auth.cas.version=cas1|cas2|cas3|saml11 (default: cas2)
entrystore.auth.cas.server.url=https://localhost:7002/cas/

The URL above is used to construct the login and validation URLs according to the specification. If the login service has a different name/URL the following can be used to override the default behaviour:

entrystore.auth.cas.server.url.login=https://localhost:7002/cas/specialLogin
entrystore.auth.cas.max-age (default: entrystore.auth.cookie.max-age; unit: seconds)

This authentication mechanism requires that all involved SSL-certificates can be validated. If invalid SSL-certificates are to be used (e.g. in testing environments) it may be necessary to activate a TrustManager that permits the use of any SSL-certificate. This can be done in the EntryStore configuration:

entrystore.https.disable-verification=true

To activate auto-provisioning of users (i.e., automatic creation of users that do not yet exist in EntryStore), the following setting must be set to on (default is off).

entrystore.auth.cas.user-auto-provisioning=on

The following settings can be used to redirect the client to application pages which are more useful for the user than the standard EntryStore API:

entrystore.auth.cas.redirect-success.url=<absolute URL> (default: unset)
entrystore.auth.cas.redirect-failure.url=<absolute URL> (default: unset)

Usage

A request to the CAS login resource initiates a CAS-based login:

GET https://base/auth/cas

The client is redirected to the CAS service and after login (successful or not) redirected back to EntryStore which sets - in the case of success - an authentication token as cookie, using the same mechanism as the Cookie login mechanism described above.

Please note that CAS users with username admin cannot login using the CAS authenticator as this particular username is reserved in EntryStore.

The standard logout procedure applies as described further down.

Mapping of CAS users to EntryStore users

Currently, the CAS login mechanism expects EntryStore principals with a username matching the CAS uid. Auto-provisioning of users is planned for a future release. Also, no other information in addition to uid is being used by EntryStore.

Admin user

Initial password

By default the admin user does not have a password set and therefore cannot login. Upon initialization of EntryStore (i.e., when starting the very first time and initializing the store), a password can be set by providing it in the environment variable ENTRYSTORE_ADMIN_PASSWORD. It must consist of at least eight characters, apart from that no restrictions apply.

Temporary password override

The admin password can be temporarily overridden using the following setting in the entrystore.properties configuration:

entrystore.auth.adminpw=<password>

The temporary password provided in the configuration is not persisted into the store.

Password restrictions and rules

The password may consist of any characters, but its length must not exceed 2048 characters.

Specific password rules can be configured using the following settings:

entrystore.auth.password.rule.lowercase=<boolean>   (default: true)
entrystore.auth.password.rule.uppercase=<boolean>   (default: true)
entrystore.auth.password.rule.number=<boolean>      (default: true)
entrystore.auth.password.rule.symbol=<boolean>      (default: false)
entrystore.auth.password.rule.min-length=<integer>  (default: 10)
entrystore.auth.password.rule.custom.1=<regexp>     (default: empty list)
entrystore.auth.password.rule.custom.2=<regexp>
entrystore.auth.password.rule.custom.x=<regexp>

Changing a user's password

A user's password can be changed either by resetting it via email or by setting it in the user's resource. To set a user's password a JSON object with a password property needs to be set (PUT) as user resource:

PUT https://base/store/_principals/resource/1
Content-Type: application/json

{ "password": "newpassword" }

With the following setting EntryStore expects the current password before it can be changed:

entrystore.auth.password.require-current-password=on|off (default: on)

With this setting a user can only change her password when she provides both the current and the new password at the same time. Admin users may change other users' passwords without providing the current password, but must provide their current password when changing their own password.

An example payload including the current password and the new password:

{
  "currentPassword": "currentpassword",
  "password": "newpassword"
}

By default this setting is disabled, which means that users can change their password without providing their current password. This may change in future releases.

Ignoring authentication token for specific requests

It is possible to let EntryStore ignore eventually sent auth_token cookies by appending ignoreAuth to any request. This can be useful for embedding scripts that fetch data from EntryStore and that should ignore eventually existing authentication tokens from other browser tabs/windows.

Refresh of authorization token

After every successful call of an EntryStore endpoint, the authorization token can automatically be refreshed.

This means that a user who is active will not have to login again as long as the user is interacting with EntryStore before the session expires.

To enable this functionality, use the following setting:

entrystore.auth.cookie.refresh-expiration-on-access=on|off

Logout

To logout the logout resource can be requested. It removes all authentication-related cookies, independently from the login-mechanism used (except for HTTP Basic, see the related section above):

GET https://base/auth/logout

Password authentication control

It is possible to deactivate or limit the authentication using username and password (e.g. if login should be restricted to SSO). Example use case: all users except admin must use SSO to login.

The following settings are available:

entrystore.auth.password=on|off|whitelist (default: on)
entrystore.auth.password.whitelist.n=username (honored if setting above is "whitelist"; n = numer of n-th line of whitelist)

In addition to the whitelist it is also possible to block certain users (e.g. admin) using a blacklist:

entrystore.auth.password.blacklist.n=username (n = numer of n-th line of blacklist)

The blacklist is active automatically when at least one user is added to it.

User information

Independently from the used authentication scheme it is possible to request basic information about the currently logged in user by sending a request to the following URL:

GET https://base/auth/user

Sample response:

{
  id: "20",
  language: "en",
  homecontext: "20",
  user: "jack",
  authTokenExpires: "Thu Jul 09 11:45:56 CEST 2015",
  clientAcceptLanguage: {
    de: 0.8,
    en-US: 0.89,
    sv: 0.69,
    en: 1
  }
}

The Accept-Language header that is sent by the client is mirrored back via the clientAcceptLanguage object. This is to aid browser executed client applications due to the fact that JavaScript cannot access the user's language settings.

The user resource may also be used for unauthenticated sessions, in such cases information about the guest user will be returned.

Temporary lockout of user

A user can be locked out for a specific time if entering the wrong password too many times. This is controlled by the following settings in entrystore.properties

# Set to -1 to disable. Default is 5.
entrystore.auth.temp.lockout.max.attempts=3

# The time the user should be lockedout. The format is <time><timeunits>. Allowed units are:
#
# ns = nanoseconds
# us = microseconds
# ms = milliseconds
# s = seconds
# m = minutes
# h = hours
# d = days
#
# If no timeunit is defined, the default is ms.
# This must be set if entrystore.auth.temp.lockout.max.attempts is enabled.
#
entrystore.auth.temp.lockout.duration=1h (default: 5m)

Lockout of administrators can be prevented with the following setting:

entrystore.auth.temp.lockout.admin=false (default: true)

Managing your active logins

Viewing all of your currently active logins

A user can be logged in using different authentication tokens, e.g. with a different browser or from another client machine.

To get a list of all currently active logins, use this request:

GET https://base/auth/tokens

The result is a JSON list of all authorization tokens that exist in the system, each one representing a separate login for the user account.

Each token is a map, where the key is the token identifier itself (stored in your browser in the cookie auth_token), and the body an object containing some information regarding this specific login.

Here is an example of what the answer could be:

{
  "9UFrQaRWSRqXbgOUdCYTiLg2Hp26zdnzyb4jLCOKdmziUfic0qDvTcwZr09bM17Qj3GcWAMpFEiE1Uv8QZSnOegNJhuGxhBMV39K7hpiWUMuHvcI9sP53bT0IoqTiCp5": {
    "loginTime": "2023-04-24T16:17:30.292205",
    "loginExpiration": "2023-04-24T18:30:54.498670",
    "inetAddress": "/122.8.11.97",
    "lastAccess": "2023-04-24T16:30:54.498670",
    "userAgent": "Apache-HttpClient/4.5.14 (Java/17.0.6)",
    "userName": "donald"
  },
  "g3CLSZ7eme2wt7vcHDPWGKUuX03a01hvhG4k436YITAur52m3xUzM7qRyt9eyQiz9aA5wYC27O6e7JZzrOBRB7kWL1VAV0KyShbn6VbUROPRuGsPOJs7wS6yjmJpLzYe": {
    "loginTime": "2023-04-24T16:29:37.867033",
    "loginExpiration": "2023-04-24T18:29:38.151487",
    "inetAddress": "/113.119.4.217",
    "lastAccess": "2023-04-24T16:29:38.151487",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Safari/605.1.15",
    "userName": "donald"
  }
}

Terminating an active session

If you see some suspicious activity, or just want to end a specific session, you can do this by using the following request:

DELETE https://base/auth/tokens

with the following payload:

{
   "token": "g3CLSZ7eme2wt7vcHDPWGKUuX03a01hvhG4k436YITAur52m3xUzM7qRyt9eyQiz9aA5wYC27O6e7JZzrOBRB7kWL1VAV0KyShbn6VbUROPRuGsPOJs7wS6yjmJpLzYe"
}

where token points to the token identifier you want to remove.

Please note that if you choose to terminate the same session you are currently using, you will effectively be signed out and need to sign in again.