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 login-procedure is not necessary with HTTP Basic as the credentials are sent with every request. HTTP Basic is not active by default and needs to be activated:
entrystore.auth.http-basic.enabled=true|false (default: false)
The 5.x setting entrystore.auth.http-basic=on is still accepted; a warning in the log names the new key.
HTTP Basic requests do not create a session and no auth_token cookie is set, so there is nothing to log out from.
When HTTP Basic is enabled, guests that request a resource requiring a login at the URL level (e.g. GET https://base/auth/tokens), and requests with invalid credentials, are answered with 401 and the header WWW-Authenticate: Basic realm="EntryStore", which triggers a challenge response dialog in web browsers. The URL parameter auth_challenge=false suppresses this header.
entrystore.auth.password=off disables HTTP Basic regardless of the setting above, and with entrystore.auth.password=whitelist only the whitelisted users can use it (see Password authentication control).
Successful password verifications are cached, so that repeated requests of the same client do not have to compute the password hash every time. A password change takes effect immediately.
entrystore.auth.http-basic.cache.ttl=1h (default: 1h)
entrystore.auth.http-basic.cache.max-size=10000 (default: 10000)
entrystore.auth.http-basic=on
A request to the following URL triggers a challenge response dialog in web browsers:
GET https://base/auth/basic
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_usernameauth_password
The parameter auth_maxage may be supplied to shorten the maximum age (in seconds) of the login; it cannot exceed entrystore.auth.cookie.max-age (default: 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. In 6.x, a successful login is answered with 200 and the text Login successful., a failed login with 401 regardless of the reason. A login of a temporarily locked out user is answered with 429 (see Temporary lockout of user).
The validity of cookie tokens is 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.
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 age of a login in seconds, units such as 1d are allowed (default: 86400)
entrystore.auth.cookie.max-age must be at least one second, otherwise EntryStore does not start. How the max age is applied depends on entrystore.auth.cookie.refresh-expiration-on-access, see Refresh of authorization token.
EntryStore 5.x
In 5.x, entrystore.auth.cookie.max-age=-1 results in a session cookie.
An unknown or expired auth_token cookie is answered with 401. With the following setting the request is served as guest instead; the cookie is expired in both cases:
entrystore.auth.cookie.invalid-token-error=on|off (default: on)
In 6.x, the login, SSO, sign-up and password-reset routes and requests with ignoreAuth are always served as guest, independently from this setting.
Since 6.x, a session reloads its user from the repository at most every 10 seconds instead of on every request. A change of the user's admin role therefore reaches an open session up to that late; disabling or deleting a user, a password change and a deleted token still end the session on its next request. The interval is configured in seconds, 0 reloads the user on every request:
entrystore.auth.session.reload-interval=10 (default: 10)
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.
The SAML IdP needs to support RelayState as EntryStore makes use of it for transporting state information for redirects after login.
Since EntryStore version 4.6 it is possible to configure multiple SAML IdPs. An IdP will be selected based on URL parameters such as the username.
Assertion Consumer Service and URL parameters¶
A SAML login is initiated with GET https://base/auth/saml, which answers with 404 if SAML is not enabled.
The IdP posts its response to the Assertion Consumer Service (ACS) URL of the IdP. If entrystore.auth.saml.assertion-consumer-service.url is set, as in 5.x, the ACS URL of an IdP is that URL with the IdP's id appended as idp parameter, e.g. https://example.entryscape.dev/store/auth/saml?idp=keycloak, so an IdP set up for 5.x needs no change. Otherwise the ACS URL is {baseUrl}/login/saml2/sso/<idp-id>, e.g. https://example.entryscape.dev/store/login/saml2/sso/keycloak. Both URLs are always accepted. SAML responses of up to 512 KB are accepted.
The ACS URL as configured in entrystore.auth.saml.assertion-consumer-service.url is a base URL and needs to be completed with a URL parameter corresponding to the IdP's name in the configuration. For the keycloak example below this results in the ACS URL https://example.entryscape.dev/store/auth/saml?idp=keycloak.
The IdP is selected based on the username URL parameter in combination with the IdP's domain setting. If username (an email address) is provided, EntryStore will try to match the username's email domain with the IdP's corresponding domain(s). This requires the IdP's domains setting be configured. A request to https://example.entryscape.dev/store/auth/saml?username=test@entryscape.dev would result in a redirect to IdP keycloak in the example further down. Without username, the IdP is selected by the idp URL parameter, and if that is missing as well, the IdP in entrystore.auth.saml.default-idp is used.
Redirects¶
Redirects after login can be performed based on the URL parameters successurl and failureurl (the URLs need to match the whitelisted domains) or the default redirect URLs, if no URL parameter is provided. See examples below.
Settings¶
entrystore.auth.saml.enabled=true|false (default: false)
entrystore.auth.saml.assertion-consumer-service.url=<ACS base URL> (default: unset, see the ACS section above)
entrystore.auth.saml.redirect-success.url=<URL> (default: /auth/user)
entrystore.auth.saml.redirect-failure.url=<URL> (default: /auth/user)
entrystore.auth.saml.redirect-domain-whitelist=<comma-separated hostnames>
entrystore.auth.saml.default-idp=<idp-id>
entrystore.auth.saml.request-lifetime=<duration> (default: 15m, allowed: 1m to 60m)
entrystore.auth.saml.idp.<idp-id>.metadata.url=https://<idp-host>/path/saml.xml
entrystore.auth.saml.idp.<idp-id>.relying-party-id=<Relying-Party-ID> (default: {baseUrl}/saml2/service-provider-metadata/<idp-id>)
entrystore.auth.saml.idp.<idp-id>.metadata.max-age=<seconds> (default: 604800, minimum: 60)
entrystore.auth.saml.idp.<idp-id>.user-auto-provisioning=true|false (default: false)
entrystore.auth.saml.idp.<idp-id>.redirect-method=get|post (default: get)
entrystore.auth.saml.idp.<idp-id>.domains=<comma-separated email domains> (default: *, i.e. fallback for all domains)
An IdP is defined by its metadata.url; its id is the part of the key after entrystore.auth.saml.idp..
The settings for relying-party-id and the ACS URL must match the SAML IdP's configuration as a mismatch likely will result in a failed authentication process.
The setting metadata.url points out a URL which must contain the SAML IdP's metadata in XML format. Both local (file:) and remote (https://) URLs are supported. The metadata is reloaded after metadata.max-age seconds, so that signing certificate rollovers are picked up without a restart. If the remote metadata of an IdP cannot be fetched at startup, EntryStore starts anyway, logs a warning and retries in the background; until then, a login with that IdP is redirected to the failure URL. Missing or invalid local metadata makes startup fail.
redirect-method determines whether the authentication request is sent to the IdP with a redirect (get) or a form (post), using the IdP's endpoint for that binding from its metadata. request-lifetime determines how long a started login may stay at the IdP (e.g. for multi-factor authentication) before its response is rejected.
The lists redirect-domain-whitelist and domains are comma-separated; the numbered form of 5.x (.1, .2, ...) is accepted as well.
Example for a configuration with two IdPs:
entrystore.auth.saml.enabled=true
entrystore.auth.saml.assertion-consumer-service.url=https://example.entryscape.dev/store/auth/saml
entrystore.auth.saml.redirect-success.url=https://example.entryscape.dev/start
entrystore.auth.saml.redirect-failure.url=https://example.entryscape.dev/signin
entrystore.auth.saml.redirect-domain-whitelist=entryscape.dev,example.entryscape.dev,thirdparty.com
entrystore.auth.saml.default-idp=keycloak
entrystore.auth.saml.idp.google.relying-party-id=EntryScapeDev
entrystore.auth.saml.idp.google.metadata.url=https://example.entryscape.dev/saml.xml
entrystore.auth.saml.idp.google.user-auto-provisioning=true
entrystore.auth.saml.idp.google.redirect-method=post
entrystore.auth.saml.idp.google.domains=external.entryscape.dev
entrystore.auth.saml.idp.keycloak.relying-party-id=EntryScapeDev
entrystore.auth.saml.idp.keycloak.metadata.url=https://id.entryscape.dev/saml2/metadata
entrystore.auth.saml.idp.keycloak.redirect-method=post
entrystore.auth.saml.idp.keycloak.domains=entryscape.dev,example.entryscape.dev
The login is implemented with Spring Security's SAML support, which EntryStore configures from the settings above. Settings without an EntryStore equivalent can be set directly on the underlying relying-party registration with spring.security.saml2.relyingparty.registration.<idp-id>.* (see the Spring Boot documentation); such a key overrides only the value it names.
Differences to 5.x: SAML is enabled with entrystore.auth.saml.enabled=true; the 5.x values entrystore.auth.saml=on and new are still accepted. entrystore.auth.saml.idps.x is no longer needed. The redirect URLs default to /auth/user. request-lifetime is new. The legacy single-IdP settings (see the 5.x tab) are still accepted and become an IdP with the id of entrystore.auth.saml.default-idp, or default.
entrystore.auth.saml=new|on|off (default: off, new: use the new SAML implementation, on: use legacy - see below)
entrystore.auth.saml.assertion-consumer-service.url=https://<entrystore-instance-domain>/store/auth/saml
entrystore.auth.saml.redirect-success.url=<absolute URL> (default: unset)
entrystore.auth.saml.redirect-failure.url=<absolute URL> (default: unset)
entrystore.auth.saml.redirect-domain-whitelist.x=entryscape.dev
entrystore.auth.saml.default-idp=<name of default IdP>
entrystore.auth.saml.idps.x=<IdP name>
entrystore.auth.saml.idp.<idp-name>.relying-party-id=<Relying-Party-ID>
entrystore.auth.saml.idp.<idp-name>.metadata.url=https://<idp-host>/path/saml.xml
entrystore.auth.saml.idp.<idp-name>.metadata.max-age=<time period after which IdP metadata is reloaded> (default: 604800; unit: seconds)
entrystore.auth.saml.idp.<idp-name>.user-auto-provisioning=on|off (default: off)
entrystore.auth.saml.idp.<idp-name>.redirect-method=get|post (default: get)
entrystore.auth.saml.idp.<idp-name>.domains.x=external.entryscape.dev
The settings for relying-party-id and assertion-consumer-service.url (ACS) must match the SAML IdP's configuration as a mismatch likely will result in a failed authentication process. Attention must be paid to the idp parameter that is appended automatically, as described in the ACS section further up.
The setting metadata.url 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 setting metadata.max-age specifies after which period of time the IdP metadata must 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.
Example for a configuration with two IdPs:
entrystore.auth.saml=new
entrystore.auth.saml.assertion-consumer-service.url=https://example.entryscape.dev/store/auth/saml
entrystore.auth.saml.redirect-success.url=https://example.entryscape.dev/start
entrystore.auth.saml.redirect-failure.url=https://example.entryscape.dev/signin
entrystore.auth.saml.redirect-domain-whitelist.1=entryscape.dev
entrystore.auth.saml.redirect-domain-whitelist.2=example.entryscape.dev
entrystore.auth.saml.redirect-domain-whitelist.3=thirdparty.com
entrystore.auth.saml.default-idp=keycloak
entrystore.auth.saml.idps.1=google
entrystore.auth.saml.idps.2=keycloak
entrystore.auth.saml.idp.google.relying-party-id=EntryScapeDev
entrystore.auth.saml.idp.google.metadata.url=https://example.entryscape.dev/saml.xml
entrystore.auth.saml.idp.google.metadata.max-age=604800
entrystore.auth.saml.idp.google.user-auto-provisioning=on
entrystore.auth.saml.idp.google.redirect-method=post
entrystore.auth.saml.idp.google.domains.1=external.entryscape.dev
entrystore.auth.saml.idp.keycloak.relying-party-id=EntryScapeDev
entrystore.auth.saml.idp.keycloak.metadata.url=https://id.entryscape.dev/saml2/metadata
entrystore.auth.saml.idp.keycloak.metadata.max-age=604800
entrystore.auth.saml.idp.keycloak.user-auto-provisioning=off
entrystore.auth.saml.idp.keycloak.redirect-method=post
entrystore.auth.saml.idp.keycloak.domains.1=entryscape.dev
entrystore.auth.saml.idp.keycloak.domains.2=example.entryscape.dev
Legacy configuration (deprecated since version 4.6)
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 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)
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.
A SAML login lasts as long as a cookie login, see entrystore.auth.cookie.max-age.
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 send the authentication request with POST (entrystore.auth.saml.idp.<idp-id>.redirect-method=post).
OpenID Connect (OIDC)¶
Since version 6.0 EntryStore supports login via OpenID Connect. A login is initiated by requesting the following URL:
GET https://base/auth/oidc
The client is redirected to the selected provider's authorization endpoint and, after authentication, back to EntryStore, which exchanges the authorization code, validates the ID token and - in the case of success - sets an authentication token as cookie, using the same mechanism as the Cookie login mechanism described above. The endpoint responds with 404 Not Found if OIDC is not enabled.
The provider must publish OIDC discovery metadata at <issuer-uri>/.well-known/openid-configuration; EntryStore uses it to resolve the authorization, token and userinfo endpoints and to pick up signing key rotations via JWKS. In contrast to SAML no metadata needs to be maintained on the EntryStore side.
The client registration must request the openid scope, and its scopes must be sufficient for the provider to emit the claim that is mapped to the EntryStore username (email by default, which usually requires the email scope). A login that does not result in an OIDC principal is rejected rather than mapped to an unintended user.
Redirect URI¶
The redirect URI (the provider's callback into EntryStore) is not configured in EntryStore; it follows the default layout and must be registered with the provider as:
https://<entrystore-instance-domain>/<path>/login/oauth2/code/<provider-id>
For an instance served at https://example.entryscape.dev/store and a provider with the id keycloak this results in https://example.entryscape.dev/store/login/oauth2/code/keycloak.
The base URL is derived from the incoming request, so when EntryStore runs behind a reverse proxy the proxy must set X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Prefix. Otherwise the redirect URI constructed by EntryStore does not match the one registered with the provider and the login fails.
Provider selection¶
It is possible to configure multiple OIDC providers. The provider is selected in the following order:
- The
usernameURL parameter (an email address): its domain is matched against the providers'domainssettings. A provider configured withdomains=*acts as fallback and is only used if no provider matches the domain specifically. - The
providerURL parameter, naming the provider id explicitly. - The provider configured in
entrystore.auth.oidc.default-provider.
A request to https://example.entryscape.dev/store/auth/oidc?username=test@entryscape.dev results in a redirect to the provider covering entryscape.dev in the example further down. If none of the three alternatives yields a provider, the request is answered with 400 Bad Request; the same applies to a provider parameter naming an unknown provider id.
Redirects¶
Redirects after login can be performed based on the URL parameters successurl and failureurl (the URLs need to match the whitelisted domains) or the default redirect URLs, if no URL parameter is provided. The default for both is /auth/user.
The host of a supplied successurl/failureurl must match one of the entries in entrystore.auth.oidc.redirect-domain-whitelist. A URL that does not match is ignored - the login itself is not failed - and the corresponding default URL is used instead. Whitelist entries must be bare hostnames; an entry containing a scheme, port, path, userinfo or a wildcard aborts startup with an error naming the setting.
The failureurl parameter applies to denials during login post-processing, i.e. an unknown user without auto-provisioning, a reserved username or a disabled user. Failures earlier in the flow - an error returned by the provider, or a failed code exchange or ID token validation - always redirect to the configured redirect-failure.url.
The per-login URLs are transported through the round trip in a server-side cache keyed by the OAuth 2.0 state parameter, which makes the flow work also with SameSite=Strict session cookies. The authorization request and the per-login URLs are kept for two minutes; a login that is not completed at the provider within that time fails and is redirected to the configured redirect-failure.url. At most 10000 logins carrying custom redirect URLs are kept in flight simultaneously.
Settings¶
entrystore.auth.oidc.enabled=true|false (default: false)
entrystore.auth.oidc.default-provider=<provider id>
entrystore.auth.oidc.redirect-domain-whitelist=<comma-separated hostnames>
entrystore.auth.oidc.redirect-success.url=<URL> (default: /auth/user)
entrystore.auth.oidc.redirect-failure.url=<URL> (default: /auth/user)
entrystore.auth.oidc.provider.<provider-id>.domains=<comma-separated email domains> (default: *)
entrystore.auth.oidc.provider.<provider-id>.user-auto-provisioning=true|false (default: false)
entrystore.auth.oidc.provider.<provider-id>.username-claim=<claim name> (default: email)
The client itself - client id, secret, scopes and issuer - is configured using the framework's native settings:
spring.security.oauth2.client.registration.<provider-id>.client-id=<client id>
spring.security.oauth2.client.registration.<provider-id>.client-secret=<client secret>
spring.security.oauth2.client.registration.<provider-id>.scope=openid,profile,email
spring.security.oauth2.client.provider.<provider-id>.issuer-uri=https://<idp-host>/<path>
The provider id must be identical in both blocks. If default-provider or an entrystore.auth.oidc.provider.<id> entry names an id without a matching spring.security.oauth2.client.registration entry, EntryStore aborts at startup with an error naming the offending setting. The same happens if OIDC is enabled without any client registration at all.
The claim configured with username-claim is resolved against the merged claims of the ID token and the userinfo endpoint. Note that EntryStore does not verify the email_verified claim when username-claim=email; the provider is trusted to only assert addresses it has verified.
Whether OIDC is active can be verified in the startup log, which contains either OIDC Auth Enabled, followed by one line per configured provider, or OIDC Auth Disabled.
Example¶
Example for a configuration with two providers, where users with an address at entryscape.dev are routed to Keycloak and everyone else to Google:
entrystore.auth.oidc.enabled=true
entrystore.auth.oidc.default-provider=keycloak
entrystore.auth.oidc.redirect-domain-whitelist=entryscape.dev,example.entryscape.dev
entrystore.auth.oidc.redirect-success.url=https://example.entryscape.dev/start
entrystore.auth.oidc.redirect-failure.url=https://example.entryscape.dev/signin
entrystore.auth.oidc.provider.keycloak.domains=entryscape.dev
entrystore.auth.oidc.provider.keycloak.user-auto-provisioning=true
entrystore.auth.oidc.provider.keycloak.username-claim=email
entrystore.auth.oidc.provider.google.domains=*
entrystore.auth.oidc.provider.google.user-auto-provisioning=false
spring.security.oauth2.client.registration.keycloak.client-id=entrystore
spring.security.oauth2.client.registration.keycloak.client-secret=<client secret>
spring.security.oauth2.client.registration.keycloak.scope=openid,profile,email
spring.security.oauth2.client.provider.keycloak.issuer-uri=https://id.entryscape.dev/realms/entryscape
spring.security.oauth2.client.registration.google.client-id=<client id>
spring.security.oauth2.client.registration.google.client-secret=<client secret>
spring.security.oauth2.client.registration.google.scope=openid,profile,email
spring.security.oauth2.client.provider.google.issuer-uri=https://accounts.google.com
The redirect URIs to be registered with the two providers are https://example.entryscape.dev/store/login/oauth2/code/keycloak and https://example.entryscape.dev/store/login/oauth2/code/google.
Mapping of OIDC users to EntryStore users¶
The claim configured with username-claim (by default email) is used as username in EntryStore. Users that do not yet exist in EntryStore are created upon first login if user-auto-provisioning is set to true for the provider that authenticated them; otherwise the login is rejected. A client registration without a corresponding entrystore.auth.oidc.provider.<id> entry can log in existing users, but never creates new ones.
Please note that the usernames admin and guest are reserved in EntryStore and cannot be used to login via OIDC, independently of the provider. Disabled users are rejected as well.
Limitations¶
- Logout removes the local EntryStore session only, the session at the provider is not terminated (no RP-initiated logout via the provider's
end_session_endpoint). This corresponds to the behaviour of the SAML and CAS mechanisms. - Claims are not mapped to EntryStore group memberships.
CAS¶
This section is valid for CAS v1-3 (and, in 5.x, SAML v1.1).
Configuration¶
The following settings are required:
entrystore.auth.cas.enabled=true
entrystore.auth.cas.version=cas1|cas2|cas3 (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 (default: <server.url>/login):
entrystore.auth.cas.server.url-login=https://localhost:7002/cas/specialLogin
The 5.x settings entrystore.auth.cas=on and entrystore.auth.cas.server.url.login are still accepted; a warning in the log names the new keys. SAML 1.1 (version=saml11) is not supported in 6.x.
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
A CAS login lasts as long as a cookie login, see entrystore.auth.cookie.max-age.
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> (6.x default: /auth/user, 5.x: unset)
entrystore.auth.cas.redirect-failure.url=<absolute URL> (6.x default: /auth/user, 5.x: 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. The endpoint responds with 404 Not Found if CAS is not enabled.
Please note that CAS users with username admin cannot login using the CAS authenticator as this particular username is reserved in EntryStore. In 6.x, the same applies to guest.
The standard logout procedure applies as described further down.
Mapping of CAS users to EntryStore users¶
The CAS login mechanism expects EntryStore principals with a username matching the CAS uid; users that do not exist yet are only created if entrystore.auth.cas.user-auto-provisioning is activated. 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 meet the password rules, otherwise the admin user is created without password and a warning is logged.
EntryStore 5.x
5.x checks the initial admin password against the default password rules, not against the configured ones.
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>
Each custom rule is a regular expression that must be found in the password. The rules apply when a password is set by a user or an admin and at sign-up; a password reset only requires 8 characters.
In 6.x, an invalid regular expression or an unrecognised boolean value makes startup fail (see Settings for the accepted values).
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"
}
In 6.x, a missing or wrong current password is answered with 403, a password that does not meet the password rules with 400. A password change ends the user's other password login sessions; when an admin changes another user's password, all of that user's password login sessions are ended.
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.
This functionality is controlled with the following setting:
entrystore.auth.cookie.refresh-expiration-on-access=on|off (default: on)
With on, a login ends entrystore.auth.cookie.max-age after the last request, and the auth_token cookie is issued with a lifetime of 365 days. With off, a login ends entrystore.auth.cookie.max-age after it was made, independently from activity, and the cookie lives as long. In 6.x this applies to cookie, SAML, CAS and OIDC logins alike.
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):
POST https://base/auth/logout
The request is answered with 204 No Content. A GET request does not log out. If CSRF protection is enabled, the request must send the X-XSRF-TOKEN header.
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 = number of n-th line of whitelist)
With off, /auth/cookie and /auth/login answer with 404 and HTTP Basic is disabled. SSO logins and existing sessions keep working, and users can still change or reset their passwords. With whitelist, only the listed users may log in with a password, using the cookie login or HTTP Basic; an empty whitelist denies every password login.
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 = number of n-th line of blacklist)
The blacklist is active automatically when at least one user is added to it.
In 6.x, true/yes/1 and false/no/0 are accepted for on and off, and any other value makes startup fail.
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",
"homecontext": "20",
"user": "jack",
"uri": "https://base/store/_principals/entry/20",
"language": "en",
"clientAcceptLanguage": {
"de": 0.8,
"en-US": 0.89,
"sv": 0.69,
"en": 1
},
"external-id": "jack@example.com",
"authTokenExpires": "2015-07-09T11:45:56.384"
}
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.
Properties without a value are omitted. authTokenExpires is only included for logged in users with a session.
EntryStore 5.x
In 5.x, the external ID of the user is returned as external_id.
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. The lockout applies to the cookie login (POST /auth/cookie); a login attempt of a locked out user is answered with 429.
This is controlled by the following settings in entrystore.properties
# Set to 0 or -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. A duration of 0 disables the lockout.
# 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)
EntryStore 5.x
In 5.x, only a negative value of entrystore.auth.temp.lockout.max.attempts disables the lockout; 0 locks a user out after the first failed attempt.
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 object with all authorization tokens of the user that exist in the system, each one representing a separate login for the user account. In 6.x, only logins via /auth/cookie are listed, not SAML, CAS or OIDC logins.
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": {
"userName": "donald",
"loginTime": "2023-04-24T16:17:30.292205",
"loginExpiration": "2023-04-24T18:30:54.498670",
"lastAccessTime": "2023-04-24T16:30:54.498670",
"lastUsedIpAddress": "122.8.11.97",
"lastUsedUserAgent": "Apache-HttpClient/4.5.14 (Java/17.0.6)",
"loginTokenMaxAge": 7200
},
"g3CLSZ7eme2wt7vcHDPWGKUuX03a01hvhG4k436YITAur52m3xUzM7qRyt9eyQiz9aA5wYC27O6e7JZzrOBRB7kWL1VAV0KyShbn6VbUROPRuGsPOJs7wS6yjmJpLzYe": {
"userName": "donald",
"loginTime": "2023-04-24T16:29:37.867033",
"loginExpiration": "2023-04-24T18:29:38.151487",
"lastAccessTime": "2023-04-24T16:29:38.151487",
"lastUsedIpAddress": "113.119.4.217",
"lastUsedUserAgent": "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",
"loginTokenMaxAge": 7200
}
}
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
Content-Type: application/json
with the following payload:
{
"token": "g3CLSZ7eme2wt7vcHDPWGKUuX03a01hvhG4k436YITAur52m3xUzM7qRyt9eyQiz9aA5wYC27O6e7JZzrOBRB7kWL1VAV0KyShbn6VbUROPRuGsPOJs7wS6yjmJpLzYe"
}
where token points to the token identifier you want to remove. In 6.x, the request is answered with 204 No Content.
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.