SSQ (Self-Service Quarantine)

This page guides you through the configuration and activation of the self-service quarantine (SSQ). The self-service quarantine portal allows your internal recipients to look at their quarantined emails and release them if necessary. Every user has access to their own emails only. Here you can see how the SSQ portal works:

The SSQ portal is a part of xorlab Control Center (XCC) and is accessed with the same URL. SSQ users will only have access to the SSQ portal.

Prerequisites

SSQ Role

Every internal user that should access the SSQ to manage their quarantined emails must have the xcc_quarantine_user role (see Users, Roles, and Permissions). Please refer to Authentication for your specific authentication method (for example, LDAP or SAML) to make sure that this role is given to your SSQ users.

Token based authentication

Token-based authentication can be used for SSQ users as an alternative to SAML or LDAP authentication to access their self-service quarantine. The Notification E-Mail which the user receives contains a link, with a generated token which allows users to access their SSQ. More information about Token based authentication can be found here Auto-Login Authentication

Accessible email addresses

If users have multiple emails to be accessed, you need to assign a list of accessible email addresses in SSQ to every SSQ user. In most cases, this list is provided as a part of the authentication process through your LDAP server (e.g., Active Directory) or through your identity provider (IdP) for SAML. Therefore, make sure that your LDAP server or IdP can provide the list of email addresses for every user. Then, please refer to Authentication to configure attributeMapping for the emails attribute, which should contain the list of email addresses.

Testing SSQ with password file authentication

If you only wish to test the SSQ with a local user, you can refer to the local password file configuration to define a local user with the xcc_quarantine_user and a static list of accessible email addresses.

Configuration

When all the requirements are met, users can log in to SSQ and start using it. There is no activation required. In the following sections, we will cover the available global SSQ settings which you can adjust if you want to change the already sensible default behavior.

Configuration fileAll global SSQ settings are configured in the shared/guarded_tenants.yml file under the quarantine section in your tenant.

Besides the global SSQ settings, the individual SSQ users can customize the portal language or the notifications in their SSQ user settings menu.

Appearance, language, and notifications

When users access the SSQ for the first time, the interface language is automatically set based on the language of their browser—provided it’s English, German, French, or Italian. If the browser is set to a different language, the SSQ interface defaults to English. SSQ users can change the interface language, notification language and frequency of the notifications on their own:

Click the user account in the upper right corner.
In the drop-down user menu, click SETTINGS.
On the Settings page that appears, a user can choose the theme for the portal (dark or light) on the Appearance tile, set Quarantine notifications (note that this option has to be enabled by the admin), select the Language of the portal and the language of the notification emails. Currently supported languages for notification emails are German, English, Italian, and French.

Language optionThe Select language option is only available to users that do not have access to the analyst or admin portal. Users that have, for example, the xcc_admin or xcc_analyst role will not see the option to change the language.

SSQ quarantines

You can configure which of your quarantines are a part of the SSQ. For every quarantine, you can specify if:

Quarantined emails are shown to the user in the SSQ (canView).
Quarantined emails can be released in the SSQ by the user (canRelease).
Quarantined emails can be unlocked via entering a password, only for Airlock quarantine (canUnlock).
Quarantined emails can be requested for release by the user (canRequestRelease).

Users can only release emails that are shown to them in the first place. And users can only request the release of an email if they can not release it themselves. See guarded_tenants.yml for the default SSQ configuration. The following snippet shows how to adjust the config for a specific quarantine:

shared/guarded_tenants.yml

tenants:
  - name: xorlab
    bccFallbackDomain: xorlab.com
    domains:
      - xorlab.com
    quarantine:
      quarantines:
          ## The name of the quarantine.
          - name: Malware
            displayText: Malware
            ## Users can see messages in this quarantine.
            canView: true
            ## Users release the message in this quarantine.
            canRelease: false
            ## Users can request the release a quarantined message to an admin.
            canRequestRelease: false
            ## Enable the message unlock feature
            canUnlock: false

Notifications

xorlab supports immediate, daily and weekly user email notifications for quarantined SSQ emails. By default, notifications are globally disabled and the corresponding user setting is hidden. If you would like to enable notifications, set enabled: true (see below). Afterwards, every user can enable or disable notifications through their individual SSQ.

Notifications are only sent for emails in quarantines that are at least viewable (canView: true). Otherwise, no notification is sent.

After enabling notifications, make sure that you set your company info and the SSQ URL that will be included in notifications as described in Changing the company information.

shared/guarded_tenants.yml

tenants:
  - name: xorlab
    bccFallbackDomain: xorlab.com
    domains:
      - xorlab.com
    quarantine:
      ## Notification settings for the self-service quarantine portal.
      notifications:
        ## Enables/disables the quarantine notification feature.
        enabled: false
        ## The default setting for the quarantine notification frequency for new users:
        ## - NEVER: Sending of a quarantine notification is disabled for the user.
        ## - IMMEDIATELY: Sending of a quarantine notification happens immediately if a message for the user is quarantined.
        ## - DAILY: Sending the quarantine notification every day at the time specified in the dailyCron option.
        ## - WEEKLY: Sending the quarantine notification once a week at the time specified in the weeklyCron option.
        frequency: DAILY

Every user with access to a mailbox can configure the notification settings for that specific mailbox. The notification setting per mailbox is global, so for shared mailboxes the setting is changeable by every user that has SSQ access to that mailbox. The defaults specified in the guarded_tenants.yml file apply only until the first time that a user logs in for that specific mailibox. Afterwards, this mailbox has its own configuration and if you change guarded_tenants.yml, it will not affect the mailbox anymore. Therefore, if you want to change the config for all mailboxes after they have already been used in SSQ, you have to perform an SQL query on XCC. In the example below, all users who had notifications individually disabled will have their notification frequency set to IMMEDIATELY:

SELECT * FROM xcc.user_settings_quarantine_notification;
UPDATE xcc.user_settings_quarantine_notification SET frequency='IMMEDIATELY' WHERE frequency='NEVER';

SSQ daily/weekly user digest

It is possible to receive periodical SSQ digests instead of immediate notifications about quarantined single messages. You can set the digest to be sent daily or weekly. And you can also change the default USER_QUARANTINE_DIGEST template. A sample digest can look like the one below:

To enable SSQ digest:

Open the guarded_tenants.yml file and make sure the notifications are enabled in as described in Notifications.
Set your preferred notification frequency to DAILY or WEEKLY.
Under the quarantine section, add the following digest block:

shared/guarded_tenants.yml

tenants:
  - name: xorlab
    bccFallbackDomain: xorlab.com
    domains:
      - xorlab.com
    quarantine:
      notifications:
        enabled: true
        frequency: DAILY
      digest:
         ## The maximum number of recent quarantined messages mentioned in the daily/weekly digest email.
         mentionedEntries: 10
         ## Daily digest frequency. It must be written in the following format (default: send daily digest at the beginning of each workday):
         ## .------------------ second (0 - 59)
         ## | .---------------- minute (0 - 59)
         ## | | .-------------- hour (0 - 23)
         ## | | | .------------ day of month (must be a *)
         ## | | | | .---------- month (must be a *)
         ## | | | | | .-------- period of week (e.g., MON-FRI)
         ## * * * * * *
         ## Note that sending daily digest emails is not instantaneous and takes at least `shippingTimespanMinutes`
         dailyCron: "0 0 0 * * MON-FRI"
         ## Weekly digest frequency. It must be written in the following format (default: send weekly digest at the beginning of each work weak):
         ## .------------------ second (0 - 59)
         ## | .---------------- minute (0 - 59)
         ## | | .-------------- hour (0 - 23)
         ## | | | .------------ day of month (must be a *)
         ## | | | | .---------- month (must be a *)
         ## | | | | | .-------- day of week (MON, TUE, WED, THU, FRI, SAT, or SUN)
         ## * * * * * *
         ## Note that sending weekly digest emails is not instantaneous and takes at least `shippingTimespanMinutes`
         weeklyCron: "0 0 0 * * MON"
         ## Default time zone of this tenant.
         zoneId: "Europe/Zurich"

In mentionedEntries, set the maximum number of recently quarantined messages mentioned in the daily/weekly digest email.
For the dailyCron and weeklyCron parameters, you can use online tools such as crontab guru to create your cron schedule.
Click the PUBLISH button to activate changes.

Integrate shared mailboxes

Token based authentication

There is no further configuration required for Token based authentication with shared mailboxes, since the shared mailbox receives the login token via email.

SAML/IDP based authentication

The user access to shared mailboxes is specified during login time. If the user logs in via SAML, the IDP has to provide the list of accessible mailboxes in the SAML token. If the user logs in via an LDAP query, the LDAP server needs to contain the list of accessible mailboxes. To integrate shared mailboxes, you need to:

Configure your IDP or LDAP server to contain the per-user accessible mailboxes. We currently only provide instructions if you use AzureAD as IDP: Shared mailboxes.
Configure the mapping for the emails attribute in the xorlab auth.yml configuration file (see SAML or LDAP)

Generate autoLogin token

The autoLogin token allows access to a specific mailbox’s SSQ portal without requiring a quarantine notification email. This can be useful for testing autoLogin configuration or providing access to a user on demand.

Prerequisites

Before using this endpoint, ensure the following requirements are met:

You need the xcc_user_impersonate permission which is granted to the admin role by default
The mailbox needs to have autoLoginLink enabled via guarded_tenants.yml (can hot-reload)
Security warning: The resulting token will give anyone access to that mailbox

https://<your.xorlab.instance>/api/v2/autologin/v1/generateToken?mailbox=test@example.com

Triggering quarantine access notification

This endpoint allows you to send an email notification to a specific mailbox, helping users regain access to the SSQ portal using the AutoLogin link feature. It is intended to be used with the autoLogin link feature for users to re-gain access to the SSQ portal.

https://<your.xorlab.instance>/api/v2/emailNotification/v1/sendQuarantineAccessNotification?mailbox=test@example.com

​Prerequisites

​SSQ Role

​Token based authentication

​Accessible email addresses

​Testing SSQ with password file authentication

​Configuration

​Appearance, language, and notifications

​SSQ quarantines

​Notifications

​SSQ daily/weekly user digest

​Integrate shared mailboxes

​Token based authentication

​SAML/IDP based authentication

​Generate autoLogin token

​Prerequisites

​Triggering quarantine access notification

Prerequisites

SSQ Role

Token based authentication

Accessible email addresses

Testing SSQ with password file authentication

Configuration

Appearance, language, and notifications

SSQ quarantines

Notifications

SSQ daily/weekly user digest

Integrate shared mailboxes

Token based authentication

SAML/IDP based authentication

Generate autoLogin token

Prerequisites

Triggering quarantine access notification