Digibee JWT

Know the component and how to use it.

Erick Rubiales avatar
Written by Erick Rubiales
Updated over a week ago

IMPORTANT: This documentation has been discontinued. Read the updated Digibee JWT documentation on our new documentation portal.

Digibee JWT generates and decodes JWT tokens for internal use in the Digibee Platform. In other words, the token generated by this component serves the communication that occurs between pipelines configured with REST Trigger or HTTP Trigger and its derivatives - once the JWT-type authentications are configured.

Take a look at the configuration parameters of this component:

  • Operation: GENERATE (that generates a JWT token) and DECODE (that decodes a JWT token).

  • Scopes: scopes for the JWT token separated by comma (eg.: SCOPE1,SCOPE2,...,...).

  • Expiration: expiration time (in milliseconds). Here, we suggest a number between 0 and 31536000 (equivalent to 31536000000 milliseconds) (365 days) that restricts the JWT's lifetime to the maximum number of expiration seconds. Any JWT with a longer lifespan will be refused. If this value is supplied, the claims- to-verify property's expiration must also be specified. An indefinite period is represented by the default value of 0. This option should be configured with potential clock skew in mind.

  • Fail On Error: if the option is enabled, the execution of the pipeline with error will be interrupted; otherwise, the pipeline execution proceeds, but the result will show a false value for the “success” property.

Messages flow

GENERATE Operation

The component can receive any object in the input and will repass the complete body for the token generation. If you want to provide the Scopes and/or Expiration dynamically, inform them as illustrated below, along with any additional parameter in the input message:

{
"scopes": "SCOPE1,SCOPE2,...,...",
"expiration": 1602790847,
"randomProperty": "someValue",
...
}

Output

{
"status": "logged"
}

The Authorization property will be placed with the token in the response header generated by the specifications above.

Example

Authorization: Bearer eyW4T.....

DECODE Operation

For this operation, the component doesn't expect any input message structure, but only a JWT token in the request header during the execution.

Input

{
"scopes": "SCOPE1,SCOPE2,...,...",
"expiration": 1602790847,
"randomProperty": "someValue",
...
}

Header

Authorization: Bearer eyW4T.....

Output

{
"body": {
"dataToken": {
"consumer_name": "digibee",
"realm": "digibee",
"parameter1": "parameter_value",
"parameter2": "parameter_value",
...
}
}
}

Error

{
error: "error message",]
code: XXX,
body: {
},
headers: {
},
errorMessage: "This property will be displayed whenever the request return body is not in JSON format. It will contain the conversion error message and the original body of the request return."
}

IMPORTANT: for some errors, body and headers are unavailable.

Digibee JWT in Action

We created an article about this component. If you want to understand its use and application, click here.

Technology

To better understand how the JWT token is generated from this component, check the following example.

For all JWT it's necessary to inform the headers, because they have all the information of the algorithm to be used in the token cryptography. Therefore, the standard headers of the generated token are:

{
"alg": "HS256",
"typ": "JWT"
}

The JWT token is composed by a payload, which includes all the information that travels in the token. It is informed in the component input:

{
"scopes": [],
"consumer_name":"digibee",
"realm": "REALM",
"someRandomProperty": "someRandomValue",
….
}

UUID is randomly generated alongside with the token creation, which must be signed. See how to identify the UUID:

HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
RANDOM_UUID
)

By the end of the execution, the token will be generated inside the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.jY3Sv72B0BlRCrxLauMXHJi5zLY3v2BmknciOEh3q2c

If you want to know more about JWT tokens, click here.

Did this answer your question?