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

StarVault поддерживает несколько методов аутентификации и позволяет включать один и тот же метод аутентификации на разных путях монтирования. Каждый клиент 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 auth в двух разных путях: 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. Установите пользовательские метаданные для псевдонима сущности bob с именем "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. Установите пользовательские метаданные для псевдонима сущности bob с именем "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

1. Создайте полезную нагрузку запроса API, содержащую строчную политику education. Создайте полезную нагрузку запроса 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

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

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

4. Создайте полезную нагрузку запроса 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_github.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`