Cloud Software Group, Inc. EBX®
Documentation > Administration Guide > Installation & configuration
Navigation mode Documentation > Administration Guide > Installation & configuration

# 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:

`HttpOnly` | Not customizable. The cookie can't be read by javascript code in the browser.
`Secure` | Customizable via the property `ebx.security.authorizationCookie.attribute.secure` in `ebx.properties`. Defines if the cookie can be sent over HTTPS only, or if it can also be sent over HTTP.
`SameSite` | Customizable via the property `ebx.security.authorizationCookie.attribute.sameSite` in `ebx.properties`. Defines if the cookie can be sent when browsing from an external site.

##### See also

- Security configuration

## 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.

##### See also

- Security configuration

### 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`.

##### Note

When EBX® redirects the user to the custom login page, it also adds a `resume` query parameter to the URL. This `resume` query parameter contains an URL pointing to `/ebx-authentication/login` with some additional parameters and should be used in priority to redirect the user to `/ebx-authentication/login` after the authentication succeeds.

##### See also

- Security configuration

## 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.

##### See also

- Enabling the SCIM feature

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.

##### Note

Only one protocol can be configured at a time.

##### Note

The logout process initiated from the IdP will only apply to the browser used to log out.

##### Note

In the case of a reverse-proxy configuration, the base URL of the server should be configured in the properties of both protocols.

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

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

##### Note

A resume query parameter can be used to hold an encoded URL to which the client should be redirected once authentication is completed.

> `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`

##### Note

A property change triggers the generation of a new sp-descriptor.xml and the loading of the existing keystore.jks and idp-descriptor.xml.

### 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`

Documentation > Administration Guide > Installation & configuration