ydb/cloud/bitbucket/private-api/README.roles.md

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. А можно и не пользоваться, такая же проверка запускается в TeamCity на каждый PR.

Роли

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 и назначать на ресурсы. Сервисам рекомендуется заменить их на правильные сервисные роли.

Пермишены

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 — пермишен запрещён.