StarVault SSH Agent

StarVault SSH Agent — это утилита, предназначенная для организации безопасного доступа к серверам по SSH без хранения статических паролей на стороне хоста. При аутентификации используется одноразовый пароль, который генерируется и хранится в StarVault. Таким образом, доступ к системе возможен только при наличии валидного временного секрета, а сам сервер не содержит долгоживущих учетных данных.

Инструмент интегрируется с механизмами SSH-аутентификации и автоматически запрашивает одноразовый пароль у StarVault в момент входа. Такой подход исключает необходимость ручного ввода или распространения постоянных паролей, повышает контроль доступа и минимизирует риск компрометации учетных записей.

1. Предварительные условия

Предварительно у вас должны быть настроены:

Виртуальная машина (ВМ) с установленным и проинициализированным StarVault;
ВМ для настройки starvault-ssh-agent.

В данном руководстве в блоках кода будут использоваться следующие обозначения:

<username> - имя пользователя;
<password> - пароль от пользователя;
<addr> - FQDN или ip до StarVault;
<cert_path> - путь до CA сертификата к <addr>;
<ip> - ip-адрес ВМ, на которой выполняется настройка starvault-ssh-agent.

Замените эти обозначения на свои данные.

2. Подготовка

В рамках работы с starvault-ssh-agent убедитесь, что на используемой учетной записи в StarVault есть следующие разрешения (если не используется root аккаунт):

# Требуется чтобы можно было конфигурировать плагины
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}
# Требуется для конфигурации ssh плагина
path "ssh/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Требуется для включения userpass метода авторизации
path "sys/auth/userpass" {
  capabilities = [ "update" ]
}

# Для создания политик для пользователей
path "sys/policies/acl/*" {
  capabilities = [ "read", "create", "update" ]
}

# Для создания пользователей
path "auth/userpass/users/*" {
  capabilities = [ "read", "create", "update" ]
}

Включите ssh-плагин:
```
starvault secrets enable ssh
```
Включите метод авторизации userpass:
```
starvault auth enable userpass
```

Создайте роль для OTP для пользователя:

starvault write ssh/roles/otp_<username>_role \
	key_type=otp \
    default_user=<username> \
    cidr_list=0.0.0.0/0

Создайте политику для пользователя. Для этого создайте файл user_policy.hcl со следующим содержанием:

path "ssh/*" {
  capabilities = [ "list" ]
}
path "ssh/creds/otp_<username>_role" {
  capabilities = ["create", "read", "update"]
}

Сохраните файл.

В данном руководстве показано, как создать политику через CLI, однако вы можете так же создать ее через веб-интерфейс. Перейдите к разделу Создание политик

Создайте политику в StarVault с помощью команды:
```
starvault policy write <username>_ssh_policy ./user_policy.hcl
```

Создайте пользователя.

starvault write auth/userpass/users/<username> password="<password>" policies="<username>_ssh_policy"

3. Установка и конфигурирование

3.1. Установка

Выполните установку пакета с помощью команды.

sudo dnf install starvault-ssh-agent

Дополнительно ознакомьтесь с инструкцией подключения репозитория rpm/apt.

3.2. Конфигурирование

Измените файл конфигурации /etc/starvault-ssh-agent.d/config.hcl в соответствии вашими требованиями.

starvault_addr = "https://<addr>"  (1)
tls_skip_verify = false
namespace = <namespace> (2)
ca_cert = "<cert_path>" (3)
ca_path = "<ca_path>" (4)
ssh_mount_point = "ssh" (5)
allowed_roles = "*" (6)
allowed_cidr_list = <block1, block2> (7)

1	`starvault_addr` (тип: string) - адрес до StarVault.
2	`namespace` (тип: string) - namespace ssh плагина. Если не выставлен - namespace не используется. Необязателен к заполнению.
3	`ca_cert` (тип: string) - путь до CA сертификата в pem формате. Игнорируется при опции `-dev`. Необязателен к заполнению.
4	`ca_path` (тип: string) - путь до директории с CA сертификатами. Игнорируется при опции `-dev`. Необязателен к заполнению.
5	`ssh_mount_point` (тип: string) - точка монтирования (путь) до ssh плагина.
6	`allowed_roles` (тип: list) - cписок ролей разделенных запятыми. Если не нужно ограничение то выставляется ``. Необязателен к заполнению.*
7	`allowed_cidr_list` (тип: list) - список блоков CIDR через запятую. Если IP-адрес, который пользователь использует для подключения к хосту, отличается от адреса(ов) сетевого интерфейса(ов) хоста (например, если адрес находится за NAT), то starvault-ssh-agent не сможет самостоятельно аутентифицировать IP. В таких случаях IP-адрес, возвращаемый StarVault, будет сопоставляться с блоками CIDR в этом списке. Если совпадение найдено, аутентификация будет успешной (использовать с осторожностью). Необязателен к заполнению.

Данная конфигурация является примером, с помощью которого вы сможете составить свой файл.

Перейдите к файлу по пути /etc/pam.d/sshd.

Опционально. Сделайте копию файла для восстановления, в случае если что-то пойдет не так.

Перейдите к редактированию файла. Закомментируйте или удалите стандартную unix-авторизацию и пропишите вместо нее starvault-ssh-agent.

auth requisite pam_exec.so quiet expose_authtok log=/var/log/vault-ssh.log /usr/local/bin/starvault-ssh-agent -config=/etc/starvault-ssh-agent.d/config.hcl

auth optional pam_unix.so not_set_pass use_first_pass nodelay

В более новых системах не используется параметр not_set_pass(например на centos 7 этот параметр все еще присутствует).

Отредактируйте файл конфигурации sshd. Отключите авторизацию по паролю, включите pam и интерактивную авторизацию, как показано в примере ниже.
```
KbdInteractiveAuthentication yes
UsePAM yes
PasswordAuthentication no
```
В старых системах используется ChallengeResponseAuthentication, вместо KbdInteractiveAuthentication.
Перезапустите sshd с помощью команды.
```
sudo systemctl restart sshd
```

Проверьте конфигурацию starvault-ssh-agent.

starvault-ssh-agent -verify-only -dev -config /etc/starvault-ssh-agent.d/config.hcl

3.3. Проверка

Получите токен пользователя StarVault.

starvault login -method=userpass username=<username> password=<password> -format=json

Сгенерируйте OTP с помощью команды.
```
starvault write ssh/creds/otp_<username>_role ip=<ip>
```
В выводе обратите внимание на поле key. Данное поле содержит OTP.
Перейдите к ВМ, предварительно отключив авторизацию по ключу.
```
ssh -o PubkeyAuthentication=no <username>@<ip>
```
Перед входом убедитесь, что пользователь создан на сервере и под ним можно авторизоваться.

4. Распространенные ошибки и решения

4.1. Ошибка: не существует опции

Текст ошибки

pam_unix(sshd:auth): unrecognized option [not_set_pass]

Данная ошибка указывает на то, что данной опции не существует.

Решение

Необходимо убрать параметр из конфигурации pam и сохранить.

4.2. Ошибка: пользователь не создан на сервере

Текст ошибки

uuid string is wrong length

Данная ошибка в логах starvault-ssh-agent может указывать на то, что пользователь не создан на сервер.

Решение

Вернитесь к шагу создания пользователя и проверьте, что создали его верно.