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. Two asterisks can be used to indicate a wildcard. For example,

/customer/**

It means all resources under [domain name]:[port]/customer/ would be matched.

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.

• 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

If you use the same data source with the REST API, you can input primary directly here. If you need to use a separate one, you need to configure another data source in the Data Source Configuration section of the REST API Worksheet then input the Identifier name here. Note that the Identifier name must be in lowercase and cannot be primary as it is used by the REST API itself already.

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:

• 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"

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.