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 orbase64
to encode the payload with.Payload
: The payload to include in the token. It must be a validJSON
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
.
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.
A
unique_name
claim is mandatory in thepayload
which will contain a unique identifier. Thisunique_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
.
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:
-
Right-click on a project or folder in the Solution Explorer.
-
Select Import Custom Type.
-
In the text editor, copy and paste the below
JSON
which contains someclaims
properties:
{
"iss":"",
"sub":"",
"aud":"",
"exp":"",
"nbf":"",
"iat":"",
"jti":"",
"unique_name":""
}
-
Give the imported Custom TYP the
name
ofjwt_token
and click Create.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 orprocessFunction .Now an instance of the
jwt_token
TYP needs to be added to the operation so that theclaims
can be configured. -
Next, drag-and-drop the
jwt_token
TYP from the Solution Explorer onto theprocessFunction or operation in the canvas that you want to generate the tokens in. -
In the Properties of the
jwt_token
TYP instance within the operation , expand theValue
field, using the field editor.This will open up the field editor where you are able to add values to the
claim
fields of thejwt_token
TYP. These will be used to store validation and additional information. -
In this example, the expiry time (
exp
)claim
is going to be set for the token.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
-
Next, the
unique_name
claim value is added to the token.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'sid
stored in a database. -
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:
-
Drag a CreateJWT FNC from the Plugins Panel onto the operation or process, positioning the CreateJWT FNC below the
jwt_token
TYP. -
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 :
-
Import the above
JSON
as a Custom TYP and give it the name oftoken
. -
Configure the result of the
processFunction by editing theOutput
fields in the Properties to have an output with the TYP oftoken
TYP. -
Add a SetValue FNC the the end of the
processFunction and configure the Properties like below:- Target:
$.Output.token
- Source: [expand field editor]
access_token
:CreateJWT
expires_in
:3599
token_type
:Bearer
- Target:
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.
Learn more about returning Custom TYP in responses.