User authentication

The /ebx-authentication servlet

The /ebx-authentication servlet is the central point handling the user authentication in EBX®. Its role is to:

• Create an authorization token when the user logs in for the first time.

• Revoke the authorization token when the user logs out.

• Redirect the authorized user to the appropriate page.

Furthermore, depending on the configuration, it can also:

• Handle the login process by displaying a login screen.

• Redirect the unauthorized user to a custom login screen.

• Redirect the user logging out to a custom exit page.

The authorization token

When the /ebx-authentication servlet successfully authenticates a user, it creates a token containing the authentication information and stores it in a session cookie.

This means that the authorization is shared between all the browser tabs:

• If the user is already authenticated on a browser tab and opens EBX® on another tab, it will not be asked to authenticate again.

• It is not possible to be logged with different users in different tabs of the same browser.

Cookie properties

The cookie containing the token has the following properties:

Customizing the authentication process

By default, EBX® uses a built-in directory and built-in login page. It is strongly recommended to replace the built-in directory by a custom one.

Customizing the directory

While EBX® provides a built-in directory, it is strongly recommended to replace it:

1. Create a class overriding Directory.

2. Create a class overriding DirectoryFactory.

3. Use the property ebx.directory.factory in ebx.properties to declare the factory.

Customizing the login page

While EBX® provides a built-in login page, it is possible to replace it. To do so, use the property ebx.security.loginPage.url in ebx.properties to declare the custom login page.

It is up to the custom login page to authenticate the user. Once the user is authenticated, he should be redirected to the /ebx-authentication/login page. Then, EBX® will call the Directory.authenticateUserFromHttpRequest method before creating an authorization token. The following points are required for this to work:

• The request pointing to /ebx-authentication/login should contain enough information to authenticate the user, for instance in a cookie, a HTTP header or a query parameter.

• The directory must be overridden (see Customizing the directory) and the implementation of the Directory.authenticateUserFromHttpRequest method should read the information from the incoming request in order to return the appropriate UserReference.

Single Sign-On (SSO)

Single sign-on allows users to authenticate once and gain access to multiple applications and services through a centralized Identity Provider (IdP) rather than managing separate login credentials. This integration streamlines the login process, reduces the risk of password-related security breaches, and enhances user experience by enabling seamless access.

EBX® supports the SAML 2.0 and OpenID Connect protocols. To enable these features, you must declare and configure EBX® as an application in the Identity Provider. Configuration requirements depend on the enabled protocol. When using SAML 2.0, an sp-descriptor.xml is generated on startup and should be imported in the Identity Provider to ensure a seamless configuration.

The endpoints used to initiate a login/logout via the configured protocol are:

http[s]://<host>[:<port>]/ebx-authentication/rest/sso/v1/login

http[s]://<host>[:<port>]/ebx-authentication/rest/sso/v1/logout

If there is a need to access or redirect to the built-in or custom login page that uses the internal directory, the following url may be used:

http[s]://<host>[:<port>]/ebx-authentication/login?method=loginPage

SAML 2.0

To enable SAML 2.0, configure the service provider properties or EBX® Container Edition environment variables and have a keystore, idp-descriptor.xml and sp-descriptor.xml in the repository folder.

• Keystore: A keystore must be configured for all signature and encryption operations. Use the following java keytool command to generate a new one:

  keytool -genkeypair -alias ebx.saml -keypass keypass -keystore keystore.p12 -storepass keypass -keyalg RSA -keysize 2048 -validity 3650

• idp-descriptor.xml: The IDPSSODescriptor XML file exported from the Identity Provider.

• sp-descriptor.xml: The SPSSODescriptor XML file generated by EBX® on startup using the configured properties.

The configured nameId is extracted from the assertion and matched with the EBX® directory to authenticate the user. Therefore, it's crucial to precisely configure the nameId attribute or the format.

The same endpoint is used for both assertion consumer and single logout services:

http[s]://<host>[:<port>]/ebx-authentication/rest/sso/v1/saml2/callback

OpenID Connect

To enable OpenID connect, configure the client properties or for EBX® Container Edition the environment variables. When using OpenID:

• The urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST binding type is used for all operations.

• The client authentication method used is Client Secret Post.

• The response mode is form_post and the response type is code.

The same endpoint is used for both redirect and logout operations:

http[s]://<host>[:<port>]/ebx-authentication/rest/sso/v1/oidc/callback