Authentication

Articles in this section will show you how to integrate your authentication backend with xorlab Security Platform. You can authenticate in XSP using one or more of the following methods:

An existing LDAP directory
An existing identity provider with SAML2 support
A static password file
An auto-login link (provides SSQ access only)

Auto-Login Authentication provides end-users with direct access to the Self-Service Quarantine via a tokenized link included in quarantine notification emails. This method allows users to review their quarantined emails without requiring additional authentication. For setup instructions and more details, refer to the [Auto-Login Authentication](authentication-auto-login-link.md] documentation.

Authentication Process

For all other authentication methods, the process involves three steps:

Performing authentication in case users provide their credentials directly to XSP (password file) or verifying federated authentication in case users are identified by a third-party identity provider (SAML2 authentication).
Extracting the set of roles associated with the user who is being authenticated (also called an “authorization”) and assigning appropriate XCC roles. For example, a user with a role named ag.analyst in Azure Active Directory can be assigned to the xcc_insights and xcc_quarantine_user roles in XCC, thus having access to both quarantined messages and insights.
Mapping (in other words, reading and assigning) all values required for an XSP user from the authentication context, e.g., user’s email addresses obtained from the identity provider are passed to XCC and stored in the emails attribute.

An XSP user has the following attributes:

User name—also called a “subject” (required)
Display name (optional)
A list of email addresses associated with the user (optional but read below); the first email address is considered to be the primary email address
A list of roles associated with the user (required)

The list of email addresses is technically optional. However, in the case of a user without at least one associated email address, the SSQ (Self-Service Quarantine) in xorlab Security Platform will not work properly.

Username password authentication

With the username password authentication backend, xorlab Authentication Service acts as an identity provider and service provider at the same time. It will display a login form featuring the username and password entry. The user input will be processed using the configured data sources for the username password backend. To use this backend, you will have to configure data sources. The currently supported data source types for the username password backend are:

LDAP
a password file

For the detailed information on how to integrate authentication based on LDAP or a password file, please see LDAP-based Authentication or Authentication with a Password File, respectively.

LDAP connections might require additional certificate configuration.

SAML2 authentication

With the SAML2 authentication backend, xorlab Security Platform acts as a service provider (a Relying Party in SAML terms) only. For the user identifying part, you have to configure an identity provider (or an Asserting Party in SAML terms). For the procedure of integrating SAML2-based authentication, please see SAML-based Authentication and SAML Authentication Using AAD Services.

SAML2 connections might require additional certificate configuration.

Authentication using multiple backends

xorlab Security Platform supports using multiple authentication backends at the same time within one instance, which means you are not limited to just one authentication method for all users. You can allow some users to be authenticated with one method but others will have to authenticate differently—for example, regular users will be authenticated using SAML and admins will rely on the good old password file authentication.

One username password auth backend onlyCurrently, you can’t specify multiple username password authentication backends (config: usernamePasswordAuthBackends) within the same Authentication Service instance.

Configuring the backends

Configure the possible auth backends in the auth/auth/auth.yml file using the XCC Expert Editor:

Open Expert Editor.
Expand the auth folder and its auth subfolder.
Click the auth.yml file to open it.

The default auth.yml file contains commented out lines with keys and sample values for all types of auth backends along with descriptions to help you configure your custom backend. Let’s take a look at a clean, sample config file:

enabledAuthBackends:
  - exampleSaml
  - examplePassword

usernamePasswordAuthBackends:
  examplePassword:  # this identifier will determine the name of the backend
    enabledAuthDataSources:
      - passwordFile
    
    fileAuthDataSources:
      passwordFile:
        file: passwordFile.yml

saml2AuthBackends:
  exampleSaml:  # this identifier will determine the name of the backend
    # SAML backend config goes here

In this configuration, under enabledAuthBackends, we define two authentication backends: exampleSaml and examplePassword, which are then configured under saml2AuthBackends and usernamePasswordAuthBackends, respectively. The order of backend entries in enabledAuthBackends and enabledAuthDataSources (the latter is used for password file and LDAP configs) is important: the first one will be default. The default backend will be used in all cases where users access XSP without specifying the authentication backend.

Authentication using a non-default backendIn the configuration above, if a user wants to authenticate using the examplePassword backend, they have to add a special query string argument _agAuthBackend to the XSP URL, e.g., https://activeguard.customer.com/?_agAuthBackend=examplePassword.

Certificate configuration

The following instructions show how to add the certificate of a custom certificate authority (CA) to the trust store, which will be used by xorlab Security Platform to verify all secure authentication connections (LDAP and SAML2).

Trust storeYou must have the certificate(s) ready in a PKCS12 trust store named truststore.p12. The trust store must contain all certificates required for all trusted communication initiated by xorlab Authentication Service (LDAP, SAML2, etc.). For every service, only the outermost signer certificate is required to be a part of the trust store as long as the service supplies a correct certificate chain. By inserting a concrete server certificate into the trust store, that certificate is pinned explicitly.To create a trust store, you can use Keytool or OpenSSL. In a nutshell, you have to add your certificate file (.pem, .crt, .cer, .p7b, or .p7c) to the trust store. You can do this with the following keytool command:keytool -import -file certificate.pem -alias ca1 -keystore truststore.p12This command will export your certificate.pem file to the truststore.p12 trust store file, giving the certificate a ca1 alias.

Open the auth/auth/auth.yml file using the XCC Expert Editor.

Add the following block and enter your custom value for the password parameter in case your provided trust store has a different password:

trustStore:
  # The type of the trust store to use. Default is PKCS12 which is also the default
  # these days when using the 'keytool' shipped with the JRE.
  type: pkcs12
  # The default trust store file. Defaults to 'truststore.p12'. Relative paths are resolved
  # relative to the config directory.
  file: truststore.p12
  # The trust store password.
  password: <trust_store_password>

Click PUBLISH to deploy changes.

Switch to the CLI of the XCC and execute the following instructions one by one:

sudo su -s /bin/bash xcc_backend
cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth

Copy the truststore.p12 file containing your certificate into the folder specified above.

Execute the following instructions one by one:

git add .
git commit -m "Adding truststore file"
exit

The Authentication service will restart automatically and apply the new configuration as described in How to Activate the Configuration.

Authentication request signing

This optional feature requires creating a key store containing the certificate of a custom certificate authority and a private key that is used to sign the authentication request. If authentication request signing is required by your IdP, follow these steps to create a key store and enable request signing in xorlab Security Platform:

Run this command in your shell to create a keystore.p12 key store file using the certificate in the certificate.crt file and a corresponding private key in the privateKey.key file:
openssl pkcs12 -export -in certificate.crt -inkey privateKey.key -out keystore.p12
After entering the command, you will be prompted to enter and verify an export password to protect the key store file. Remember this password as you will need it in step #6.

Switch to the CLI of the XCC and execute the following instructions one by one:

sudo su -s /bin/bash xcc_backend`
cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth

Copy the keystore.p12 file into the folder specified above.

Execute the following instructions one by one:

git add .
git commit -m "Adding keystore file"
exit

Open the auth/auth/auth.yml file using the XCC Expert Editor.

In the saml2AuthBackends section, under your IdP config (here as mySaml), add the following block and enter your key store password as the password parameter:

saml2AuthBackends:
  mySaml:
    idp:
      signingKeyStore:
        file: keystore.p12
        password: the-key-store-password

Click PUBLISH to deploy changes.

The Authentication service will restart automatically and apply the new configuration as described in How to Activate the Configuration.

​Auto-Login Authentication

​Authentication Process

​Username password authentication

​SAML2 authentication

​Authentication using multiple backends

​Configuring the backends

​Certificate configuration

​Authentication request signing

Auto-Login Authentication

Authentication Process

Username password authentication

SAML2 authentication

Authentication using multiple backends

Configuring the backends

Certificate configuration

Authentication request signing