Skip to content

REST Service

Kura provides a built-in REST Service based on the osgi-jax-rs-connector project.

By default, REST service providers register their services using the context path /services. The REST service provides the BASIC Authentication support and HTTPS client certificate authentication support.

Starting from Kura 5.4.0, REST service provides built in session management support, the Session REST APIs can be used to establish a session. Using sessions is the recommended way for interacting with Kura REST APIs from a browser based application. To support this new mode, starting from Eclipse Kura 5.5.0 session-less BASIC and certificate based authentication are disabled by default (see the Basic Authentication Enabled and Enable Certificate Authentication Whitout Session Management configuration parameters below).

REST API access is available on all HTTP ports defined in the HTTP/HTTPS Configuration section. By default this parameter is set to allow access from ports 443 and 4443 (standard HTTPS and certificate-based authentication ports).

Certificate authentication support is only available on the HTTPS With Certificate Authentication Ports configured in HTTP/HTTPS Configuration section.

Clients can also authenticate with short-lived JWT bearer tokens, obtained through the JWT Token V1 REST APIs (disabled by default, see JWT Authentication Enabled below).

Kura Identity names and passwords can be used for BASIC Authentication. Certificate authentication follows the same rules as Gateway Administration Console Authentication.

Warning

If the forced password change feature for a given identity is enabled, REST API password authentication will be blocked for that identity until the password is updated by the user or the feature is manually disabled. Certificate authentication will continue to be allowed even if the forced password change feature is enabled.

JAX-RS roles are mapped to Kura permissions, the name of a permission associated with a JAX-RS role is the rest. prefix followed by the role name. For example the assets role is mapped to the rest.assets permission. REST related permissions can be assigned to an identity using the Gateway Administration Console in the Identities section.

Rest Service configuration

The available configuration parameters are the following:

  • Allowed Ports: If set to a non empty list, REST API access will be allowed only on the specified ports. If set to an empty list, access will be allowed on all ports. Please make sure that the allowed ports are open in HttpService and Firewall configuration. (Default: empty)

  • Password Authentication Enabled: Enables or disables the built-in password authentication support. (Default: true)

  • Certificate Authentication Enabled: Enables or disables the built-in certificate authentication support. (Default: true)

  • Session Based Authentication Enabled: If set to true, enables authentication using the dedicated /services/session/v1 endpoints and cookie based session management. (Default: true)

  • Session Inactivity Interval (Seconds): The session inactivity interval, sessions will expire if no request is performed for the amount of time specified by this parameter in seconds. This parameter is ignored if Session Based Authentication Enabled is set to false. (Default: 900)

  • Basic Authentication Enabled: Allows to perform authentication by providing identity name and password as BASIC credentials in the request to any resource endpoint. Requires that the Password Authentication Enabled parameter is set to true. (Default: false)

  • Enable Certificate Authentication Without Session Management: If set to true, calling /services/session/v1/certificate to create a session will not be necessary in order to perform certificate based authentication. Presenting a valid HTTPS client certificate and accessing resource endpoint directly is enough for authentication to succeed. Requires that the Certificate Authentication Enabled parameter is set to true. (Default: false)

  • JWT Authentication Enabled: Enables JWT bearer authentication and the /services/token/jwt/v1 endpoints that issue and refresh tokens. Requires a configured JWT Issuing Service and JWT Verification Service. See JWT Token V1 REST APIs. (Default: false)

  • Token Issuing Service Target: OSGi filter selecting the TokenIssuingService that signs access and refresh tokens. Without a match, tokens cannot be issued or refreshed. (Default: (objectClass=org.eclipse.kura.security.token.TokenIssuingService))

  • Token Verification Service Target: OSGi filter selecting the TokenVerificationService that verifies access and refresh tokens, including those issued by other trusted services. Without a match, JWT authentication and refresh are unavailable. (Default: (objectClass=org.eclipse.kura.security.token.TokenVerificationService))

  • JWT Access Token Duration (Seconds): Lifetime of access tokens. They cannot be revoked, so short values limit the use of a leaked token. Capped by the Maximum Token Lifetime of the issuing service. (Default: 60)

  • JWT Refresh Token Duration (Seconds): Lifetime of refresh tokens. Each one can be exchanged only once, so this is the inactivity timeout of a client. Should be greater than the access token duration. Capped by the Maximum Token Lifetime of the issuing service. (Default: 900)

  • JWT Used Refresh Token Retention (Seconds): How long a used refresh token is still tracked after it expires, so that it cannot be exchanged again. Must be greater than or equal to the Clock Skew Tolerance of the verification service. Used tokens are tracked in memory: after a restart they are accepted again until they expire. (Default: 300)

Custom authentication methods

Starting from Kura 5.2.0 it is also possible to develop custom REST authentication method providers by registering an implementation of the org.eclipse.kura.rest.auth.AuthenticationProvider interface as an OSGi service. The org.eclipse.kura.example.rest.authentication.provider bundle in Kura repository provides an example on how to implement a custom authentication method.

Assets REST APIs

Kura exposes REST APIs for the Asset instances instantiated in the framework. Assets REST APIs are available in the context path /services/assets. Following, the supported REST endpoints.

Method Path Allowed roles Encoding Request parameters Description
GET / assets JSON None Returns the list of available assets
GET /{pid} assets JSON None Returns the list of available channels for the selected asset (specified by the corresponding PID)
GET /{pid}/_read assets JSON None Returns the read for all the READ channels in the selected Asset
POST /{pid}/_read assets JSON The list of channels where the READ operation should be performed. Returns the result of the read operation for the specified channels
POST /{pid}/_write assets JSON The list of channels and associated values that will be used for the WRITE operation. Performs the write operation for the specified channels returning the result of the operation.