Getting Started with REST

This section contains an example of retrieving the information about application users through the Generic REST API.

First, add the Generic REST add-on to your project according to the installation section.

Obtaining Access Token

To access the protected resource the client must present a valid access token. The OAuth 2.1 specification provides several ways to get an access token from the authorization server. They are called grant types. In this example, we will use the Client Credentials grant which is suitable for confidential clients, such as backend integrations.

The functionality responsible for issuing tokens and supporting OAuth 2.1 protocol features is located inside the Authorization Server add-on. You must add this add-on to your application. See the Authorization Server add-on documentation for instructions on how to do this.

implementation 'io.jmix.authserver:jmix-authserver-starter'

The idea is that in Jmix application we must register the client (e.g. an external application that needs to access Jmix REST API), define client id and secret, and then using these credentials we will be able to get the access token by a special HTTP request.

The simplest way to register a client is to add standard Spring Authorization Server application properties:

# 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

The next set of application properties is Jmix-specific and defines which resource and row-level roles must be assigned to the access token issued to the client. In this example we will assign two resource roles:

  • rest-minimal (REST: minimal access) - to enable REST API endpoints access.

  • user-management (User management) - to allow operations with the User entity using 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

The user-management role looks as follows:

@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 The API scope indicates the role will be applied for REST API requests

After these properties are defined in the application it should be possible to obtain access tokens. In this example, we will use the curl command-line tool to interact with the REST API.

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"
On Windows, remove \ symbols and write the command in a single line.

As a result, you should get something like this:

HTTP/1.1 200
{
  "access_token":"hKhgNyGMTqaKd6prH-GoHF8zFVTSr9tKKyE3OnMoafRO4FT4Xq_cewHr28cIRITaRmF0olRXpVTyFdxcOPTAl8Vc7xopHrdNuXNXwEeBn7NSiEMvQXW5zO0dwMn_H8FQ",
  "token_type":"Bearer",
  "expires_in":299
}

The access_token attribute is the token you can use for further requests as part of the Authorization Header. It acts as a temporary credential that grants you access to the application.

Configuring REST Endpoints Security

By default, when you add the REST API add-on to the application, no security settings are applied to the REST endpoints. There are multiple ways to protect these endpoints. One way is to configure authenticated URLs for resource server by adding the following application property:

jmix.resource-server.authenticated-url-patterns = /rest/**
If the security of the REST endpoints is not configured in one way or another, then accessing them will either redirect to the UI login page or result in a server error due to executing code without the user’s security context.

Retrieving Entity List

With the access token you can use the generic REST API endpoints to load a list of users (replace <access_token> with the value obtained on the previous step). In this example, we will fetch all the users that are present in the application through the Entities API:

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

The response will contain all users that are available in the application:

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