Skip to content

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.

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 logout procedure. To perform unauthenticated requests, credentials must be omitted in the HTTP request header. This may be difficult in web browser 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 (default: unset)
entrystore.auth.saml.redirect-failure.url (default: unset)
entrystore.auth.saml.idp-metadata.max-age (default: 604800; 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

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

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 following optional URL-parameters can be used to redirect the client to application pages which are more useful for the user than the standard EntryStore API:

  • redirectOnSuccess
  • redirectOnFailure

The parameters redirectOnSuccess and/or redirectOnFailure expect an absolute URL and may be provided if the client should be redirected upon success or failure. The URLs must be encoded.

Example for redirectOnSuccess:

GET https://base/auth/cas?redirectOnSuccess=http%3A%2F%2Fbase%2Fauth%2Fuser

The standard logout procedure applies as described below.

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.

Password restrictions

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

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.

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)

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.