Authentication for REST API

In most cases, REST API need to have authentication required in order to protect API call security. For instance, you may define whether a user needs to login and has some specific authorities to access a specific endpoint. AlchemyJ can help user to apply the security control on REST API via some configuration operations in AlchemyJ workbook.

Here we shall use the simple REST API generated via the REST API Sample Model to show how to add security control on the REST API. There have 3 security control cases to be shown in this recipe.

Case 1 - REST API can be accessed only when login authentication is passed, the user authentication information is kept in session

We shall use the REST API created via REST API Sample Model, and add user authentication when calling the endpoint 'http://localhost:8080/endpointGroup/resource1'.

1. Case Preparation

1.1. Create 'MyRESTAPI' via the 'REST API Sample Model', the detail procedures can refer to Get Started section.

1.2. Click 'Add Definition' button in AlchemyJ ribbon, select 'REST API Login Service' to add ##RestLoginService worksheet.

1.3. Select 'REST API Endpoint Security' to add ##RestEndpointSecurity worksheet.

2. Enable LDAP Authentication in ##RestLoginService worksheet

2.1. Go to ##RestLoginService worksheet

2.2. In 'Basic Setting' section, keep below default value no change.

2.3. In 'Login Service Settings' section, change 'User name source' and 'Password source' parameter value to 'Request Header', 'User information store type' parameter value to 'Session'.

2.4. In 'LDAP Authentication Setting' section, fill in 'LDAP user-dn replacement holder' parameter value as '{0}@domain.com', e.g. {0}@ABCCompany.com

3. Configure LDAP Connection Information in ##RestApi worksheet

3.1. Go to ##RestApi worksheet

3.2. Expand 'LDAP Connection' section and fill in LDAP server information in the section.

4. Enable Endpoint Authentication in ##RestEndpointSecurity worksheet

4.1. Go to ##RestEndpointSecurity worksheet

4.2. In 'Basic Setting' section, keep below default value no change.

4.3. In 'Static Access Control Configuration' section, add access control for URL '/endpointGroup/resource1' and '/login' as below.

5. Generate REST API and Verify Endpoint Authentication

5.1. Click 'Generate API' button in AlchemyJ ribbon to trigger REST API generation and execution.

5.2. Wait until 'MyRESTAPI' is generated and started.

5.3. Let's try following several calls using Postman to check if REST API authentication can work.

a. In Postman, create a request to call /endpointGroup/resource1, it is expected that authentication error shall return because there is no authenticated user in the session yet.

b. Because there is no user authentication yet, we shall make a new request to call '/login', and provide the correct domain user name and password in the 'Headers'.

c. Back to '/endpointGroup/resource1' tab in Postman, click 'Send' button to send the call again, it is expected that the endpoint call can be successful and the result shall be returned.

Case 2 - REST API can be accessed only when the login user has specified function entitlement, the user authentication information is kept in session

Comparing with case 1, the case has additional checking on the user entitlement, the endpoint can be accessed by these users who has specific functional entitlement. Because it is to do more security configuration base on case 1, the case shall continue the enhanced security configuration using the workbook generated in case 1.

1. Case Preparation

1.1. Prepare a database for REST API to keep user status and function entitlement information in the table. Here we use MSSQL database and create two tables as below to keep user status and function entitlement.

1.2. Insert AD user account and status into the table 'SEC_USERDETAIL'.

Note that the 'USERSTATUS' column possible value are 0, 1, 2, 3.

0 - normal account which means the user account status is normal.

1 - expired account which means the user account is expired.

2 - locked account which means the user account is locked.

3 - expired token which means the user token is expired.

1.3. Insert user function entitlement into the table 'SEC_USERDETAIL_AUTHORITY'. Here 'AM', 'BO', 'MO', 'RM' and 'SM' represents the role name.

1.4. Copy the AlchemyJ workbook generated in case 1 as case 2 AlchemyJ workbook.

1.5. Click 'Add Definition' button in AlchemyJ ribbon, select 'REST API User Detail Service' to add ##RestUserDetailService worksheet.

2. Enable User Detail Service in ##RestUserDetailService worksheet

2.1. Go to ##RestUserDetailService worksheet.

2.2. In 'Basic Settings' section, keep below default value no change.

2.3 In 'Database User Management' section, revise the SQL statement in 'User state SQL query' and 'Authority SQL query' parameter value as below.

3. Configure Data Source in ##RestApi worksheet

3.1 Go to ##RestApi worksheet.

3.2 In 'Data Source Configuration' configuration, configure the data source 'primary' connection information like below. Note that the 'Password' value is encrypted via 'Tools\Encrypt Passwords' button in AlchemyJ ribbon.

4. Configure DB Operation Type for Endpoint in ##RestEndpointGroup worksheet

4.1 Go to ##RestEndpointGroup worksheet.

4.2 In section 'Function Points', select 'Non-transactional' in column 'DB Operation Type' for the function point '/resource1'.

5. Configure Required Authority for Endpoint in ##RestEndpointSecurity worksheet

5.1 Go to ##RestEndpointSecurity worksheet.

5.2 In section 'Static Access Control Configuration' section, change 'Access Operator' value to 'Has all required authority' and add 'BO' in 'Authority List' column for the function '/endpointGroup/resource1'.

6. Generate REST API and Verify Endpoint Authentication

6.1. Click 'Generate API' button in AlchemyJ ribbon to trigger REST API generation and execution.

6.2. Wait until 'MyRESTAPI' is generated and started.

6.3. Let's try following several calls using Postman to check if REST API authentication can work.

a. In Postman, create a request to call '/endpointGroup/resource1', it is expected that authentication error shall return because there is no authenticated user in the session yet.

b. Because there is no user authentication yet, we shall make a new request to call /login, and provide the correct domain user name and password in the 'Headers', but the user has no 'BO' authority.

c. Back to '/endpointGroup/resource1' tab in Postman, click 'Send' button to send the call again, it is expected that the endpoint call should still be failed because current user has no required function entitlement 'BO' assigned.

d. Now we shall use a user account which has 'BO' function entitlement assigned. Back to '/login' tab in Postman, revise the user name and password, click 'Send' button to send the call again, it is expected that the user shall have 'BO' authority returned.

e. Back to '/endpointGroup/resource1' tab in Postman again, click 'Send' button to send the call again, it is expected that the endpoint call should be successful.

Case 3 - REST API can be accessed only when login authentication is passed, the user authentication information is kept in JSON web token

In this case, we shall store the user authentication using JSON Web Token, instead of session. We shall still use the workbook created in case 1 to show the steps about how to do the REST API security authentication using token.

1. Case Preparation

1.1. Copy AlchemyJ workbook created in case 1 as case 3 AlchemyJ workbook.

1.2. Go to ##RestLoginService sheet.

1.3. In section 'Login Service Settings', change 'User information store type' value from 'Session' to 'JSON web token (JWT)'.

1.4 Click 'Add Definition' button in AlchemyJ ribbon, select 'REST API Token Authentication' to add ##RestTokenAuthorization worksheet.

2. Configure Token Name in ##RestLoginService

2.1. Go to ##RestLoginService worksheet.

2.2. In section 'JSON Web Token Generation Settings', change the 'Token' parameter value from default value 'Authorization' to 'UserToken'.

3. Configure Token Name in ##RestTokenAuthorization

3.1. Go to ##RestTokenAuthorization worksheet.

3.2 In section 'Basic Settings', keep below default value no change.

3.4. In section 'JSON Web Token Authorization', change the 'Token name' parameter value from default value 'Authorization' to 'UserToken'.

4. Generate REST API and Verify Endpoint Authentication

4.1. Click 'Generate API' button in AlchemyJ ribbon to trigger REST API generation and execution.

4.2. Wait until 'MyRESTAPI' is generated and started.

4.3. Let's try following several calls using Postman to check if REST API authentication can work.

a. In Postman, create a request to call /endpointGroup/resource1, it is expected that authentication error shall return because there is no authenticated user in the token yet.

b. Because there is no user authentication yet, we shall make a new request to call '/login', and provide the correct domain user name and password in the 'Headers'. After authentication passed, a 'UserToken' field can be found in response 'Headers'.

c. Copy the 'UserToken' value in response header of above '/login' call.

d. Back to '/endpointGroup/resource1' tab in Postman, in request 'Header', paste the copied token value in 'UserToken' field.

e. Click 'Send' button and it is expected that the endpoint call should be successful.