> ## 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 with a Password File

xorlab Security Platform users can be authenticated using a static password file. Similarly to [LDAP-based authentication](/9.0/ldap-based-authentication), the configuration of the backend is defined in the `fileAuthDataSources:` subsection of the `usernamePasswordAuthBackends:` section in the `auth/auth/auth.yml` file.

<Note>
  Before you start configuring this backend, please read the [Authentication](/9.0/authentication) article, if you haven’t already.
</Note>

Generally, we don’t recommend this authentication method as it’s more vulnerable than the others, e.g., it is prone to credential abuse and doesn’t allow 2FA. If you really need to use it, please make sure to follow these two principles:

* Use secure passwords or passphrases, i.e., make them unique, random, and long; preferably create them in a password generator of your favorite password manager or use an online service like [Bitwarden](https://bitwarden.com/password-generator/).
* Don’t share accounts.

## Enable Logging

With this authorization method, it’s good to know whether there were any unsuccessful login attempts. You can use the logging system for that:

1. Follow the instructions for logging [audit trail events](/9.0/logging-events#audit-trail-events) to create a log for the `audit.access.denied` event.

2. Your `auth/auth/logback-audit.xml` config file should look like the one below:

   ```xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <included>
    <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
      <syslogHost>syslog.example.com</syslogHost>
      <port>514</port>
      <protocol>UDP</protocol>
      <facility>LOCAL0</facility>
      <encoder>
      <pattern>%jsonMsg%n</pattern>
      </encoder>
    </appender>

    <!-- Log all unsuccessful login attempts -->
    <logger name="audit.access.denied">
      <appender-ref ref="syslogAppender"/>
    </logger>
   </included>
   ```

If you want to log all login attempts—both unsuccessful and successful—just change the `logger name` value to `"audit.access"`.

## Basic Configuration

The following configuration example shows how to enable this option:

```yaml theme={null}
enabledAuthBackends:
  - examplePassword

usernamePasswordAuthBackends:
  examplePassword:
    enabledAuthDataSources:
      - passwordFile

    fileAuthDataSources:
      passwordFile:
        file: passwordFile.yml
```

In this example, we defined the `examplePassword` backend, then we configured it under the `usernamePasswordAuthBackends:` section:

* in the `enabledAuthDataSources` key, we set the only source of auth data to `passwordFile`, then
* in the `file` key for this source under `fileAuthDataSources`, we pointed to the `passwordFile.yml` file which contains the password.

## Password file

Using [Expert Editor](/9.0/expert-editor), open the default `passwordFile.yml` located in `auth/auth/` and edit it. Use the example below to create your own password file:

```yaml theme={null}
users:
  - username: admin
    tenant: customerA
    displayName: The Admin
    passwordHash: "<ADD PWD HASH HERE>"
    emails: ["email1@example.com", "email2@example.com"]
    roles:
      - xcc_admin
  - username: user1
    tenant: customerA
    passwordHash: "{bcrypt}$2y$10$.4If2RFwcvHRrxlR98m9ju/mCRYCHLAYULByGXvJY.jBuK2/bckZu"
    roles:
      - xcc_analyst
```

All users are listed under the `users:` section and their available attributes are explained in the table below:

| Attribute      | Value                                                                                                     |
| :------------- | :-------------------------------------------------------------------------------------------------------- |
| `username`     | Unique user name                                                                                          |
| `tenant`       | The `tenant` attribute should reference either `name` or `authTenantId`, defined in guarded\_tenants.yml  |
| `displayName`  | More descriptive user name                                                                                |
| `passwordHash` | Hash value of a password (see *[Password hash generator](#password-hash-generator)* below)                |
| `emails`       | List of emails associated with the user                                                                   |
| `roles`        | Role in AG assigned to the user (see *[Users, Roles, and Permissions](/9.0/users-roles-and-permissions)*) |

### Password hash generator

1. Run the `docker exec -it auth_auth create_hash` command on the **XCC** terminal to generate a password hash from the password you enter and re-type when prompted. You should get the output similar to the one below:
   ```shell theme={null}
   $ docker exec -it auth_auth create_hash
   ActiveGuard password hash generator
   Password to hash: 1234
   Hashed password:
   {bcrypt}$2a$10$YOmSE8jp9fSBlVP3P3KEh.UnezedRVSnBZL7x5xWQvYfiBF0z49Uy
   ```
2. Copy the generated hash, open Expert Editor and paste it into `auth/auth/passwordFile.yml` as a value for the `passwordHash` key of a particular user.
3. Once you finish adding password hashes for all users, click **PUBLISH** to deploy changes. After one minute, the changes will be hot-reloaded and active.

In case you don't have access to the XCC terminal, run `htpasswd -nBC 10 ignore | sed 's/ignore:/{bcrypt}/'` on a Linux terminal to generate a password hash as alternative to step 1 above.

### Multi-Tenant Configuration

Please refer to [Multi-Tenant Password Authentication](/9.0/multi-tenancy-authentication#password-file) for instruction on how to configure password file-based authentication in a multi-tenant environment.