AlchemyJ by Axisoft

4.1

REST API Endpoint Security Worksheet

This worksheet defines the access control setting for endpoints.

Basic Settings

Enable endpoint security

Yes, enable the REST API Endpoint Security service. No, does not enable the REST API Endpoint Security service.

Use external configuration

  • Yes - Endpoint access right configuration will be loaded from an external source. Changing configuration can be done at the external source without rebuilding the project. In other words, the configuration is externalized.

  • No - Endpoint access right configuration is set in this worksheet. Therefore, it is fixed and cannot be changed after the API project has been built. Changing the access right configuration requires re-building the project to become effective.

Static Access Control Configuration

Configure this section if you set the Use external configuration to No. You can configure one or more records here. The system will run through the rules from top to bottom. It will stop when the first match is found. For example,

/customer/tel
/customer/**

Suppose the configuration contains the above records. A request of http://customer/tel will match the first record since it is the first match.

HTTP Method

AlchemyJ security service enables you to control the access right of the resources by HTTP Method. The following options are provided, POST, GET, PUT, PATCH, DELETE and ALL. The option ALL means matching any method.

URL Pattern

Define the URL pattern for configuration. 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

Access Operator

The access type assigned.

  • Anyone - No access control. All requests to this endpoint will be allowed.

  • Authenticated users - Only logged in users may gain access.

  • Has any required authorities - Only logged in users with any one of the authorities defined in the authority list can gain access.

  • Has all required authority - Only logged in users with all authorities defined in the authority list can gain access.

Authority List

A list of authority values. Use comma (,) to separate multiple items.

External Access Control Settings

This table defines how endpoint access right configuration should be loaded from an external source. Set the values in this table when Use external configuration is Yes.

Retrieval time

The time when the Endpoint access right configuration is loaded.

  • On Server Start - Retrieves endpoint access right configuration upon application server startup.

  • By Request - Retrieves endpoint access right configuration on every request.

Retrieval mode

How the endpoint access right configuration will be loaded. When Retrieval time is "On Server Start", this value can only be SQL query.

  • SQL query - Loads the configurations from a database by running a SQL statement.

  • Stored procedure - Loads the configurations from a database by executing a stored procedure. Retrieval time must be “By Request” as the stored procedure should return the authorization result to the requested resource by the current user.

Retrieve data source from

Provide the Data Resource ID you would like to use for retrieving data. The resource should exist in the Data Source Configuration section in External Resources Worksheet. The default value is "primary".

Configuration retrieval SQL query

The SQL statement for retrieving the external endpoint access right configuration

If Retrieval time is “On Server Start”, the query should return the following columns: “HTTP_METHOD”,“URL_PATTERN”, “ACCESS_OPERATOR” and “AUTHORITY_LIST”. No parameter is required for the query. It contains the same structure as defined in the Static Access Control Configuration.

If Retrieval time is “By Request”, the query should return a single column “CHECK_RESULT”. The value 1 indicates the access to the requested resource is granted to the user. Other values indicate access is denied. The following parameters can be used in the query.

  • HTTPMETHOD - The parameter will be replaced by the HTTP method of the request.

  • REQUEST_URL - The parameter will be replaced by the request URL

  • AUTHENTICATED - The parameter will be replaced by TRUE or FALSE to indicate the user has logged in or not.

  • USERNAME - The parameter will be replaced by the user name of the current user.

  • AUTHORITIES - The parameter will be replaced by the authorities that are granted to the current user. Multiple values will be separated by comma (,). For example, "Admin,Staff"

Configuration retrieval stored procedure

The name of the stored procedure that should be called to return the check result. Set this when Retrieval mode is Stored procedure. The stored procedure should have the following input parameters:

  • REQUEST_URL - The parameter will be replaced by the request URL
  • AUTHENTICATED - The parameter will be replaced by TRUE or FALSE to indicate the user has logged in or not.
  • USERNAME - The parameter will be replaced by the user name of the current user.
  • HTTPMETHOD - The parameter will be replaced by the HTTP method of the request.
  • AUTHORITIES - The parameter will be replaced by the authorities that are granted to the current user. Multiple values will be separated by comma (,). For example, "Admin,Staff"

It should return an output parameter called “CHECK_RESULT”. The value 1 indicates the access to the requested resource is granted to the user. Other values indicate access is denied.

← REST API User Details Service WorksheetDB Schema Worksheet →