# MSSQL Server - Windows Authentication

- Updated on Feb 25, 2026
- Published on Oct 29, 2025

- 5 minute(s) read

This feature is supported for Docker and Podman deployments running v42 or later. It is not supported for Kubernetes deployments.

Microsoft offers two authentication methods for MSSQL databases: SQL Server authentication and Windows authentication. Windows authentication is Microsoft's recommended authentication method, as it leverages Linux's Kerberos Ticket Granting Ticket (TGT) and provides a higher level of security than SQL Server authentication. As a result, implementing Windows authentication can reduce potential compliance overhead and facilitate installations and upgrades in Microsoft ecosystems.

By default, MSSQL databases in Hyperscience use SQL Server authentication. The steps required to enable Windows authentication for MSSQL Server access depend on which type of `ccache` you’re using: `KCM` or `FILE`.

## _KCM ccache_

This article provides one illustrative way to perform the setup. You should adapt it as needed to fit your organization's Active Directory configuration, security policies, operational processes, and automation tools.

1. **Create an Active Directory (AD) user** that will be used by Hyperscience to authenticate to SQL Server.

2. **Create the database and grant proper permissions** to the AD user.

3. **Set up Kerberos TGT** on every machine running Hyperscience.

4. **Add relevant information to the “.env” file** and start the application.

### 1. Create an AD User for Windows authentication.

```shell
New-ADUser -Name "hsuser" -SamAccountName "hsuser" -AccountPassword (Read-Host -AsSecureString "Enter Password") -Enabled $true
Set-ADUser -Identity "hsuser" -PasswordNeverExpires $true
Get-ADUser hsuser
```

2. Export `keytab` for the user (`hsuser`).

```shell
ktpass -princ hsuser@EXAMPLE.COM -mapuser hsuser@EXAMPLE.COM -pass <password> -out C:\hsuser.keytab -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1
```

3. Configure SQL Server to allow `hsuser` to log in.

```sql
CREATE LOGIN [EXAMPLE\hsuser] FROM WINDOWS;
USE [YourDatabase];
CREATE USER [EXAMPLE\hsuser] FOR LOGIN [EXAMPLE\hsuser];
ALTER ROLE db_owner ADD MEMBER [EXAMPLE\hsuser];
SELECT name, type_desc FROM sys.database_principals WHERE name = 'EXAMPLE\hsuser';
```

4. Copy `keytab` to RHEL and set the required permissions.

```shell
sudo cp /path/to/hsuser.keytab /etc/hsuser.keytab
sudo chown 1000:1000 /etc/hsuser.keytab
sudo chmod 600 /etc/hsuser.keytab
```

5. Allow containerized Hyperscience to access the SSSD Kerberos credential socket.

Create the following policy module in a file named `container_sssd_socket.te`:

```plaintext
module container_sssd_socket 1.0;
require {
    type container_t;
    type sssd_var_run_t;
    class sock_file { read write getattr open };
    class unix_stream_socket { connectto };
}
allow container_t sssd_var_run_t:sock_file { read write getattr open };
allow container_t sssd_var_run_t:unix_stream_socket connectto;
```

Then, compile and install the policy module:

```bash
checkmodule -M -m -o container_sssd_socket.mod container_sssd_socket.te
semodule_package -o container_sssd_socket.pp -m container_sssd_socket.mod
sudo semodule -i container_sssd_socket.pp
```

6. Set up the `systemd` service and timer for TGT renewal.

```shell
# /etc/systemd/system/hsuser-tgt-renew.service
sudo tee /etc/systemd/system/hsuser-tgt-renew.service > /dev/null <<EOF
[Unit]
Description=Renew Kerberos TGT for hsuser
[Service]
Type=simple
User=hsuser
ExecStart=/usr/bin/kinit -kt /etc/hsuser.keytab hsuser@EXAMPLE.COM
EOF
```

```shell
# /etc/systemd/system/hsuser-tgt-renew.timer
sudo tee /etc/systemd/system/hsuser-tgt-renew.timer > /dev/null <<EOF
[Unit]
Description=Periodic Kerberos TGT renewal for hsuser
[Timer]
OnBootSec=1min
OnUnitActiveSec=30min
[Install]
WantedBy=timers.target
EOF
```

```shell
sudo systemctl daemon-reload
sudo systemctl enable --now hsuser-tgt-renew.timer
```

7. Modify the “.env” file.

Update your “.env” file with the following example configuration:

```bash
FORMS_DB_TYPE=mssql
FORMS_DB_HOST=SQLSERVER-SPN.EXAMPLE.COM
FORMS_DB_NAME=YourDatabase
FORMS_DB_USER=
FORMS_DB_PASS=
SQLSERVER_OPTIONS_EXTRA_PARAMS=Encrypt=Yes;TrustServerCertificate=Yes;Trusted_Connection=Yes;
HS_KERBEROS_KCM_SOCKET=/run/.heim_org.h5l.kcm-socket
KRB5CCNAME=KCM:
```

8. Verify the configuration.

Run `./run.sh manage check` and ensure that there are no errors.

Your Hyperscience installation should now be configured to access SQL Server using Windows authentication.

If you are installing a new Hyperscience, you can proceed with the rest of the installation steps.

## _FILE ccache_

This document provides one illustrative way to perform the setup. You should adapt it as needed to fit your organization's Active Directory configuration, security policies, operational processes, and automation tools.

1. **Create an Active Directory (AD) user** that will be used by Hyperscience to authenticate to SQL Server.

2. **Create the database and grant proper permissions** to the AD user.

3. **Set up Kerberos TGT** on every machine running Hyperscience.

4. **Add relevant information to the “.env” file** and start the application.

### 1. Create an AD user for Windows authentication.

2. Export `keytab` for the user (`hsuser`).

```shell
ktpass -princ hsuser@EXAMPLE.COM -mapuser hsuser@EXAMPLE.COM -pass <password> -out C:\hsuser.keytab -ptype KRB5_NT_PRINCIPAL -crypto AES256-SHA1
```

3. Configure SQL Server to allow `hsuser` to log in.

4. Copy `keytab` to RHEL and set the required permissions.

```shell
sudo cp /path/to/hsuser.keytab /etc/hsuser.keytab
sudo chown 1000:1000 /etc/hsuser.keytab
sudo chmod 600 /etc/hsuser.keytab
```

5. Prepare the folder for the TGT cache.

You can prepare the TGT cache directory in one of two ways:

- Manually create the directory.

```shell
sudo mkdir -p /var/run/hs_krb5_cache/krb5cc_1000
sudo chown 1000:1000 /var/run/hs_krb5_cache/krb5cc_1000
sudo chcon -R -t container_file_t /var/run/hs_krb5_cache/krb5cc_1000
```

- Use `systemd-tmpfiles` for automatic directory creation.

Create a `tmpfiles.d` entry to ensure the directory exists with the correct permissions and SELinux label after every reboot:

```shell
# /etc/tmpfiles.d/hs_krb5_cache.conf
d /var/run/hs_krb5_cache/krb5cc_1000 0700 1000 1000 - -
Z /var/run/hs_krb5_cache/krb5cc_1000 - - - - container_file_t
```

After creating this file, run:

```shell
sudo systemd-tmpfiles --create /etc/tmpfiles.d/hs_krb5_cache.conf
```

6. Set up the `systemd` service and timer for TGT renewal.

### 6. Set up the `systemd` service and timer for TGT renewal.

```shell
# /etc/systemd/system/hsuser-tgt-renew.service
sudo tee /etc/systemd/system/hsuser-tgt-renew.service > /dev/null <<EOF
[Unit]
Description=Renew Kerberos TGT for hsuser
[Service]
Type=simple
User=hsuser
Environment="KRB5CCNAME=/var/run/hs_krb5_cache/krb5cc_1000"
ExecStartPre=/usr/bin/mkdir -p /var/run/hs_krb5_cache
ExecStartPre=/usr/bin/chown -R 1000:1000 /var/run/hs_krb5_cache
ExecStartPre=/usr/bin/chcon -R -t container_file_t /var/run/hs_krb5_cache
ExecStart=/usr/bin/kinit -kt /etc/hsuser.keytab hsuser@EXAMPLE.COM
EOF
```

```shell
sudo systemctl daemon-reload
sudo systemctl enable --now hsuser-tgt-renew.timer
```

7. Modify the “.env” file.

Update your “.env” file with the following example configuration:

```bash
FORMS_DB_TYPE=mssql
FORMS_DB_HOST=SQLSERVER-SPN.EXAMPLE.COM
FORMS_DB_NAME=YourDatabase
FORMS_DB_USER=
FORMS_DB_PASS=
SQLSERVER_OPTIONS_EXTRA_PARAMS=Encrypt=Yes;TrustServerCertificate=Yes;Trusted_Connection=Yes;
HS_KERBEROS_CACHE_FILE=/var/run/hs_krb5_cache
KRB5CCNAME=FILE:/var/www/forms/forms/krb5_cache/krb5cc_1000
```

8. Verify the configuration.

Run `./run.sh manage check` and ensure that there are no errors.

Your Hyperscience installation should now be configured to access SQL Server using Windows authentication.

If you are installing a new Hyperscience, you can proceed with the rest of the installation steps.