---
id: runbook-authentication-server
title: Authentication Server runbook
---

The Authentication Server is a core Deephaven infrastructure service responsible for authenticating users and issuing authentication tokens. It validates credentials through multiple authentication methods. See the [Authentication Service overview](../core-components/authentication.md) for a full description of services provided.

## Impact of Authentication Server failure

| Level            | Impact                                                    |
| :--------------- | :-------------------------------------------------------- |
| Sev 1 - Critical | New users will be unable to log in or create new queries. |

> [!CAUTION]
> Users with valid, non-expired authentication tokens can continue working during an Authentication Server outage, but new logins and token refreshes will fail.

## Authentication Server dependencies

The Authentication Server requires:

1. **etcd cluster** — Must be running and accessible for ACL storage (if using etcd for ACLs).
2. **MySQL/MariaDB** — Must be running if using MySQL for ACL storage.
3. **etcd client configuration files** — Located at `/etc/sysconfig/deephaven/etcd/client`.
4. **LDAP/Active Directory** — Must be accessible if using LDAP authentication.
5. **SAML Identity Provider** — Must be accessible if using SAML authentication.

The Authentication Server does not depend on the Configuration Server, allowing it to start independently.

## Supported authentication methods

The Authentication Server supports multiple authentication methods:

- **Built-in username/password** — Stored in ACL database (etcd or MySQL).
- **LDAP/Active Directory** — Validates credentials against directory service.
- **SAML 2.0** — Integrates with enterprise identity providers.
- **DSA keys** — Public key authentication for programmatic access.

## Configuring the Authentication Server

**ACL backend configuration:**

For etcd-based ACLs:

```properties
acls.dataSource=etcd
```

For MySQL-based ACLs:

```properties
acls.dataSource=mysql
db.url=jdbc:mariadb://localhost:3306/dbacl_iris
db.user=iris
db.password=<encrypted-password>
```

> [!CAUTION]
> TLS should never be disabled unless you have very strong network isolation and fully trust all users with access to your network.

## Checking Authentication Server status

Check process is running with monit:

```bash
dh_monit status authentication_server
```

Expected output should show status `Running`.

Test authentication endpoint connectivity:

```bash
# Test if server is responding (adjust hostname and port as needed)
# Use --insecure if the server uses a self-signed certificate
grpcurl --insecure localhost:22123 list
```

## Viewing Authentication Server logs

View application log:

```bash
cat /var/log/deephaven/authentication_server/AuthenticationServer.log.current
```

Tail the log to follow in real-time:

```bash
tail -f /var/log/deephaven/authentication_server/AuthenticationServer.log.current
```

List historical log files:

```bash
ls -ltr /var/log/deephaven/authentication_server/authentication_server.log.????-??-??
```

View process stdout/stderr logs:

```bash
cat /var/log/deephaven/authentication_server/authentication_server.log.$(date +%Y-%m-%d)
```

## Restart procedure

Restart the Authentication Server:

```bash
dh_monit restart authentication_server
```

Verify the restart was successful:

```bash
dh_monit status authentication_server
```

Monitor the log during startup:

```bash
tail -f /var/log/deephaven/authentication_server/AuthenticationServer.log.current
```

**Expected startup messages:**

- Successful connection to etcd or MySQL.
- Server listening on configured port.
- No authentication backend errors.

## Checking dependencies

### Check etcd status

If using etcd for ACLs:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/etcdctl.sh endpoint status --write-out table
```

### Check MySQL status

If using MySQL for ACLs:

```bash
sudo systemctl status mariadb
```

Test MySQL connectivity:

```bash
sudo mysql -e "SELECT COUNT(*) FROM users" dbacl_iris
```

## Authentication modes and ACL integration

### Built-in authentication

Users and password hashes are stored directly in the ACL database. Managed through the [ACL Write Server](runbook-acl-write-server.md) or `dhconfig acls` commands.

### LDAP authentication

Validates credentials against LDAP/Active Directory. Users must still exist in the ACL database for authorization. See [LDAP configuration](../configuration/ldap.md) for setup and the full property reference.

### SAML authentication

Delegates authentication to an enterprise identity provider (IdP). See [SAML configuration](../configuration/saml-auth.md) for setup and the full property reference.

### DSA key authentication

Public key authentication for programmatic API access. The `dhconfig acls publickeys` subcommand manages the public keys used for DSA key authentication. See [dhconfig acls command reference](../configuration/dhconfig/acls.md) for usage.

## Configuration files and locations

**monit configuration:** `/etc/sysconfig/illumon.d/monit/authentication_server.conf`

**Property files:**

- `/etc/sysconfig/illumon.d/resources/iris-common.prop`
- `/etc/sysconfig/illumon.d/resources/authentication_server.prop`

**TLS keystore:** `/etc/sysconfig/deephaven/auth/keystore.authserver.p12`

**Keystore passphrase:** `/etc/sysconfig/deephaven/auth/.auth_passphrase`

**Log directory:** `/var/log/deephaven/authentication_server/`

## Related documentation

- [Authentication overview](../core-components/authentication.md)
- [System processes overview](../architecture/architecture-overview.md)
- [SAML authentication setup](../configuration/saml-auth.md)
- [LDAP authentication setup](../configuration/ldap.md)
- [Managing ACLs](../security/hardening-technical-controls.md)
- [ACL Write Server runbook](runbook-acl-write-server.md)
- [etcd runbook](runbook-etcd.md)