Настройка сущностей и групп удостоверений

StarVault поддерживает несколько методов аутентификации. Один и тот же метод можно включить на разных путях монтирования. Каждый клиент StarVault может иметь несколько учетных записей в различных провайдерах удостоверений, активированных на сервере.

Клиенты StarVault сопоставляются с сущностями, а их учетные записи в провайдерах аутентификации — с псевдонимами. Каждая сущность состоит из нуля или более псевдонимов. Движок секретов удостоверений внутренне управляет клиентами, которые распознаются StarVault.

1. Учетные записи

Шаги, описанные в данном руководстве, выполняются под учетной записью оператора.

2. Задача

Боб имеет учетные записи в userpass и LDAP. Оба метода аутентификации (userpass и LDAP) активированы на сервере StarVault, и он может аутентифицироваться, используя любую из своих учетных записей. Обе учетные записи принадлежат Бобу, однако между ними нет связи. Из-за этого нет возможности задать для них общие свойства.

3. Решение

Создайте сущность, представляющую Боба, и свяжите с ней псевдонимы, соответствующие каждой из его учетных записей. Можно установить дополнительные политики и метаданные на уровне сущности, чтобы обе учетные записи наследовали их.

Когда Боб аутентифицируется с использованием любой из своих учетных записей, идентификатор сущности привязывается к аутентификационному токену. При использовании таких токенов их идентификаторы сущностей фиксируются в журнале аудита, создавая запись действий, выполненных конкретными пользователями.

4. Предварительные требования

Для выполнения описанных в этом руководстве задач вам нужна среда StarVault.

Обратитесь к руководству по установке StarVault для установки StarVault.
Установите jq для обработки вывода JSON для удобочитаемости.

5. Требования к политике

Если вы не используете StarVault для тестирования или разработки (например, в dev-режиме -dev), рекомендуется аутентифицироваться в StarVault и получать токены с соответствующим набором политик в зависимости от вашей роли в организации.

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

# Настройка методов аутентификации
path "sys/auth" {
  capabilities = [ "read", "list" ]
}

# Полный доступ к настройке методов аутентификации
path "sys/auth/*" {
  capabilities = [ "create", "update", "read", "delete", "list", "sudo" ]
}

# Управление методом аутентификации userpass
path "auth/userpass/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}

# Просмотр вкладки "Политики" в UI
path "sys/policies" {
  capabilities = [ "read", "list" ]
}

# Создание и управление ACL-политиками через UI
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Управление политиками ACL
path "sys/policies/acl" {
  capabilities = [ "read", "list" ]
}

# Полный доступ к управлению политиками ACL
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Получение списка доступных движков секретов для извлечения accessor ID
path "sys/mounts" {
  capabilities = [ "read" ]
}

# Создание и управление сущностями и группами
path "identity/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

Если вы не знакомы с политиками, рекомендуется к прочтению руководство по политикам.

6. Настройка среды

В терминале установите переменную окружения STARVAULT_ADDR на адрес StarVault:
```
$ export STARVAULT_ADDR=<Public_Cluster_URL>
```
В терминале установите переменную окружения STARVAULT_TOKEN на значение токена:
```
$ export STARVAULT_TOKEN=<token>
```

Проверьте подключение к кластеру StarVault:

$ starvault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft

Включите движок хранения секретов Key/Value v2 на пути secret:
```
starvault secrets enable -path=secret kv-v2
```

Теперь сервер StarVault готов к использованию.

7. Создание сущности с псевдонимом

Вам необходимо создать новую сущность с назначенной базовой политикой. Сущность включает два псевдонима, каждому из которых назначена своя политика.

Пример сценария

У пользователя Боба Смита из ACME Inc. есть два набора учетных данных: bob и bsmith. Боб может проходить аутентификацию в StarVault, используя любую из его учетных записей. Чтобы управлять учетными записями пользователя и связать их с личностью Боба Смита в команде QA, вам нужно создать объект для Боба.

Для упрощения этого руководства вы будете работать с методом аутентификации userpass. В реальности пользователь bob может быть именем пользователя в Active Directory, а bsmith — именем пользователя Bob в LDAP. Чтобы сымитировать такое поведение, включите метод userpass в двух разных путях: userpass-test и userpass-qa. Это имитирует два разных типа методов аутентификации.

Блокировка пользователей. В StarVault функция блокировки пользователей включена по умолчанию для методов аутентификации userpass, approle и ldap.

7.1. Политика сценариев

base.hcl

path "secret/data/training_*" {
   capabilities = ["create", "read"]
}

test.hcl

path "secret/data/test" {
   capabilities = [ "create", "read", "update", "delete" ]
}

team-qa.hcl

path "secret/data/team-qa" {
   capabilities = [ "create", "read", "update", "delete" ]
}

В этом сценарии предполагается, что механизм секретов K/V v2 включен на пути секретов. Если вы не уверены, обратитесь к руководству по версионированному механизму секретов ключей/значений.

Создайте пользователей bob и bsmith с соответствующими политиками.

7.2. CLI команда

Создайте политику base

$ starvault policy write base -<<EOF
path "secret/data/training_*" {
   capabilities = ["create", "read"]
}
EOF

Создайте политику test

$ starvault policy write test -<<EOF
path "secret/data/test" {
   capabilities = [ "create", "read", "update", "delete" ]
}
EOF

Создайте политику team-qa

$ starvault policy write team-qa -<<EOF
path "secret/data/team-qa" {
   capabilities = [ "create", "read", "update", "delete" ]
}
EOF

Выведите все политики, чтобы убедиться в существовании политик base, test, team-qa
```
$ starvault policy list
base
default
team-qa
test
root
```
Включите метод аутентификации userpass на userpass-test.
```
$ starvault auth enable -path="userpass-test" userpass
```
Создайте нового пользователя bob в userpass-test, где пароль - training, а политика test подключена.
```
$ starvault write auth/userpass-test/users/bob password="training" policies="test"
```
Включите метод аутентификации userpass на другом пути, userpass-qa.
```
$ starvault auth enable -path="userpass-qa" userpass
```
Создайте нового пользователя с именем bsmith в userpass-qa, где пароль - training и политика team-qa подключена.
```
$ starvault write auth/userpass-qa/users/bsmith password="training" policies="team-qa"
```

Выполните следующую команду, чтобы обнаружить указатель монтирования для метода аутентификации userpass.

$ starvault auth list -detailed

Path Plugin Accessor …

Path	Plugin	Accessor	…
----	----	----	…
`token/`	`token`	`auth_token_c5943123`	…
`userpass-qa/`	`userpass`	`auth_userpass_8c7b8e0f`	…
`userpass-test/`	`userpass`	`auth_userpass_264d4705`	…
…

----

…

token/

token

auth_token_c5943123

…

userpass-qa/

userpass

auth_userpass_8c7b8e0f

…

userpass-test/

userpass

auth_userpass_264d4705

…

Каждый метод аутентификации userpass имеет уникальный указатель монтирования Accessor, который используется для его идентификации.

Выполните следующую команду, чтобы сохранить значение указателя userpass-test auth в файле с именем accessor_test.txt.
```
$ starvault auth list -format=json | jq -r '.["userpass-test/"].accessor' > accessor_test.txt
```
Полученный файл содержит значение указателя (auth_userpass_XXXXX).
Аналогичным образом выполните следующую команду, чтобы сохранить значение указателя userpass-qa в файле с именем accessor_qa.txt.
```
$ starvault auth list -format=json | jq -r '.["userpass-qa/"].accessor' > accessor_qa.txt
```
Создайте сущность для bob-smith и сохраните полученный идентификатор сущности в файле с именем entity_id.txt.
```
$ starvault write -format=json identity/entity name="bob-smith" policies="base" \
     metadata=organization="ACME Inc." \
     metadata=team="QA" \
     | jq -r ".data.id" > entity_id.txt
```
Полученный файл содержит идентификатор сущности bob-smith (например, 24204b50-22a6-61f5-bd4b-803f1a4e4726).

Теперь добавьте пользователя bob к сущности bob-smith, создав псевдоним сущности. Установите пользовательские метаданные для псевдонима сущности bob с именем account и задайте для него значение Tester Account.

$ starvault write identity/entity-alias name="bob" \
     canonical_id=$(cat entity_id.txt) \
     mount_accessor=$(cat accessor_test.txt) \
     custom_metadata=account="Tester Account"

**Пример вывода:**
Key	Value
---	-----
`canonical_id`	`24204b50-22a6-61f5-bd4b-803f1a4e4726`
`id`	`ae2cdd0f-9807-7336-2265-5575c71837e7`

Просмотр псевдонимов сущностей (необязательно)

Чтобы просмотреть созданный псевдоним сущности, используйте возвращаемый идентификатор псевдонима сущности.

$ starvault read identity/entity-alias/id/<id>

Пример

$ starvault read identity/entity-alias/id/ae2cdd0f-9807-7336-2265-5575c71837e7

Key Value

Key	Value
---	----
`canonical_id`	`971b5ab3-1931-8381-8605-1b9511572278`
`creation_time`	`2021-11-15T01:41:03.093366Z`
`custom_metadata`	`map[account:Tester Account]`
`id`	`10340e8f-64fa-fe7d-0c88-b6172293f788`
`last_update_time `	`2021-11-15T01:41:03.093366Z`
`local`	`false`
`merged_from_canonical_ids`	`<nil>`
`metadata`	`<nil>`
`mount_accessor`	`auth_userpass_2cbfe431`
`mount_path `	`auth/userpass-test/`
`mount_type`	`userpass`
`name `	`bob`
`namespace_id `	`root`

---

----

canonical_id

971b5ab3-1931-8381-8605-1b9511572278

creation_time

2021-11-15T01:41:03.093366Z

custom_metadata

map[account:Tester Account]

id

10340e8f-64fa-fe7d-0c88-b6172293f788

`last_update_time `

2021-11-15T01:41:03.093366Z

local

false

merged_from_canonical_ids

<nil>

metadata

<nil>

mount_accessor

auth_userpass_2cbfe431

`mount_path `

auth/userpass-test/

mount_type

userpass

`name `

bob

`namespace_id `

root

Повторите предыдущий шаг, чтобы добавить пользователя bsmith в сущность bob-smith. Установите пользовательские метаданные для псевдонима сущности bsmith с именем account и задайте для него значение "QA Eng Account".
```
$ starvault write identity/entity-alias name="bsmith" \
     canonical_id=$(cat entity_id.txt) \
     mount_accessor=$(cat accessor_qa.txt) \
     custom_metadata=account="QA Eng Account"
```
Пример вывода:

Key Value

---

-----

canonical_id

24204b50-22a6-61f5-bd4b-803f1a4e4726

id

6066f6af-bb1c-5310-58a1-fd9c8f151573

Посмотрите сведения о сущности

$ starvault read -format=json identity/entity/id/$(cat entity_id.txt) | jq -r ".data"

Пример вывода: Результат должен включать псевдонимы сущностей, метаданные (организация и команда) и базовую политику.

{
  "aliases": [
    {
      "canonical_id": "73503625-abcd-db22-08c3-c121d682d550",
      "creation_time": "2021-11-17T05:33:48.040506Z",
      "custom_metadata":
      {
        "account": "Tester Account"
      },
      "id": "cf073e2e-41af-852f-848d-f67533c8a610",
      "last_update_time": "2021-11-17T05:33:48.040506Z",
      "local": false,
      "merged_from_canonical_ids": null,
      "metadata": null,
      "mount_accessor": "auth_userpass_0a6936a7",
      "mount_path": "auth/userpass-test/",
      "mount_type": "userpass",
      "name": "bob"
    },
     {
      "canonical_id": "73503625-abcd-db22-08c3-c121d682d550",
      "creation_time": "2021-11-17T05:33:48.107834Z",
      "custom_metadata":
      {
        "account": "QA Eng Account"
      },
      "id": "7add6763-ce53-d92a-c795-c8ae529ce6e7",
      "last_update_time": "2021-11-17T05:33:48.107834Z",
      "local": false,
      "merged_from_canonical_ids": null,
      "metadata": null,
      "mount_accessor": "auth_userpass_ef4f8068",
      "mount_path": "auth/userpass-qa/",
      "mount_type": "userpass",
      "name": "bsmith"
     }
     ],
  "creation_time": "2021-11-17T05:33:47.966585Z",
  "direct_group_ids": [
    "49e8b9e8-8933-1e14-f05c-e1c9674b142b"
  ],
  "disabled": false,
  "group_ids": [
    "49e8b9e8-8933-1e14-f05c-e1c9674b142b"
  ],
  "id": "73503625-abcd-db22-08c3-c121d682d550",
  "inherited_group_ids": [],
  "last_update_time": "2021-11-17T05:33:47.966585Z",
  "merged_entity_ids": null,
  "metadata":
  {
    "organization": "ACME Inc.",
    "team": "QA"
  },
  "mfa_secrets": {},
  "name": "bob-smith",
  "namespace_id": "root",
  "policies":
  [
    "base"
  ]
}

7.3. Вызов API с использованием cURL

Сначала создайте полезную нагрузку запроса API, содержащую базовую политику.
```
$ tee payload-1.json <<EOF
{
  "policy": "path \"secret/data/training_*\" {\n   capabilities = [\"create\", \"read\"]\n}"
}
EOF
```

Создайте политику base.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-1.json \
   $STARVAULT_ADDR/v1/sys/policies/acl/base

Создайте полезную нагрузку API запроса, содержащую политику test.

$ tee payload-2.json <<EOF
{
  "policy": "path \"secret/data/test\" {\n capabilities = [ \"create\", \"read\", \"update\", \"delete\" ]\n }"
}
EOF

Создайте политику test

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-2.json \
   $STARVAULT_ADDR/v1/sys/policies/acl/test

Создайте полезную нагрузку запроса API, содержащую политику team-qa.

$ tee payload-3.json <<EOF
{
  "policy": "path \"secret/data/team-qa\" {\n capabilities = [ \"create\", \"read\", \"update\", \"delete\" ]\n }"
}
EOF

Создайте политику team-qa

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-3.json \
   $STARVAULT_ADDR/v1/sys/policies/acl/team-qa

Выведите все политики, чтобы убедиться в существовании политик base, test и team-qa.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request LIST \
   $STARVAULT_ADDR/v1/sys/policies/acl | jq -r ".data"

Пример вывода:

{
  "keys": [
    "base",
    "default",
    "team-qa",
    "test",
    "root"
  ]
}

Включите метод аутентификации userpass на userpass-test.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data '{"type": "userpass"}' \
   $STARVAULT_ADDR/v1/sys/auth/userpass-test

Создайте нового пользователя bob в userpass-test, где пароль - training, а политика test подключена.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data '{"password": "training", "policies": "test"}' \
   $STARVAULT_ADDR/v1/auth/userpass-test/users/bob

Включите метод аутентификации userpass в userpass-qa.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data '{"type": "userpass"}' \
   $STARVAULT_ADDR/v1/sys/auth/userpass-qa

Создайте нового пользователя с именем bsmith в userpass-qa, где пароль - training, а политика team-qa подключена.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data '{"password": "training", "policies": "team-qa"}' \
   $STARVAULT_ADDR/v1/auth/userpass-qa/users/bsmith

Выполните следующую команду, чтобы обнаружить указатель монтирования для метода аутентификации userpass, включенного в userpass-test, и сохраните его значение в файле accessor_test.txt.
```
$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/sys/auth | jq -r '.data | .["userpass-test/"].accessor' > accessor_test.txt
```
Результирующий файл содержит значение указателя (auth_userpass_XXXXX).
Выполните следующую команду, чтобы обнаружить указатель монтирования для метода аутентификации userpass, включенного в userpass-qa, и сохраните его значение в файле accessor_qa.txt.
```
$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/sys/auth | jq -r '.data | .["userpass-qa/"].accessor' > accessor_qa.txt
```

Создайте полезную нагрузку API для создания сущности bob-smith.

$ tee payload-entity.json <<EOF
{
  "name": "bob-smith",
  "metadata": {
    "organization": "ACME Inc.",
    "team": "QA"
  },
  "policies": ["base"]
}
EOF

Создайте сущность bob-smith
```
$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-entity.json \
   $STARVAULT_ADDR/v1/identity/entity | jq -r ".data.id" > entity_id.txt
```
Полученный файл содержит идентификатор сущности bob-smith (например, 24204b50-22a6-61f5-bd4b-803f1a4e4726).

Добавьте пользователя bob к сущности bob-smith, создав псевдоним сущности. В теле запроса нужно передать имя userpass как name, значение указателя userpass-test как mount_accessor и id сущности как canonical_id. Установите пользовательские метаданные для псевдонима сущности bob с именем "account" и задайте его значение как "Tester Account".

Создайте полезную API нагрузку.

$ tee payload-bob.json <<EOF
{
  "name": "bob",
  "canonical_id": "$(cat entity_id.txt)",
  "mount_accessor": "$(cat accessor_test.txt)",
  "custom_metadata": {
    "account": "Tester Account"
  }
}
EOF

Используйте конечную точку identity/entity-alias, чтобы добавить псевдоним сущности.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-bob.json \
   $STARVAULT_ADDR/v1/identity/entity-alias | jq -r ".data"

Пример вывода:

{
  "canonical_id": "24204b50-22a6-61f5-bd4b-803f1a4e4726",
  "id": "ae2cdd0f-9807-7336-2265-5575c71837e7"
}

Просмотр псевдонимов сущностей (необязательно)

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/identity/entity-alias/id/<id> | jq -r ".data"

Пример

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/identity/entity-alias/id/ae2cdd0f-9807-7336-2265-5575c71837e7 \
   | jq -r ".data"

{
  "canonical_id": "65764de8-4e3a-6ea1-8c96-3df951f05b42",
  "creation_time": "2021-11-15T02:18:18.925287Z",
  "custom_metadata":
  {
    "account": "Tester Account"
  },
  "id": "ad67d5f0-221f-5c4a-b652-eecf107e5beb",
  "last_update_time": "2021-11-15T02:18:18.925287Z",
  "local": false,
  "merged_from_canonical_ids": null,
  "metadata": null,
  "mount_accessor": "auth_userpass_53c9a0c7",
  "mount_path": "auth/userpass-test/",
  "mount_type": "userpass",
  "name": "bob",
  "namespace_id": "root"
}

Повторите предыдущий шаг, чтобы добавить пользователя bsmith в сущность bob-smith. Установите пользовательские метаданные для псевдонима сущности bsmith с именем "account" и задайте для него значение "QA Eng Account".

Создайте полезную нагрузку API-запроса.
```
$ tee payload-bsmith.json <<EOF
{
   "name": "bsmith",
   "canonical_id": "$(cat entity_id.txt)",
   "mount_accessor": "$(cat accessor_qa.txt)",
   "custom_metadata": {
     "account": "QA Eng Account"
   }
}
EOF
```
Используйте конечную точку identity/entity-alias, чтобы добавить псевдоним сущности.
```
$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-bsmith.json \
   $STARVAULT_ADDR/v1/identity/entity-alias | jq -r ".data"
```
Пример вывода:
```
{
  "canonical_id": "24204b50-22a6-61f5-bd4b-803f1a4e4726",
  "id": "6066f6af-bb1c-5310-58a1-fd9c8f151573"
}
```

Просмотрите сведения о сущности

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/identity/entity/id/$(cat entity_id.txt) | jq -r ".data"

Пример вывода: Пользователи bob и bsmith должны появиться в списке псевдонимов сущности и в метаданных, связанных с ней.

{
  "aliases": [
    {
      "canonical_id": "73503625-abcd-db22-08c3-c121d682d550",
      "creation_time": "2021-11-17T05:33:48.040506Z",
      "custom_metadata":
      {
        "account": "Tester Account"
      },
      "id": "cf073e2e-41af-852f-848d-f67533c8a610",
      "last_update_time": "2021-11-17T05:33:48.040506Z",
      "local": false,
      "merged_from_canonical_ids": null,
      "metadata": null,
      "mount_accessor": "auth_userpass_0a6936a7",
      "mount_path": "auth/userpass-test/",
      "mount_type": "userpass",
      "name": "bob"
    },
    {
      "canonical_id": "73503625-abcd-db22-08c3-c121d682d550",
      "creation_time": "2021-11-17T05:33:48.107834Z",
      "custom_metadata":
      {
        "account": "QA Eng Account"
      },
      "id": "7add6763-ce53-d92a-c795-c8ae529ce6e7",
      "last_update_time": "2021-11-17T05:33:48.107834Z",
      "local": false,
      "merged_from_canonical_ids": null,
      "metadata": null,
      "mount_accessor": "auth_userpass_ef4f8068",
      "mount_path": "auth/userpass-qa/",
      "mount_type": "userpass",
      "name": "bsmith"
    }
  ],
  "creation_time": "2021-11-17T05:33:47.966585Z",
  "direct_group_ids": [
    "49e8b9e8-8933-1e14-f05c-e1c9674b142b"
  ],
  "disabled": false,
  "group_ids": [
    "49e8b9e8-8933-1e14-f05c-e1c9674b142b"
  ],
  "id": "73503625-abcd-db22-08c3-c121d682d550",
  "inherited_group_ids": [],
  "last_update_time": "2021-11-17T05:33:47.966585Z",
  "merged_entity_ids": null,
  "metadata":
  {
    "organization": "ACME Inc.",
    "team": "QA"
  },
  "mfa_secrets": {},
  "name": "bob-smith",
  "namespace_id": "root",
  "policies": [
    "base"
  ]
}

7.4. Веб-интерфейс

Откройте веб-браузер и запустите StarVault UI с добавлением http://127.0.0.1:8200/ui в адрес и войдите в систему.
Перейдите на вкладку Политики и выберите Создать ACL политику .
Введите base в поле Название и вставьте следующую политику в текстовое поле Политика.
```
path "secret/data/training_*"
{
   capabilities = ["create", "read"]
}
```
Нажмите Создать для завершения
Снова выберите Создать ACL политику, введите test в поле Название и вставьте следующую политику в текстовое поле Политика.
```
path "secret/data/test"
{
   capabilities = [ "create", "read", "update", "delete" ]
}
```
Нажмите Создать для завершения.
Снова выберите Создать ACL политику, введите team-qa в поле Название и вставьте следующую политику в текстовое поле Политика.
```
path "secret/data/team-qa"
{
   capabilities = [ "create", "read", "update", "delete" ]
}
```
Нажмите Создать для завершения.
Перейдите на вкладку Доступ и выберите Добавить.
Нажмите Username & Password.
Нажмите Далее
Введите userpass-test в поле Путь и нажмите Включить метод.
Снова перейдите на вкладку Доступ, а затем выберите userpass-test/.
В подразделе Пользователи нажмите Создать. Введите bob в поле Имя пользователя и training в поле Пароль
Разверните вкладку Токены.
В разделе Политики сгенерированного токена введите test, чтобы прикрепить политику тестирования
Нажмите Сохранить
Выберите Методы аутентификации и Добавить*.
Выберите Username & Password, затем нажмите Далее
Введите userpass-qa в поле Путь и нажмите Включить метод.
Снова нажмите на вкладку Доступ и выберите userpass-qa/.
В подразделе Пользователи нажмите Создать. Введите bsmith в поле Имя пользователя и training в поле Пароль.
Разверните вкладку Токены.
В разделе Политики сгенерированного токена введите team-qa, чтобы прикрепить политику тестирования
Нажмите Сохранить.
На вкладке Доступ выберите Сущности. Нажмите Создать сущность чтобы создать новую сущность bob-smith. Заполните поля Название, Политики и Метаданные, как показано ниже:
Нажмите Создать. После создания вы окажетесь на странице созданной сущности.
Нажмите + Добавить псевдоним. Введите bob в поле Название и выберите userpass-test/ (userpass) в раскрывающемся списке Бэкенд аутентификации
Нажмите Создать.
Вернитесь в список Сущности. Выберите Добавить псевдоним в меню сущности bob-smith.
Введите bsmith в поле Название и выберите userpass-qa/ (userpass) в раскрывающемся списке Бэкенд аутентификации, затем нажмите Создать
Вернитесь в раздел Сущности > bob-smith и выберите Псевдонимы. В этом списке должны быть bob и bob-smith

Соображения безопасности. Избегайте хранения в метаданных сущности какой-либо конфиденциальной персональной информации (PII). Метаданные сущности реплицируются на другие кластеры, если настроен Performance Replication. Это может стать серьезной проблемой в связи с GDPR. В StarVault есть возможность устанавливать пользовательские метаданные для каждого псевдонима сущности, которые не пересекаются с метаданными, установленными StarVault. Если метод аутентификации является локальным для кластера, метаданные не будут реплицироваться на другие кластеры в той же группе репликации производительности. Поэтому рекомендуется использовать пользовательские метаданные для псевдонима сущности.

8. Тестирование сущности

Чтобы лучше понять, как токен наследует возможности от политики сущности, можно протестировать это, войдя в систему под именем bob.

8.1. CLI команда

Войдите в систему под именем bob и сохраните сгенерированный клиентский токен в файле bob_token.txt.
```
$ starvault login -format=json -method=userpass -path=userpass-test \
    username=bob password=training \
    | jq -r ".auth.client_token" > bob_token.txt
```
Политика test разрешает CRUD-операции на пути secret/test. Убедитесь, можете ли вы записывать секреты в этот путь.
```
$ STARVAULT_TOKEN=$(cat bob_token.txt) starvault kv put secret/test owner="bob"
```
Key Value

---

-----

created_time

2021-11-06T02:12:02.104146Z

custom_metadata

<nil>

deletion_time

n/a

destroyed

false

destroyed

false

version

1
Хотя имя пользователя bob не имеет подключенной base политики, токен наследует возможности, предоставленные базовой политикой, потому что bob является членом сущности bob-smith, а эта сущность имеет подключенную базовую политику. Проверьте, унаследовал ли bob эти возможности.
```
$ STARVAULT_TOKEN=$(cat bob_token.txt) starvault token capabilities secret/data/training_test
create, read
```
Базовая политика предоставляет возможности создания и чтения для пути secret/training_*; поэтому Бобу разрешено выполнять операции создания и чтения для любого пути, начинающегося с secret/training_*.
А как насчет пути secret/team-qa?
```
$ STARVAULT_TOKEN=$(cat bob_token.txt) starvault token capabilities secret/data/team-qa
deny
```
Пользователь bob наследует возможности только от политики ассоциированной с ним сущности. Пользователь может получить доступ к пути secret/team-qa, только если он вошел в систему с учетными данными bsmith. ---

8.2. Вызов API с использованием cURL

Войдите в систему под именем bob и сохраните сгенерированный клиентский токен в файле bob_token.txt.
```
$ curl --request POST \
   --data '{"password": "training"}' \
   $STARVAULT_ADDR/v1/auth/userpass-test/login/bob \
   | jq -r ".auth.client_token" > bob_token.txt
```
Политика test разрешает CRUD-операции на пути secret/test. Убедитесь, можете ли вы записывать секреты в этот путь.

Создайте полезную нагрузку API-запроса.
```
tee payload_test.json <<EOF
{
  "data": {
    "owner": "bob"
  }
}
EOF
```

Проверьте, можно ли записывать секреты по пути

curl --header "X-Vault-Token: $(cat bob_token.txt)" \
   --request POST \
   --data @payload_test.json \
   $STARVAULT_ADDR/v1/secret/data/test | jq -r ".data"

Команда выше должна быть выполнена успешно.

Пример вывода

{
  "created_time": "2021-11-06T02:31:57.43338Z",
  "custom_metadata": null,
  "deletion_time": "",
  "destroyed": false,
  "version": 1
}

Хотя имя пользователя bob не имеет подключенной политики base, токен наследует возможности, предоставленные базовой политикой, потому что bob является членом сущности bob-smith, а эта сущность имеет подключенную базовую политику. Проверьте, унаследовал ли bob эти возможности.
```
$ curl --header "X-Vault-Token: $(cat bob_token.txt)" \
   --request POST \
   --data '{"paths": ["secret/data/training_test"]}' \
   $STARVAULT_ADDR/v1/sys/capabilities-self | jq -r ".data"
```
Пример вывода:
```
{
  "capabilities": [
    "create",
    "read"
  ],
  "secret/data/training_test": [
    "create",
    "read"
  ]
}
```
Политика base предоставляет возможности создания и чтения для пути secret/training_*; поэтому bob разрешено выполнять операции создания и чтения для любого пути, начинающегося с secret/training_*.
А как насчет пути secret/team-qa?
```
$ curl --header "X-Vault-Token: $(cat bob_token.txt)" \
   --request POST \
   --data '{"paths": ["secret/data/team-qa"]}' \
   $STARVAULT_ADDR/v1/sys/capabilities-self | jq -r ".data"
```
Пример вывода:
```
{
  "capabilities": [
    "deny"
  ],
  "secret/data/team-qa": [
    "deny"
  ]
}
```
Пользователь bob наследует возможности только от политики ассоциированной с ним сущности. Пользователь может получить доступ к пути secret/team-qa, только если он вошел в систему с учетными данными bsmith.

9. Создание внутренней группы

Для создания внутренней группы сбросьте переменную окружения STARVAULT_TOKEN

Войдите в систему с токеном, который вы использовали при настройке сущности, прежде чем приступить к созданию внутренней группы. (См. раздел Настройка среды).

Пусть необходимо создать внутреннюю группу под названием engineers. Ее членом будет сущность bob-smith, которая была создана в разделе Создание сущности с псевдонимом.

Групповая политика team-eng включает следующее в файле team-eng.hcl..

team-eng.hcl

path "secret/data/team/eng" {
  capabilities = [ "create", "read", "update", "delete"]
}

9.1. CLI команда

Создайте новую политику team-eng

$ starvault policy write team-eng -<<EOF
path "secret/data/team/eng" {
  capabilities = [ "create", "read", "update", "delete"]
}
EOF

Создайте внутреннюю группу engineers и добавьте сущность bob-smith в качестве члена группы и прикрепите team-eng.
```
$ starvault write identity/group name="engineers" \
     policies="team-eng" \
     member_entity_ids=$(cat entity_id.txt) \
     metadata=team="Engineering" \
     metadata=region="North America"
```
Пример вывода:

Key Value

---

-----

id

0cd76d41-fe36-8c7b-4758-d36bbc212650

name

engineers

Теперь, когда вы входите в систему под именем bob или bsmith, сгенерированный токен наследует политику группового уровня team-eng. Чтобы убедиться в этом, можно выполнить аналогичные тесты, показанные в разделе Тестирование сущности. ---

9.2. Вызов API с использованием cURL

Создайте полезную нагрузку запроса API, содержащую политику team-eng.

$ tee payload.json <<EOF
{
   "policy": "path \"secret/data/team/eng\" {\n  capabilities = [ \"create\", \"read\", \"update\", \"delete\"]\n}\n
}
EOF

Создайте новую политику team-eng

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-1.json \
   $STARVAULT_ADDR/v1/sys/policies/acl/team-eng

Создайте полезную нагрузку API-запроса для создания внутренней группы с именем engineers.

$ tee payload-group.json <<EOF
{
  "name": "engineers",
  "policies": ["team-eng"],
  "member_entity_ids": ["$(cat entity_id.txt)"],
  "metadata": {
    "team": "Engineering",
    "region": "North America"
  }
}
EOF

Используйте конечную точку /identity/group, чтобы создать внутреннюю группу с именем engineers и добавить в нее сущность bob-smith в качестве члена группы, а также присоединить team-eng.
```
$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-group.json \
   $STARVAULT_ADDR/v1/identity/group | jq -r ".data"
```
Пример вывода:
```
{
  "id": "3439804b-c82e-1977-a306-c9dc2e97f039",
  "name": "engineers"
}
```
Теперь, когда вы входите в систему под именем bob или bsmith, сгенерированный токен наследует политику группового уровня team-eng. Чтобы убедиться в этом, можно выполнить аналогичные тесты, показанные в разделе Тестирование сущности. ---

9.3. Веб-интерфейс

Перейдите на вкладку Политики, а затем выберите Создать ACL политику.
Введите team-eng в поле Название и вставьте следующую политику в текстовое поле Политика.
```
path "secret/data/team/eng" {
  capabilities = [ "create", "read", "update", "delete"]
}
```
Нажмите Создать для завершения.
Нажмите на вкладку Доступ и перейдите к подразделу Группы. Нажмите Создать группу
Добавьте информацию по группе, как показано ниже.
Нажмите Создать.

9.4. Резюме

По умолчанию StarVault создает внутреннюю группу. При создании внутренней группы вы указываете членов группы, а не псевдоним группы. Псевдоним группы является связующим звеном между StarVault и внешними поставщиками идентификационных данных (например, LDAP и т. д.). Поэтому вы определяете псевдонимы групп только при создании внешних групп. Для внутренних групп вы указываете member_entity_ids и/или member_group_ids.

10. Создание внешней группы

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

Чтобы управлять авторизацией на уровне группы, можно создать внешнюю группу для связи StarVault с внешним поставщиком идентификационных данных (auth-провайдером) и прикрепить к группе соответствующие политики.

Пример сценария

Любой пользователь, принадлежащий к команде training в организации userpass, example-inc, имеет право выполнять все операции над путем secret/education.

10.1. CLI команда

Создайте новую политику education.

$ starvault policy write education -<<EOF
path "secret/data/education" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}
EOF

Включите метод аутентификации LDAP.
```
$ starvault auth enable ldap
```
Получите указатель монтирования для метода аутентификации LDAP и сохраните его в файле с именем accessor_ldap.txt.
```
$ starvault auth list -format=json | jq -r '.["ldap/"].accessor' > accessor_ldap.txt
```

Настройте конфигурацию метода аутентификации LDAP согласно документации LDAP.

$ starvault write auth/ldap/config \
    url="ldap://ldap.example.com" \
    userdn="ou=User,dc=example,dc=com" \
    groupdn="ou=Groups,dc=example,dc=com" \
    userattr="cn" \
    groupattr="cn" \
    binddn="cn=user1,dc=example,dc=com" \
    bindpass="User1_password"

Создайте внешнюю группу и сохраните сгенерированный идентификатор группы в файле group_id.txt.

$ starvault write -format=json identity/group name="education" \
      policies="education" \
      type="external" \
      metadata=organization="Product Education" | jq -r ".data.id" > group_id.txt

Создайте псевдоним группы, где canonical_id - это идентификатор группы, параметр name должен соответствовать реальной группе в LDAP, существующей в указанном выше groupdn.
```
$ starvault write identity/group-alias name="training" \
      mount_accessor=$(cat accessor_ldap.txt) \
      canonical_id=$(cat group_id.txt)
```
Пример вывода:

Key Value

---

-----

canonical_id

66818a45-ef85-0ff3-6c1e-37faf12ea55e

id

578944f0-dcfd-29fd-a763-d3f9431512d7

Войдите в систему как пользователь LDAP. Введите имя пользователя и пароль LDAP при запросе.

$ starvault login -method=ldap username="user1"

**Пример вывода:**
Key	Value
---	-----
`token`	`s.oECAOloRPLX7s05Ed3cN5hR7`
`token_accessor`	`DcPoprMms2QtDOEVYJIZAfzE`
`token_duration`	`768h`
`token_renewable`	`true`
`token_policies`	`["default"]`
`identity_policies`	`["education"]`
`policies`	`["default" "education"]`
`token_meta_username`	`user1`

10.2. Вызов API с помощью cURL

Создайте полезную нагрузку запроса API, содержащую политику education.

$ tee payload-pol.json <<EOF
{
  "policy": "path \"secret/data/education\" {\n   capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\"]\n}"
}
EOF

Создайте политику education.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request PUT \
   --data @payload-pol.json \
   $STARVAULT_ADDR/v1/sys/policies/acl/education

Включите метод LDAP Auth в StarVault.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data '{"type": " ldap"}' \
   $STARVAULT_ADDR/v1/sys/auth/ldap

Создайте полезную нагрузку запроса API, для настройки конфигурации метода аутентификации LDAP согласно документации LDAP. Документация API для плагина метода аутентификации LDAP StarVault представлена в данном разделе LDAP.
```
$ tee payload-ldap-config.json <<EOF
{
  "url": "ldap://ldap.example.com",
  "userdn": "ou=User,dc=example,dc=com",
  "groupdn": "ou=Groups,dc=example,dc=com",
  "userattr": "uid",
  "groupattr": "cn",
  "binddn": "cn=user1,dc=example,dc=com",
  "bindpass": "User1_password"
}
EOF
```

Примените настройки конфигурации.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-ldap-config.json \
   $STARVAULT_ADDR/v1/auth/ldap/config

Получите значение указателя LDAP и сохраните его в файле с именем accessor_ldap.txt.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   $STARVAULT_ADDR/v1/sys/auth | jq -r '.data | ."ldap/".accessor' > accessor_ldap.txt

Создайте полезную нагрузку запроса API для создания внешней группы.

$ tee payload-edu.json <<EOF
{
  "name": "education",
  "policies": ["education"],
  "type": "external",
  "metadata": {
    "organization": "Product Education"
  }
}
EOF

Создайте внешнюю группу и сохраните сгенерированный идентификатор группы в файле group_id.txt.

curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-edu.json \
   $STARVAULT_ADDR/v1/identity/group | jq -r ".data.id" > group_id.txt

Создайте полезную нагрузку API-запроса для создания псевдонима группы для команды, параметр name должен соответствовать реальной группе в LDAP, существующей в указанном выше groupdn.
```
$ tee payload-training.json <<EOF
{
  "canonical_id": "$(cat group_id.txt)",
  "mount_accessor": "$(cat accessor_ldap.txt)",
  "name": "training"
}
EOF
```

Создайте псевдоним группы.

$ curl --header "X-Vault-Token: $STARVAULT_TOKEN" \
   --request POST \
   --data @payload-training.json \
   $STARVAULT_ADDR/v1/identity/group-alias | jq -r ".data"

Пример вывода:

{
"canonical_id": "81297d74-d67e-afe6-8a57-d76769430796",
"id": "2891f4e7-554a-2fd7-82a4-3fe890266f75"
}

Авторизуйтесь в систему как пользователь LDAP, входящий в группу.

curl --request POST \
   --data '{"password": "User1_Password"}' \
   $STARVAULT_ADDR/v1/auth/ldap/login/user1

Пример вывода:

{
  "request_id": "545fded5-418f-7ad2-eecc-d45cd8d4a45d",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {},
  "wrap_info": null,
  "warnings": null,
  "auth": {
    "client_token": "s.8uC4xxrQaYOLilEiBX0CIrLw",
    "accessor": "fdRhTOnPu5aSWQtx53uNEWZ1",
    "policies": [
      "default",
      "education"
    ],
    "token_policies": [
      "default"
    ],
    "identity_policies": [
      "education"
    ],
    "metadata": {
      "username": "user1"
    },
    "lease_duration": 2764800,
    "renewable": true,
    "entity_id": "01ba143b-aef1-1ccd-b8d1-7e9fd15c8f4d",
    "token_type": "service",
    "orphan": true,
    "mfa_requirement": null,
    "num_uses": 0
  }
}

10.3. Веб-интерфейс

Нажмите на вкладку Политики и выберите Создать ACL политику.
Введите education в поле Название и вставьте следующую политику в поле Политика.
```
path "secret/data/education" {
  capabilities = ["create","read","update","delete","list"]
}
```
Нажмите Создать политику для завершения.
Зайдите во вкладку Доступ и выберите Методы аутентификации. Нажмите + Добавить.
Из представленных методов выберите LDAP и кликните Далее.
Оставьте путь ldap и нажмите Включить метод.
В открывшемся окне настройте конфигурацию метода аутентификации LDAP согласно документации LDAP.
Зайдите на вкладку Доступ и выберите Группы
Выберите Создать группу. Введите информацию о группе, как показано ниже.
Нажмите Cоздать.
Выберите Добавить псевдоним и введите в поле Название имя существующей группы в LDAP. Выберите ldap/(ldap) в раскрывающемся списке Бэкенд аутентификации.
Нажмите Создать.
Войдите в систему, выбрав метод аутентификации LDAP. Введите имя пользователя и пароль. ---

На данном этапе любой пользователь LDAP, принадлежащий группе training в организации, может пройти аутентификацию в StarVault. Сгенерированный токен для пользователя содержит политику education.

11. Очистка

Если вы хотите очистить свое окружение после завершения обучения, выполните действия, описанные в этом разделе.

Снимите значение переменной окружения STARVAULT_TOKEN.
```
$ unset STARVAULT_TOKEN
```
Снимите значение переменной окружения STARVAULT_ADDR.
```
$ unset STARVAULT_ADDR
```
Вы можете остановить сервер StarVault dev, нажав Ctrl+C, когда сервер запущен. Или выполните следующую команду.
```
$ pgrep -f starvault | xargs kill
```

12. Зачем создавать сущности?

В этом руководстве в качестве примера, демонстрирующего использование сущностей и групп, использовался пользователь Боб Смит. Однако эта концепция применима и к приложениям.

Рассмотрим сценарий, в котором приложение использует несколько методов авторизации для входа в StarVault. Если не определена сущность, привязывающая эти несколько идентификаторов авторизации к приложению, сервер StarVault не сможет узнать, что одно и то же приложение вошло в StarVault с помощью разных методов авторизации. В результате каждый вход будет считаться новым клиентом.

Key	Value
---	-----
`id`	`0cd76d41-fe36-8c7b-4758-d36bbc212650`
`name`	`engineers`

Key	Value
---	-----
`canonical_id`	`66818a45-ef85-0ff3-6c1e-37faf12ea55e`
`id`	`578944f0-dcfd-29fd-a763-d3f9431512d7`