REST API Login Service Worksheet
Introduction
This worksheet defines the API authentication configurations. Essentially, where to get login information, how to authenticate the user, how to store the credential and more.
When this worksheet is set up, an endpoint for login and logout (optionally) will be automatically created. Users will be able to log in the API by sending their user name and password to the login service. If the user details service is set up, it will look to use information such as account state as well. After authentication passes, the credential information will be stored as a session or as a JSON Web Token (JWT).
When an API receives a request to an endpoint, it tries to retrieve the login information from the session, JWT, or database token. Configurations of JWT and database token are defined in Token Authorization Configurations. If endpoint security configurations have been defined, it will check whether the current user has access to the requested resource.
This explains how the REST API Login Service, User Details Service, Token Authorization and Endpoint Security work together. The rest of the document describes the details of each setting on the REST API Login Service Worksheet. It contains the following sections:
Basic Settings
Enabled login service
- Yes, enable the login service.
- No, does not enable.
Authentication source
- LDAP - This means that after the service extracts user name and password from a request, they will be passed to an LDAP server for authentication check. If authentication is passed, this user name will become the logged-in user name. In the current version of AlchemyJ, this is the only option supported. Other validation type may be supported in the future. For example, calling a stored procedure, SQL or a web service to validate a user name/password pair.
In any case, the authenticated user name will be written to REST Security User Name (name: AlchemyJ_REST_Sec_UserName) in %%SysRuntime. Modeler can write formulas to refer to this cell to retrieve the current login user name.
Login Service Settings
Login URL path
The endpoint URL that provides the authentication (login) service. Login requests should be sent to this URL.
User name source
This defines where the user name is obtained from the request.
Request header - Get the username from the request header. The key name is specified in User name field name.
Request parameter - Get the username from the request parameters. The parameter name is specified in the User name field name.
It is not recommended to pass the user name and password via URL query string parameter as URL is often logged in access logs of any servers that the request passes through. They might also be saved in browser history.
User name field name
The header name or the request parameter name for getting the user name.
For example, if this key is set as "user" and User name source is "Request header", the authentication service will try to find the "user" element from the request header and use its value as the user name for authentication.
Password source
This defines where a password should be obtained from the request.
Request header - Get the password from the request header. The key name is specified in the Password field name.
Request parameter - Get the password from the request parameters. The parameter name is specified in the Password field name.
Password field name
The header name or the request parameter name for getting the password.
Login success handle type
JSON - Return the defined JSON when authentication passes
Customized Function Point - Execute the function point when authentication passes.
Login success return JSON
Defines the JSON response when Login success handle type is JSON. It supports the following place holders:
- ${username} - will be replaced by the name of the current user.
- ${authorities} will be replaced by the authorities of the current user.
For example,
{"message":"Authentication is passed, the user name is ${username}"}
If the user submits "Tom" as the user name to the login service, the following JSON will be returned when authentication is passed.
{"message":"Authentication is passed, the user name is Tom"}
Login success handle function point
Define the function point name when Login success handle type is Customized Function Point. The function point should be defined in current AlchemyJ workbook with POST operation only. The response of the function point will become the response of the Login endpoint.
Login failed handle type
JSON - Return the defined JSON when authentication fails
Customized Function Point - Execute the function point when authentication fails.
Login failed return JSON
Defines the JSON response when Login failed handle type is JSON. It supports the following place holder:
- ${errorMessage} would be replaced by the authentication error message when authentication failed. This is similar for a successful case.
Please note that if the REST API User Details Service Worksheet is enabled, the authentication will also fail if USER_STATE is not 0.
Login failed handle function point
Define the function point name when Login failed handle type is Customized Function Point. The function point should be defined in current AlchemyJ workbook with POST operation only. The response of the function point will become the response of the Login endpoint.
User information store type
Defines how authentication information should be stored.
Session - To store the information in the web application server session.
JSON web token (JWT) - Generate a JWT token and put the user name in the payload. API caller should get the JWT token and include it in the subsequent requests.
LDAP Authentication Setting
This section defines the LDAP connection settings when the Authentication source (in Basic Settings) is “LDAP”.
LDAP connection identifier
Provide the LDAP resource ID you would like to use for authentication. The resource should exist in the LDAP Connection section in External Resources Worksheet. The default value is "primary".
LDAP user-dn replacement holder
LDAP expects a distinguished name (DN) when authenticating a user. It includes information such as the domain, organization unit and etc. The login name received by the API, however, can only contain the user id part. This field defines the pattern used to form a DN. It supports the following place holder:
- {0} will be replaced by the name of the current user.
For example,
{0}@axisoft.com
uid={0},ou=people
If the {0} is Peter, the first example would become Peter@axisoft.com and the second example would become uid=Peter, ou=people.
JSON Web Token Generation Settings
This section defines how JWT is processed when login passes. It is applicable when the User information store type is “JSON web token (JWT)”. For the details on the configuration for processing (consuming) the JWT, please refer to the JSON Web Token Authorization section of the REST API Token Authorization worksheet.
JWT Secret
The secret key for generating the JWT token.
If this API only generates JWT for other servers to use. Define a key here and share it with other servers.
If this API generates JWT for authentication of itself. Define your own key here and it must be the same as the one defined in the JSON Web Token Authorization section of REST API Token Authorization worksheet. Otherwise, it will fail when parsing the JWT.
In any case, the key should NOT be shared with a client (e.g. a user)
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).
Token location
Where 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. It is commonly set as Authorization.
Logout Service Setting
Setup this section to enable the logout endpoint and set its configuration.
Enabled logout feature
Yes - Logout endpoint will be available in the API.
No - No logout endpoint in the API.
Please note the logout feature only applies to the session (User information store type = Session).
Logout URL path
The URL of the logout endpoint. It accepts any HTTP requests. Accessing this endpoint will log out the user.
Invalidate session
Yes - Information stored in session will be removed after logout.
No - After logout, the API will treat the user as not logged in. However, information stored in the user session will still be available until it expires.
Delete cookie key list
A list of cookie items that would be deleted when logging out. The list of cookie items would be separated by comma (,).
Logout success handle type
JSON - Return the defined JSON when logout success.
Customized Function Point - Execute the function point when logout success .
Logout success return JSON
The JSON response should be returned after logout. It supports the following place holder:
- ${username} would be replaced by the user name of the current user.
For example,
{"statusCode": 200, "logoutUser":"${username}"}
If the current user name is Tom, the below JSON would be returned after successfully logging out.
{"statusCode": 200, "logoutUser":"Tom"}
Logout success handle function point
Define the function point name when Logout success handle type is Customized Function Point. The function point should be defined in current AlchemyJ workbook with POST operation only.