> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.
# 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
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:
1. 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).
2. 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.
3. 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)](/9.0/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](/9.0/ldap-based-authentication)* or *[Authentication with a Password File](/9.0/authentication-with-a-password-file)*, respectively.
LDAP connections might require additional [certificate configuration](#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](/9.0/saml-based-authentication)* and *[SAML Authentication Using AAD Services](/9.0/saml-aad-authentication)*.
SAML2 connections might require additional [certificate configuration](#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 only**
Currently, 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](/9.0/expert-editor):
1. Open Expert Editor.
2. Expand the `auth` folder and its `auth` subfolder.
3. 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:
```yaml theme={null}
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 backend**
In 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 store**
You 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](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html) or [OpenSSL](https://www.ssl.com/how-to/create-a-pfx-p12-certificate-file-using-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.p12`
This command will export your `certificate.pem` file to the `truststore.p12` trust store file, giving the certificate a `ca1` alias.
1. Open the `auth/auth/auth.yml` file using the XCC [Expert Editor](/9.0/expert-editor).
2. Add the following block and enter your custom value for the `password` parameter in case your provided trust store has a different password:
```yaml theme={null}
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:
```
3. Click **PUBLISH** to deploy changes.
4. Switch to the CLI of the XCC and execute the following instructions one by one:
```shell theme={null}
sudo su -s /bin/bash xcc_backend
cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth
```
5. Copy the `truststore.p12` file containing your certificate into the folder specified above.
6. Execute the following instructions one by one:
```shell theme={null}
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](/9.0/activate-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:
1. 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:
```shell theme={null}
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.
2. Switch to the CLI of the XCC and execute the following instructions one by one:
```shell theme={null}
sudo su -s /bin/bash xcc_backend`
cd /var/lib/xorlab/xcc/config/work/ag_local/auth/auth
```
3. Copy the `keystore.p12` file into the folder specified above.
4. Execute the following instructions one by one:
```shell theme={null}
git add .
git commit -m "Adding keystore file"
exit
```
5. Open the `auth/auth/auth.yml` file using the XCC [Expert Editor](/9.0/expert-editor).
6. 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:
```yaml theme={null}
saml2AuthBackends:
mySaml:
idp:
signingKeyStore:
file: keystore.p12
password: the-key-store-password
```
7. Click **PUBLISH** to deploy changes.
The Authentication service will restart automatically and apply the new configuration as described in *[How to Activate the Configuration](/9.0/activate-configuration)*.