Начало работы с REST

В этом разделе представлен пример получения через REST API информации о пользователях приложения.

Для начала добавьте REST в свой проект как описано в разделе Установка.

Получение токена доступа

Для доступа к защищенному ресурсу клиент должен предоставить действующий токен доступа. Спецификация OAuth 2.1 предоставляет несколько способов получения токена от сервера авторизации. Они называются типами разрешения (grant types). В этом примере мы будем использовать тип разрешения Client Credentials, который подходит для конфиденциальных клиентов, таких как бэкенд-интеграции.

Идея заключается в том, что в приложении Jmix мы должны зарегистрировать клиента (например, внешнее приложение, которому необходим доступ к Jmix REST API), определить идентификатор и секрет клиента, а затем, используя эти учетные данные, мы сможем получить токен доступа с помощью специального HTTP-запроса.

Функциональность, ответственная за выдачу токенов и поддержку всех функций протоколов OAuth 2.1 и OpenID Connect 1.0, предоставляется дополнением Authorization Server, которое должно уже быть включено во время установки дополнения REST API (io.jmix.authserver:jmix-authserver-starter). Дополнение Authorization Server построено на основе Spring Authorization Server.

Простейший способ зарегистрировать клиента - добавить стандартные свойства Spring Authorization Server:

# The client id is my-client
spring.security.oauth2.authorizationserver.client.myclient.registration.client-id=my-client
# The client secret (password) is my-secret
spring.security.oauth2.authorizationserver.client.myclient.registration.client-secret={noop}my-secret
# Enable Client Credential grant for the my-client
spring.security.oauth2.authorizationserver.client.myclient.registration.authorization-grant-types=client_credentials
# Client credentials must be passed in the Authorization header using the HTTP Basic authentication scheme
spring.security.oauth2.authorizationserver.client.myclient.registration.client-authentication_methods=client_secret_basic
# Use opaque tokens instead of JWT
spring.security.oauth2.authorizationserver.client.myclient.token.access-token-format=reference
# access token time-to-live
spring.security.oauth2.authorizationserver.client.myclient.token.access-token-time-to-live=24h

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

rest-minimal (REST: minimal access) - чтобы разрешить доступ к REST API.
user-management (User management) - чтобы разрешить операции с сущностью User через REST API.

# my-client is the client id we configured previously
jmix.authserver.client.myclient.client-id = my-client
jmix.authserver.client.myclient.resource-roles = user-management, rest-minimal

Роль user-management выглядит следующим образом:

@ResourceRole(name = "User management", code = UserManagementRole.CODE, scope = "API") (1)
public interface UserManagementRole {

    String CODE = "user-management";

    @EntityAttributePolicy(entityClass = User.class, attributes = "*", action = EntityAttributePolicyAction.MODIFY)
    @EntityPolicy(entityClass = User.class, actions = EntityPolicyAction.ALL)
    void user();
}

1	"API" scope указывает, что роль будет применяться для запросов к REST API.

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

В данном примере для взаимодействия с REST API мы будем использовать инструмент командной строки curl.

curl -X POST http://localhost:8080/oauth2/token \
   --basic --user my-client:my-secret \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials"

В Windows удалите символы \ и вводите команду одной строкой.

Вы должны получить ответ подобный этому:

HTTP/1.1 200

{
  "access_token":"hKhgNyGMTqaKd6prH-GoHF8zFVTSr9tKKyE3OnMoafRO4FT4Xq_cewHr28cIRITaRmF0olRXpVTyFdxcOPTAl8Vc7xopHrdNuXNXwEeBn7NSiEMvQXW5zO0dwMn_H8FQ",
  "token_type":"Bearer",
  "expires_in":299
}

Атрибут access_token — это токен, который можно использовать для дальнейших запросов в заголовке Authorization. Он действует как временные учетные данные, которые предоставляют вам доступ к приложению от имени пользователя.

Запрос списка сущностей

С токеном доступа вы можете использовать операции (endpoints) REST API для загрузки списка пользователей. Замените <access_token> значением, полученным на предыдущем шаге. Мы извлечем всех пользователей в приложении через Entities API:

curl -X GET http://localhost:8080/rest/entities/User \
    -H "Authorization: Bearer <access_token>"

Ответ будет содержать всех пользователей, доступных в приложении:

HTTP/1.1 200

[
  {
    "_entityName": "User",
    "_instanceName": "[admin]",
    "id": "60885987-1b61-4247-94c7-dff348347f93",
    "version": 1,
    "active": true,
    "username": "admin"
  }
]