REST API Token Authorization Worksheet
You can configure the REST API Token Authorization Worksheet to enable your REST API to support JSON Web Token for authorization. The token can be issued by the same system or another system.
This worksheet defines how the API is authorized by the JSON Web Token.
Basic Settings
Enable token authorization
Yes, to enable the token authorization. No, does not enable the token authorization.
JSON Web Token Authorization
Enable
Yes, to enable the JSON Web token authorization. No, does not enable the JSON Web token authorization.
Protected URL path
This property defines which URL pattern where a JWT token is expected. The path uses Ant-style path pattern matching. It uses the following rules:
-? matches one character
-* matches zero or more characters
-** matches zero or more 'directories' in a path
For example,
-/** matches all resources
-/customers/** matches all resources under customers
-/**/example matches /abc/example and /example
JWT Secret
The key used to renew and decode the JWT. For the configuration of generating the JWT, please refer to the JSON Web Token Generation Settings section of the REST API Login Service worksheet.
If this API only processes JWT that is generated by another authentication service, obtain the key from the administrator of that service.
If this API generates JWT for authentication of itself, define your own key here and it must be the same as the one that is defined in the JSON Web Token Generation Settings section of REST API Login Service worksheet. Otherwise, it will fail when parsing the JWT.
In any case, the key shall NOT be shared with a client (e.g. a user).
Token location
The place to store the generated JWT token. Two options are provided. Cookie: storing in browser cookies. Header: storing in HTTP header.
Token name
If the Token location is "Cookie", this defines the Cookie name. If the Token location is "Header", this defines the header element that is used for setting (response) and retrieving (request) the JWT. The default value is "Authorization". Please note that Token Location and Token Name should not unique.
Token refresh interval (ms)
The interval for refreshing the JWT token. The unit is in milliseconds.
Expiration (ms)
The expiration time of the JWT token. The unit is in milliseconds.
For example, if you set this as 1800000, that is 1800 seconds. The token will expire in 1800 seconds (30 minutes).
Invalid token return JSON
Defines the JSON response when the authentication fails. It supports the following place holder:
- ${errorMessage} would be replaced by the authentication error message when authentication failed. This is similar to the successful case.
Database Token Authorization
Enable
Yes, to enable the Database token authorization. No, does not enable the Database token authorization.
Protected URL path
This property defines which URL pattern where a JWT token is expected. The path uses Ant-style path pattern matching. It uses the following rules:
-? matches one character
-* matches zero or more characters
-** matches zero or more 'directories' in a path
For example,
-/** matches all resources
-/customers/** matches all resources under customers
-/**/example matches /abc/example and /example
Token location
The place to store the generated token. Two options are provided. Cookie: storing in browser cookies. Header: storing in HTTP header.
Token name
If the Token location is "Cookie", this defines the Cookie name. If the Token location is "Header", this defines the header element that is used for setting (response) and retrieving (request) the
Data Source
Provide the Data Source ID that stores the Database Token. The resource should exist in the Data Source Configuration section in External Resources Worksheet. The default value is "primary".
Checking SQL
The SQL statement for retrieving the USERNAME by Database Token. The SQL statement should retrieve a user name of provided Token information. it must return a single record with USERNAME.
Use ":TOKEN" in the SQL statement to indicate the Database Token. AlchemyJ will replace it with the actual Database Token.
SELECT USERNAME FROM XXX WHERE TOKEN = :TOKEN