# identity-role-access-matrix

Этот документ описывает новый формат хранения данных о well-known сущностях IAM'а.

Пермишены и сервисные роли хранятся в отдельном каталоге для сервиса, который ими управляет. 
Например, пермишен `compute.instances.start` может быть задан в файле `compute/permissions.yaml`, а роль `resource-manager.clouds.member` — в файле `resource-manager/roles.yaml`.
Внутри своего каталога команда сервиса может организовать данные как угодно, одним файлом или несколькими, положить их в одном каталоге или раскидать по поддиректориям. 
Обязательное требование — файлы внутри подкаталогов должны называться `permissions.yaml`, `roles.yaml`, `stages.yaml`, `resources.yaml` для описания набора прав, ролей, стейджей и типов ресурсов соответсвенно. 
В каждом файле можно сослаться на сущность из любого другого файла — точно так же, как если бы сущности были описаны рядом, явно ссылаться на файл не нужно.

Если эта документация противоречит тому, что на самом деле творится в файлах — значит, в файлах неправильно :)

## Тулинг

Для проверки того, что yaml'ы написаны верно, можно воспользоваться `yc-iam-compile-role-fixtures` из Python-пакета [yc_iam_tools](https://bb.yandex-team.ru/projects/CLOUD/repos/identity/browse/iam_tools/yc_iam_tools/). А можно и не пользоваться, такая же проверка запускается в TeamCity на каждый PR.

## Роли

```yaml
roles:
   # В этом dict'е перечисляются роли: ключ — название роли, значение — dict со свойствами
   
   example.editor:  # название роли
   
     # Описание роли на английском для документации.
     summary: |>
       Edit different things that are managed by ExampleService.
       Users with this role are also allowed to whisper to horses.
     
     # Видимость роли: может быть public или internal. Роли public видят пользователи, а internal роли — нет.
     # Public роль не должна включать в себя internal-пермишены, сейчас это warning при компиляции,
     # в будущем повысим до error.
     visibility: public
     
     # Минимальный тип ресурса, на который можно назначить роль.
     resourceType: resource-manager.folder
     # Эту роль можно назначить на фолдер или на клауд, но нельзя на SA или на биллинг-аккаунт.
     # Такая роль может содержать пермишены, у которых resourceType фолдер или какой-нибудь вложенный в него ресурс,
     # но не может содержать никакие другие пермишены.
     
     # Другие роли, входящие в состав этой.
     # Параметр можно не указывать, если не нужно инклюдить никакие другие роли.
     includedRoles:
       - example.viewer
       - horse.whisperer
     # Роль `example.editor` содержит все пермишены из `example.viewer` и `horse.whisperer`.
     # `includedRoles` работает транзитивно: если в определении `example.viewer` тоже инклюдятся какие-то роли,
     # то их пермишены входят и в `example.editor`.
       
     # Пермишены, входящие в роль.
     # Параметр можно не указывать, если роль не включает никаких пермишенов напрямую.
     permissions:
       - example.things.edit
       - example.things.manage
       # Есть сокращённая форма записи:
       - example.thingCollections.{create,update,delete}
       # Фигурные скобки можно использовать в любом месте записи:
       # `sample.{horses,mice,chickens}.{feed,pet}` тоже можно сказать,
       # эта запись разресолвится в 6 пермишенов.
       # (Но лучше таким не злоупотреблять.)
     
     # В итоге получается, что в роль `example.editor` входят пермишены:
     # `example.things.edit`, `example.things.manage`,
     # `example.thingCollections.create`, `example.thingCollections.update`, `example.thingCollections.delete`,
     # а также все пермишены, которые входят в роли `example.viewer` и `horse.whisperer`.
     
   # Ещё одна роль.
   example.viewer:
     # Эта роль используется в роли `example.editor` выше.
     # Но это не значит, что `example.viewer` в файле должна идти после `example.editor` —
     # можно расположить их хоть как или вообще положить в разные файлы.
     ...
```

Роли задаются аддитивно: можно создать роль "`viewer` плюс `compute.editor` плюс `iam.serviceAccounts.create`", но нельзя задать "`viewer` минус `billing.viewer`" или "все пермишены `serverless.*.*`, кроме `serverless.*.delete`". Это сделано специально, чтобы при добавлении новой роли/пермишена вся система вела себя более предсказуемо.

Некоторые роли помечены как "псевдороли", у них есть поле `pseudorole: true`. Это временные сущности, они нужны только для того, чтобы из них составить общеоблачные роли типа `viewer`. Ни внешние, ни внутренние пользователи не могут видеть псевдороли в API и назначать на ресурсы. Сервисам рекомендуется заменить их на правильные сервисные роли.

## Пермишены

```yaml
permissions:

  iam.accessBinding.delete:  # имя пермишена
  
    # Описание роли на английском для документации.
    description: Delete access binding.
    
    # Стейдж. Чаще всего это GA.
    # Список стейджей лежит в `stages.yaml`.
    stage: GA
    
    # Видимость пермишена: может быть public или internal.
    # Связана с видимостью ролей: internal пермишены не должны входить в public роли.
    visibility: public
    
    # Здесь задаются условия, когда пермишен может действовать.
    allowedWhen:
      
      # Сейчас можно задать только условие на статус клауда.
      cloud:
        status:
        - BLOCKED_BY_BILLING
        - ACTIVE
      # Этим пермишеном можно воспользоваться только тогда, когда клауд
      # находится в статусе ACTIVE или BLOCKED_BY_BILLING.
      # А если клауд в другом статусе — например, BLOCKED — пермишен запрещён.
```