Authentication
Version: 1.0 | Release Date: 30/6/2023
# OAuth 2.0 Protocol
The access authentication of web services on aiM18 is based on OAuth 2.0 Protocol, for details, please refer to http://oauth.net/2/.
# OAuth Applications in aiM18
For any third party application that needs to call aiM18 web services, the application must be registered in [OAuth Applications] in aiM18:
The Client ID and Client Secret will be generated after the record is saved.
# Authorization Type
| Authorization Type | Third party application needs to meet the conditions | User Authorization |
|---|---|---|
| Authorization code | Needs a Web Server, such as JBoss or Tomcat. | Requires independent authorization for each user. |
| Implicit Grant Type | No need to have Web Server, such as some Mobile App applications. | Requires independent authorization for each user. |
| Resource Owner Password Credentials Grant | Third party application needs to know the username and password of the aiM18 User. | No user's action is needed. |
For the first and second authorization type, the third party application is not aware of the aiM18 user's username and password, but independent authentication (login) for each user is required.
# Type 1: Authorization Code
Authorization code is the most complete, the most rigorous process of the 3 authorization types. Its main characteristic is using the backend server of the third party program to interact with the aiM18 authentication server.
Interactive flow of Authorization Code
# Auth URL
GET http://[server]/jsf/rfws/oauth/entry
# Auth Parameters
| Name | Type | Description |
|---|---|---|
| response_type | String(Query) | Required. The value must be "code" |
| client_id | String(Query) | Required. Client ID registered on aiM18 |
| redirect_uri | String(Query) | Required. Authorization callback URL registered on aiM18 |
# Access Token URL
GET http://[server]/jsf/rfws/oauth/token
# Access Token Parameters
| Name | Type | Description |
|---|---|---|
| grant_type | String(Query) | Required. The value can be "authorization_code" or "refresh_token" |
| client_id | String(Query) | Required. Client ID registered on aiM18 |
| client_secret | String(Query) | Required. Client Secret registered on aiM18 |
| code | String(Query) | Authorization Code get from aiM18 using the Auth URL |
| redirect_uri | String(Query) | Required. Authorization callback URL registered on aiM18 |
| refresh_token | String(Query) | Refresh Token used to get the Access Token |
# Type 2: Implicit Grant Type
Third party program's backend server is not involved, access token is requested directly from user's browser to aiM18 server. The returned access token is therefore visible to the user (show directly in returned URL) Notice that refresh token is not returned in this authoization type.
Interactive flow of Implicit Grant Type
# Access Token URL
GET http://[server]/jsf/rfws/oauth/entry
# Access Token Parameters
| Name | Type | Description |
|---|---|---|
| response_type | String(Query) | Required. The value must be "token" |
| client_id | String(Query) | Required. Client ID registered on aiM18 |
| redirect_uri | String(Query) | Required. Authorization callback URL registered on aiM18 |
# Type 3: Resource Owner Password Credentials Grant
In Resource Owner Password Credentials Grant, aiM18 users need to provide their user name and password to the third party application. The application uses that to request authorization from aiM18 directly.
Interactive flow of Resource Owner Password Credentials Grant
# Access Token URL
GET http://[server]/jsf/rfws/oauth/token
# Access Token Parameters
| Name | Type | Description |
|---|---|---|
| grant_type | String(Query) | Required. The value must be "password" |
| client_id | String(Query) | Required. Client ID registered on aiM18 |
| client_secret | String(Query) | Required. Client Secret registered on aiM18 |
| username | String(Query) | Required. Username of the aiM18 User |
| password | String(Query) | Required. Password of the aiM18 user. The password must be SHA1 hashed |
This authorization method is commonly used for API integration. For more information, you can refer to this example.
# API Fine-grained control
The data of aiM18 is composed of modules, each module provides basic APIs such as Create, Update, Read, Delete, as well as other APIs. You can set permission controls separately for the basic APIs and other APIs. Please refer to the program for detailed control principles.
# CURD Control
Developer can decide if module right checking is needed through the check_right parameter. When check_right parameter is empty, system assumes module right checking is skipped.
CURD interface assumes all requests have to be checked against module right of the corresponding user.
# Other Control
This setting is not RECOMMENDED if you want to minimize web service (and data) accessed by a third-party application.
You can set rules for access control separately for each API.
