Application Tokens

2.5

Premium

Application tokens provide an alternative way of accessing MMC that can be used by the other applications and services ( non-human MMC users). The entity that receives an application token can include it in its requests to the REST API of the MMC and obtain the same access rights as an authenticated user. The access rights are limited by the role attribute of the token.

info

The Application Tokens Feature can be accessed only by the users with an admin role.

info

Application Tokens are especially useful with the Single Sign-On, since the SSO plugin replaces the standard authentication you won't have a way to access the MMC REST APIs using external services and applications. That's precisely the right use case for Application Tokens Feature.

Enable Application Tokens Plugin

To enable the Application Tokens Feature, ensure you are using the Pro Edition of Mosquitto and that you have the feature enabled in your license. Also ensure that your config file (specified with CEDALO_MC_PROXY_CONFIG environmental variable or by default saved in management-center/config/config.json) contains the following entry inside the plugins array:

    {
  "name": "application-tokens"
}

On start-up, the Management Center will print a message that the application-tokens plugin is enabled and laoded into the console:

Loaded plugin: "application_tokens" (Cedalo Application tokens)

What is an application token

An application token is a string of characters that encodes authorization information, which is comprised of the following attributes:

• exp - date and time when the token expires (Unix timestamp)
• role - role (admin, editor, viewer, connectionManager, monitoringViewer) that the token grants to the one using it

Application tokens also hold (encode) additional attributes:

• iat - issued at, the date when the application token was issued (unix timestamp)
• iss - user who requested the application token

{
  "role": "viewer",
  "iat": 1669294549,
  "exp": 1669382280,
  "iss": "cedalo"
}

This string of data is saved as a JWT token which is signed with a secret. The token can only be signed by the party holding the secret (Management Center). In case somebody else tries to change the token information, they will not be able to generate a valid signature. A signature is always verified by the Management Center for every token. Without a valid one the token will be unusable.

Application tokens are never stored on the MMC's backend because they are essentially plain text passwords. It would be a problem if an attacker gained access to the complete database of all tokens. Therefore, Management Center does not store them and requires user to copy the token upon creation and store them in a safe place. Please create tokens with minimum needed permissions for every application that needs the access.

How to use application token

When you have your application token generated (read below if you want to learn how application tokens can be created), you just have to pass it with every request you make to the MMC REST API.

We recommend including the application token inside of the Authorization header with a value of "Bearer <insert your token here>". So, for example:

Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE2Njk2NTkxOTYsImV4cCI6MTY3MjM0MDUyMCwiaXNzIjoiY2VkYWxvIn0.swBlZ-3fpNCgIaG5ymfuFJ-Du7g59KHewOIHCMRx1cM"

Another option is to include your application token as a token url query parameter inside of your request url: ?token=<insert your token here>. For example:

https://yourmmcurl.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE2Njk2NTkxOTYsImV4cCI6MTY3MjM0MDUyMCwiaXNzIjoiY2VkYWxvIn0.swBlZ-3fpNCgIaG5ymfuFJ-Du7g59KHewOIHCMRx1cM

Types of responses

When using application tokens, you may receive either a successful response or an error.

A successful response means that your token was accepted and the data you asked for when issuing request was returned back to you. In this case the HTTP status code would be 200, and the response type is application/json. In case your token was successfully accpeted but your query was malformed or some other error when processing your request occurred, you would get a status code in the range of 400-500 inclusive. You can guess what when wrong just by looking at the status code (refer to the HTTP status codes) or reading the body of the response which in case of error will be of type text/* and will simply contain a string explaining the error.

In case the application token was not accepted by the MMC, you will get a 403 status code with a text response body of either Forbidden for endpoints for which your token does not have enough permissions or Token not found or was revoked for cases when your token is invalid or has expired.