JWT Token Generation

How To
1

Implementing Token Generation

In order for the HTTP Bearer authentication scheme to operate successfully, you need issue the JWT Tokens using a secret key and a payload containing authentication details. This would typically take place in an unauthenticated operation which would issue tokens according to parameters passed in with a request.

To issue a JWT Token using Linx, use the CreateJWT FNC which is part of the Cryptography PLG:

CreateJWT FNC has the following properties:

  • Secret key: The secret key as LST<BYT> TYP or base64 to encode the payload with.
  • Payload: The payload to include in the token. It must be a valid JSON string.
  • Algorithm: The algorithm to use in the encoding (HS256, RS356 etc.)

Secret key: This will be the $.Setting value that you added when you configured the RESTHost svc Auth config with the secret key.

:warning: Important : Make sure the same secret key value is is used when verifying and generating tokens.

Payload: This will contain verification claims in a JSON format. These claims are properties of the token which are used to verify it. Things such as expiry time (exp) of the token or issuer (iss) can be included.

:information_source: A unique_name claim is mandatory in the payload which will contain a unique identifier. This unique_name claim will be decoded from the JWT Token during the built-in secuirty validations and then passed in to the operation via the $.Input.Data.HttpContext.User.Name.

Please note the terms 'Process' and 'Custom Type' have been depreciated and have been replaced with 'Function' and 'Type' respectively. More details here.
The explanations are mostly for Linx5 users.

Feel free to contact support@linx.software and we'll assist.

Create a JSON Payload

In order to create the JSON object which will contain the necessary fields of information, you can import a Custom TYP by doing the following:

  1. Right-click on a project or folder in the Solution Explorer.

  2. Select Import Custom Type.

  3. In the text editor, copy and paste the below JSON which contains some claims properties:

        {
            "iss":"",
            "sub":"",
            "aud":"",
            "exp":"",
            "nbf":"",
            "iat":"",
            "jti":"",
            "unique_name":""
        }

  1. Give the imported Custom TYP the name of jwt_token and click Create.

    :information_source: Note: This will create a jwt_token TYP in the Solution Explorer. This Custom TYP is now available to reference throughout the Solution via the drop-down selectors as well as being able to be added as a local instance to an operation or process Function .

    Now an instance of the jwt_token TYP needs to be added to the operation so that the claims can be configured.

  2. Next, drag-and-drop the jwt_token TYP from the Solution Explorer onto the process Function or operation in the canvas that you want to generate the tokens in.

  3. In the Properties of the jwt_token TYP instance within the operation , expand the Value field, using the field editor.

    This will open up the field editor where you are able to add values to the claim fields of the jwt_token TYP. These will be used to store validation and additional information.

  4. In this example, the expiry time (exp) claim is going to be set for the token.

    image56

    This is done by selecting the EX from the drop down to expand the editor.

    A dynamic expression is used which will take the current timestamp at execution and add a pre-configured number of seconds to it (stored as a $.Setting value):

    = ($.System.CurrentDateTime - "1970-01-01".ToDateTime("yyyy-MM-dd")).TotalSeconds + $.Settings.JWTExpirySeconds

  5. Next, the unique_name claim value is added to the token.

    :information_source: Note: This unique_name claim will be passed in to the operation from the built-in security validations for HTTP Bearer authentication via the AuthenticationData . This identifier can be something like a User's id stored in a database.

  6. Click Save.

Now that the jwt_token TYP has been configured with the claims value, a JWT Token can be generated.

Generate a JWT token

To generate a JWT token using the secret key and payload, do the following:

  1. Drag a CreateJWT FNC from the Plugins Panel onto the operation or process, positioning the CreateJWT FNC below the jwt_token TYP.

  2. Configure the Properties of the CreateJWT FNC like below:

    • Secret Key: $.Settings.JWTTokenSecretSigningKey.ToBytes().ToBase64()

      This will encode the secret signing key into a base64 format.

    • Payload: jwt_token TYP.

    • Algorithm: Selected preferred algorithm to use, i.e. HS256

The result of CreateJWT FNC will be a large STR TYP containing a sequence of characters representing the JWT Token which can then be issued to in the operation’s response.

Return JWT Token

Tokens can be returned as a basic type such as a STR TYP or a Custom TYP. Usually, tokens are returned as a in the response body as a JSON object containing additional information, i.e. the expiry time of the token.

    {
      "token_type": "Bearer",
      "expires_in": 3599,
      "access_token": "eyJ0eXAiOiJKV1QiLCJhiOiJIsIng1dCI6Ik1uQ19WWmNBVGZNNXB"
    }

Generic process Function Result

In order to return a token as the result of a process Function :

  1. Import the above JSON as a Custom TYP and give it the name of token.

  2. Configure the result of the process Function by editing the Output fields in the Properties to have an output with the TYP of token TYP.

  3. Add a SetValue FNC the the end of the process Function and configure the Properties like below:

    • Target: $.Output.token
    • Source: [expand field editor]
      • access_token: CreateJWT
      • expires_in: 3599
      • token_type: Bearer

This process Function can now be used interchangeable and referenced in several operations and processes in the Solution.

Return token in operation response

In order to return a token as the response body of a RESTHost svc operation :

Add the below object to the API Definition:

    Token:
      type: object
      properties:
        access_token:
          type: string
        expires_in:
          type: integer
        token_type:
          type: string

You will then need to reference this object as the response in the API Definition :

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'

To return the result of the CreateJWT FNC as the response body of the operation, add a SetValue FNC to the bottom of the operation and configure the Properties like below:

  • Target: $.Output.Data.Response200
  • Source: [expand field editor]
    • access_token: CreateJWT
    • expires_in: 3599
    • token_type: Bearer

The response body of the operation will then contain this token object which contains the generated JWT Token.

:green_book: Learn more about returning Custom TYP in responses.