Ресурсные роли

Ресурсные роли предоставляют пользователям разрешения на определенные объекты и действия в системе: операции CRUD с сущностями, атрибутами сущностей, экранами UI и так далее.

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

Создание ресурсных ролей

Создавать ресурсные роли можно во время разработки с помощью аннотированных интерфейсов Java (см. дизайнер роли в Studio) или во время выполнения с помощью экранов UI, доступных в разделе Security → Resource roles.

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

Пример определения роли во время разработки:

@ResourceRole( (1)
    name = "Full Access", (2)
    code = FullAccessRole.CODE) (3)
public interface FullAccessRole {

    String CODE = "system-full-access";
    
    void fullAccess(); (4)

1	Аннотация `@ResourceRole` указывает, что интерфейс определяет ресурсную роль.
2	Удобное для пользователя имя роли.
3	Код роли.
4	Интерфейс может иметь один или несколько методов для определения аннотаций политики (см. ниже). Различные методы используются только для группировки связанных политик. Имена методов могут быть произвольными, они отображаются как Policy group, когда роль показывается в UI.

Ресурсные политики

Ресурсные роли определяют разрешения, задавая ресурсные политики. Политика объединяет ресурс с разрешенным типом доступа к нему.

Политика сущностей

Политика сущностей определяет, какие операции CRUD разрешены для сущности.

В роли, определенной во время разработки, политика сущностей определяется аннотацией @EntityPolicy, например:

@EntityPolicy(
        entityClass = Customer.class,
        actions = {EntityPolicyAction.READ,
                EntityPolicyAction.CREATE,
                EntityPolicyAction.UPDATE})
void customer();

Параметр entityClass указывает сущность. Чтобы определить политику для всех сущностей, используйте параметр entityName со значением *.

Параметр actions указывает разрешенные операции CRUD. Чтобы разрешить все операции, используйте значение EntityPolicyAction.ALL.

Политика атрибутов сущностей

Политика атрибутов сущностей определяет, какие атрибуты сущностей разрешены.

В роли, определенной во время разработки, политика атрибутов сущностей определяется аннотацией @EntityAttributePolicy, например:

@EntityAttributePolicy(
        entityClass = Customer.class,
        attributes = {"name", "region", "details"},
        action = EntityAttributePolicyAction.MODIFY)
void customer();

Параметр attributes указывает имена атрибутов сущности. Чтобы определить политику для всех атрибутов сущности, используйте значение *.

Параметр action указывает разрешенный уровень доступа: VIEW (просмотр) или MODIFY (модификация). Право на модификацию автоматически предоставляет доступ к просмотру.

Политика экранов

Политика экранов определяет разрешенные экраны UI.

В роли, определенной во время разработки, политика экранов определяется аннотацией @ViewPolicy, например:

@ViewPolicy(
        viewIds = {"Customer.list"})
void customer();

Параметр viewIds задает идентификаторы разрешенных экранов UI. Чтобы разрешить все экраны, используйте значение *.

Политика меню определяет разрешенные пункты главного меню.

В роли, определенной во время разработки, политика меню определяется аннотацией @MenuPolicy, например:

@MenuPolicy(
        menuIds = {"Customer.list"})
void customer();

Параметр menuIds задает идентификаторы разрешенных пунктов меню. Чтобы разрешить все пункты меню, используйте значение *.

Специальная политика

Специальная политика определяет разрешения для произвольных именованных функций.

Фреймворк использует специальные разрешения для ограничения доступа к различным механизмам. Например, Generic REST API определяет политику rest.enabled, поэтому пользователь должен иметь это разрешение, чтобы иметь возможность взаимодействовать с приложением через интерфейс Generic REST.

Также можно использовать специальные политики для ограничения доступа к функциям приложения. Ниже приведен пример такого контроля доступа.

В роли, определенной во время разработки, специальная политика определяется аннотацией @SpecificPolicy, например:

@SpecificPolicy(
        resources = {"customer.notify"})
void customer();

Политика проверяется в коде приложения классами AccessManager и SpecificOperationAccessContext, предоставляемыми фреймворком:

@Autowired
private AccessManager accessManager;

public void notifyCustomer(Customer customer) {
    SpecificOperationAccessContext accessContext =
            new SpecificOperationAccessContext("customer.notify");
    accessManager.applyRegisteredConstraints(accessContext);
    if (accessContext.isPermitted()) {
        // do notify
    }
}

Узнать больше о проверке разрешений можно в разделе Ограничения доступа.

Чтобы разрешить все существующие специальные политики, используйте значение * в аннотации @SpecificPolicy.resources.

Детализация ролей

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

Детализированные роли определяют разрешения для тесно связанных ресурсов, таких как сущность, ее экраны UI и пункты меню. Например, "Полный доступ к Клиентам", "Может создавать и обновлять Заказы". Обычно пользователю назначается несколько таких ролей.
Крупномасштабные роли определяют все разрешения, необходимые для конкретной задачи, например "Продавец". Такая роль может сама определять все разрешения или наследовать их от дочерних ролей, поэтому крупномасштабная роль может быть создана как совокупность детализированных ролей.

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

Пример

Ниже приведен полный пример ресурсной роли, определенной во время разработки, которая обеспечивает ограниченный доступ к следующим сущностям и их экранам UI:

@ResourceRole(
        name = "Customers: non-confidential info only, cannot delete",
        code = "customer-nonconfidential-access")
public interface CustomerNonConfidentialAccessRole {

    @EntityPolicy(
            entityClass = Customer.class,
            actions = {EntityPolicyAction.READ,
                    EntityPolicyAction.CREATE,
                    EntityPolicyAction.UPDATE})
    @EntityAttributePolicy(
            entityClass = Customer.class,
            attributes = {"name", "region", "details"},
            action = EntityAttributePolicyAction.MODIFY)
    @ViewPolicy(
            viewIds = {"Customer.list"})
    @MenuPolicy(
            menuIds = {"Customer.list"})
    void customer();

    @EntityPolicy(
            entityClass = CustomerDetail.class,
            actions = EntityPolicyAction.ALL)
    @EntityAttributePolicy(
            entityClass = CustomerDetail.class,
            attributes = {"content"},
            action = EntityAttributePolicyAction.MODIFY)
    @ViewPolicy(
            viewIds = {"CustomerDetail.detail"})
    void customerDetail();
}