# Authentication

Version: 1.0 | Release Date: 30/6/2018

# OAuth 2.0 Protocol

The access authentication of web services on M18 is based on OAuth 2.0 Protocol, for details, please refer to http://oauth.net/2/.

# OAuth Applications in M18

For any third party application that needs to call M18 web services, the application must be registered in [OAuth Applications] in M18:

register

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 M18 User. No user's action is needed.

For the first and second authorization type, the third party application is not aware of the M18 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 M18 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 M18
redirect_uri String(Query) Required. Authorization callback URL registered on M18

# 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 M18
client_secret String(Query) Required. Client Secret registered on M18
code String(Query) Authorization Code get from M18 using the Auth URL
redirect_uri String(Query) Required. Authorization callback URL registered on M18
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 M18 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 ![Implicit Grant Type](./assets/Implicit Grant Type.png)

# 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 M18
redirect_uri String(Query) Required. Authorization callback URL registered on M18

# Type 3: Resource Owner Password Credentials Grant

In Resource Owner Password Credentials Grant, M18 users need to provide their user name and password to the third party application. The application uses that to request authorization from M18 directly.

Interactive flow of Resource Owner Password Credentials Grant Implicit Grant Type

# 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 M18
client_secret String(Query) Required. Client Secret registered on M18
username String(Query) Required. Username of the M18 User
password String(Query) Required. Password of the M18 user. The password must be SHA1 hashed