Authentication

General considerations

Authentication manager

The AuthenticationManager is dedicated to everything related to user authentication. eQual is stateless, meaning that all HTTP requests are expected to hold some data allowing to identify the user who made the request.

Access token

eQual uses JWT tokens that are exchanged between the back-end and the client (browser ) as HttpOnly cookie.

using CLI

There is no authentication using CLI: in command-line context, user is identified as root with full privileges.

During authentication (via the signin controller) a token is generated, according to the AUTH_ACCESS_TOKEN_VALIDITY parameter, and stored by the browser.

The duration defined in AUTH_ACCESS_TOKEN_VALIDITY corresponds to the maximum duration of inactivity of a user session.

When the token's validity limit has been exceeded, the token is deleted by the browser and the user must identify himself again.

Extension of validity

Each time a valid session token is used, it authenticates the user according to AUTH_ACCESS_TOKEN_VALIDITY. The validity of the token is extended each time a user makes a userinfo request .

Authentication Levels

The table below outlines authentication levels (auth_level) and their associated requirements:

auth_level	Description	Supported auth_types
AAL1	Basic: Single-factor authentication.	pwd, email, sms, pin
AAL2	Moderate: MFA required, including phishing-resistant methods.	otp, smsotp, push, qrcode, passkey(1)
AAL3	High: MFA required, including hardware or biometric factors.	hwk, fingerprint, face, eye, voice, sc, passkey(2)

Possible Authentication Methods

Detailed descriptions of supported auth_types are provided below:

auth_type	Description
pwd	Traditional password authentication.
email	One-time code or unique link sent via email.
sms	Code sent via SMS to the user's registered number.
pin	Short numeric code defined by the user.
otp	One-time password generated by an app or device.
smsotp	OTP sent via SMS.
push	Push notification for approval via a trusted device.
qrcode	QR code scanned by a trusted application.
hwk	Secure hardware key (e.g., YubiKey).
fingerprint	Biometric authentication using fingerprints.
face	Biometric authentication using facial recognition.
eye	Biometric authentication using iris or eye scans.
voice	Biometric authentication using voice recognition.
sc	Smartcard-based authentication requiring a specific reader.
passkey	Passwordless authentication using FIDO2/WebAuthn cryptographic keys.

Supported authentication methods

As of version 2.0 of eQual supports the following methods: pwd, email, passkey

Handling Insufficient Authentication Levels

Certain services or applications may require stricter authentication depending on their importance or the sensitivity of the data they handle.

Within access property of the announcement of a controller, if the visibility is set to "protected", the default auth_level is "simple". However, this behavior can be explicitly overridden by setting the auth_level to "2" to enforce multi-factor authentication.

    'access' => [
        'visibility'        => 'protected',
        'groups'            => ['booking.default.user'],
        'auth_level'        => 2
    ],

When requesting the controller, if a user's authentication level is insufficient, a prompt, such as an overlay or popup window, is displayed. This prompt invites the user to select and use an available authentication method that meets the required level of escalation.

Upon successful authentication, the system updates the auth_level in the session or token and re-evaluates the original request, ensuring the process continues seamlessly without losing context.

MFA authentication

Multi-Factor Authentication (MFA) in eQual enhances user identity verification by requiring additional authentication steps. This escalation can occur during sign-in, based on Authentication Policies, or when attempting sensitive actions.

Several MFA methods are supported:

Email Authentication

In this method, a validation email is sent to the user's registered email address. The email contains a link that, when accessed, escalates the access token level, provided the following conditions are met:

• The correct nonce is supplied.
• A valid CSRF token is included.

Passkeys Authentication

Passkeys provide an advanced MFA option. Here's how it works:

1. Controller Request Handling:
   • In a controller's "announce" phase, the required authentication level (auth_level) is specified.
   • If the current authentication level is insufficient, the server responds with a 403 Forbidden status code.
2. Escalation Request Flow:
   • The client is redirected to the "Auth" application with an Auth Escalation request.
   • A redirect URL is included in the request to maintain context after successful authentication.

HTTP 403 Payload Example (RFC 7231):

{
  "error": "insufficient_auth_level",
  "escalation_auth_types": []
}

After an MFA escalation, the access_token is updated with an amr (Authentication Methods Reference) section. This section tracks the user's authentication methods and their expiration, enabling dynamic evaluation of the global auth_level.

Access Token Example

{
  "id": "...",
  "exp": 1672531200,
  "amr": [
    {
      "auth_type": "passkey",
      "exp": 1672534800
    }
  ]
}

The Auth Manager calculates the global auth_level by identifying the highest valid authentication level based on the amr section. Expired methods are disregarded.