Получение информации о субъектах в системе управления доступом Yandex Cloud

Статья создана

Обновлена 28 сентября 2026 г.

Типы субъектов
Доступные методы
- List
- BatchGet
Атрибуты субъектов
Фильтр субъектов

Yandex Identity and Access Management предоставляет инструмент получения информации о субъектах для одновременного поиска и получения атрибутов различных типов субъектов системы управления доступом Yandex Cloud.

Дополнительную гибкость при поиске и получении атрибутов субъектов дает использование фильтров на основе языка Common Expression Language (CEL).

Функциональность получения информации о субъектах доступна в интерфейсах Yandex Cloud CLI и API.

Типы субъектов

Функциональность получения информации о субъектах позволяет выполнять поиск одновременно по разным типам субъектов в организации:

Тип субъекта	Описание	Минимальная роль, необходимая для получения информации
`USER_ACCOUNT`	Пользователи с аккаунтом на Яндексе, локальные и федеративные пользователи	organization-manager.users.viewer или выше на организацию
`SERVICE_ACCOUNT`	Сервисные аккаунты	iam.auditor или выше на организацию
`GROUP`	Группы пользователей, системные и публичные группы	organization-manager.groups.viewer или выше на организацию
`INVITEE`	Пользователи с аккаунтом на Яндексе, которые были приглашены в организацию, но еще не приняли приглашение	organization-manager.users.viewer или выше на организацию

Доступные методы

В Identity and Access Management доступны два метода для получения информации о субъектах: List и BatchGet.

При вызове обоих методов вы можете передать маску субъектов (field-mask), которая определяет, какие атрибуты субъектов необходимо получить. Если не указать маску субъектов, по умолчанию возвращаются только атрибуты sub и type. Доступные атрибуты зависят от типа субъекта. Подробнее читайте в разделе Атрибуты субъектов.

Также при вызове обоих методов вы можете использовать гибкий CEL-фильтр, чтобы максимально конкретизировать список субъектов, информацию по которым вы хотите получить.

Подробнее об использовании методов получения информации о субъектах читайте в разделе Получение информации о субъектах в системе управления доступом Yandex Cloud.

List

Метод List предоставляет список и информацию о субъектах организации по ее идентификатору. Вызвать метод List можно с помощью REST API, gRPC API или команды CLI yc iam subject-details list.

При вызове метода List обязательно передавайте идентификатор организации, в которой будет выполняться поиск субъектов.

BatchGet

Метод BatchGet предоставляет информацию о заданных субъектах организации по их идентификаторам. Вызвать метод BatchGet можно с помощью REST API, gRPC API или команды CLI yc iam subject-details get.

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

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

Атрибуты субъектов

С помощью методов List и BatchGet вы можете получить значения следующих атрибутов субъектов:

Примечание

Маска субъектов (field-mask), передаваемая в методах List и BatchGet, должна содержать имена полей без указания имени основного контейнера subject. Например: sub, user_account или service_account.service_agent.microservice_id.

Поле	Тип данных	Атрибут
subject — основной контейнер, содержащий все атрибуты субъекта.
`subject.sub`	`string`	Идентификатор субъекта.
`subject.type`	`enum` ¹	Тип субъекта в системе управления доступом: `1` — пользовательский аккаунт, соответствует возвращаемому значению `USER_ACCOUNT`; `2` — сервисный аккаунт, соответствует возвращаемому значению `SERVICE_ACCOUNT`; `3` — группа, соответствует возвращаемому значению `GROUP`; `4` – приглашенный пользователь, соответствует возвращаемому значению `INVITEE`;
`subject.created_at`	timestamp	Дата и время создания субъекта.
`subject.status`	`enum` ¹	Статус субъекта (только для федеративных и локальных пользователей): `1` — активный статус, соответствует возвращаемому значению `ACTIVE`; `2` — неактивный статус, соответствует возвращаемому значению `SUSPENDED`.
`subject.name`	`string`	Имя субъекта.
`subject.last_authenticated_at`	timestamp	Дата и время последней аутентификации.
`subject.external_id`	`string`	Идентификатор субъекта во внешней системе.
subject.groups — набор полей с атрибутами групп, участником которых является пользователь или сервисный аккаунт. ²
`subject.groups.type`	`enum` ¹	Тип группы: `1` — публичная группа, соответствует возвращаемому значению `PUBLIC_ACCESS`; `2` — группа пользователей, соответствует возвращаемому значению `EXPLICIT`; `3` — системная группа, соответствует возвращаемому значению `META`.
`subject.groups.id`	`string`	Идентификатор группы пользователей, системной или публичной группы.
`subject.groups.name`	`string`	Имя группы пользователей, системной или публичной группы.
subject.user_account — набор полей с атрибутами, специфичными для субъектов-пользователей.
`subject.user_account.given_name`	`string`	Имя.
`subject.user_account.family_name`	`string`	Фамилия.
`subject.user_account.preferred_username`	`string`	Логин пользователя.
`subject.user_account.email`	`string`	Адрес электронной почты пользователя.
`subject.user_account.phone_number`	`string`	Номер телефона.
`subject.user_account.expires_at`	timestamp	Дата и время плановой деактивации пользователя (если установлена). Только для федеративных и локальных пользователей.
`subject.user_account.modified_at`	timestamp	Дата и время последнего изменения атрибутов пользователя.
`subject.user_account.last_id_proof_at`	timestamp	Дата и время последней верификации пользователя.
`subject.user_account.suspend_reason`	`string`	Причина деактивации (только для федеративных и локальных пользователей).
subject.user_account.subject_container — набор полей с атрибутами, специфичными для различных типов субъектов-пользователей.
`subject.user_account.subject_container.container_type`	`enum` ¹	В зависимости от типа пользователя: `1` — пользователь SAML-совместимой федерации удостоверений, соответствует возвращаемому значению `SAML`; `3` — пользователь с аккаунтом на Яндексе, соответствует возвращаемому значению `PASSPORT`; `4` — локальный пользователь, соответствует возвращаемому значению `USERPOOL`.
`subject.user_account.subject_container.id`	`string`	В зависимости от типа пользователя: для локальных пользователей — идентификатор пула пользователей; для федеративных пользователей — идентификатор федерации удостоверений; для пользователей с аккаунтом на Яндексе — значение `yandex`.
`subject.user_account.subject_container.name`	`string`	В зависимости от типа пользователя: для локальных пользователей — имя пула пользователей; для федеративных пользователей — имя федерации удостоверений; для пользователей с аккаунтом на Яндексе — значение `yandex`.
subject.user_account.job_info — набор полей с атрибутами, которые содержат информацию о компании и должности пользователя.
`subject.user_account.job_info.company_name`	`string`	Название компании.
`subject.user_account.job_info.department`	`string`	Подразделение.
`subject.user_account.job_info.job_title`	`string`	Должность.
`subject.user_account.job_info.employee_id`	`string`	Табельный номер сотрудника.
subject.invitee — набор полей с атрибутами, специфичными для пользователей с аккаунтом на Яндексе, которые были приглашены в организацию, но еще не приняли приглашение.
`subject.invitee.email`	`string`	Адрес электронной почты пользователя.
`subject.invitee.preferred_username`	`string`	Логин пользователя.
subject.service_account — набор полей с атрибутами, специфичными для сервисных аккаунтов.
subject.service_account.cloud — набор полей с атрибутами, содержащими информацию об облаке, к которому относится сервисный аккаунт.
`subject.service_account.cloud.id`	`string`	Идентификатор облака.
`subject.service_account.cloud.name`	`string`	Имя облака.
subject.service_account.folder — набор полей с атрибутами, содержащими информацию о каталоге, к которому относится сервисный аккаунт.
`subject.service_account.folder.id`	`string`	Идентификатор каталога.
`subject.service_account.folder.name`	`string`	Имя каталога.
subject.service_account.service_agent — набор полей с атрибутами, специфичными для сервисных аккаунтов, которые являются сервисными агентами.
`subject.service_account.service_agent.service_id`	`string`	Идентификатор сервиса, от имени которого действует сервисный агент.
`subject.service_account.service_agent.microservice_id`	`string`	Идентификатор микросервиса, от имени которого действует сервисный агент.
subject.group — набор полей с атрибутами, специфичными для групп пользователей, системных и публичных групп.
`subject.group.type`	`enum` ¹	Тип группы: `1` — публичная группа, соответствует возвращаемому значению `PUBLIC_ACCESS`; `2` — группа пользователей, соответствует возвращаемому значению `EXPLICIT`; `3` — системная группа, соответствует возвращаемому значению `META`.
`subject.group.id`	`string`	Идентификатор группы пользователей, системной или публичной группы.
`subject.group.name`	`string`	Имя группы пользователей, системной или публичной группы.

¹ Значения полей с типом данных enum, передаваемые в фильтре (filter) запроса, должны указываться в числовом формате.
² Чтобы с помощью метода BatchGet получить список групп, участником которых является пользователь с аккаунтом на Яндексе, обязательно передавайте в запросе идентификатор организации.

Фильтр субъектов

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

Фильтр задается в поле filter и основан на языке Common Expression Language (CEL).

Подробнее о доступных функциях CEL читайте в официальной документации.

В дополнение к стандартным функциям CEL в Identity and Access Management реализована функция icontains, позволяющая выполнять регистронезависимую проверку вхождения подстроки в строку. Например:

"ABcdEf".icontains("abc") // true

Подробнее об использовании фильтров при получении информации о субъектах читайте в разделе Получение информации о субъектах в системе управления доступом Yandex Cloud.

Полезные ссылки