OAuth based SSO

The the Single Sign On authentication based on the OAuth 2.0 protocol

OAuth Provider requirements

1. Provide a special login page that can authenticate users.

2. Provide a token service that would allow validating the authentication code.

3. Issue 'client_id' and 'client_secret' to the FORM system to identify the requests coming from our systems.

4. Store the 'client_secret' securely and validate 'client_id' and 'client_secret' in requests when required

Overall authentication process description

1. Upon opening the Mobile app or the portal, the users will be requested to enter the Portal ID. 
   

2. Once the Portal ID is entered, the app will open a WebView taking the user to the authentication endpoint (a 'special' login page) provided.
   For example https://login.qccompany.com/services/oauth2/authorize. 
   The following parameters will be provided in the request to the authentication endpoint:

   1. response_type - this parameter will always equal 'code'. It is required for compliance with the OAuth2 protocol requirements.

   2. client_id - a key using which the FORM platform will present itself. This can be a random value that both systems will have saved.

   3. redirect_uri - the URL where the user should be redirected after successful authentication.

   4. The example request may look as follows: https://login.example.com/services/oauth2/authorize?response_type=code&client_id=Form_com&redirect_uri=https%3A%2F%2Fapp.form.com%2F4code_callback.jsp
      

3. The user is to enter login credentials. Once the credentials are entered, the system must validate the credentials
   

4. When the validation has been completed successfully, the user will be redirected to the link specified by the 'redirect_ui' with the following parameters in the request:

   1. code - a unique code that will be used by FORM system to verify the authentication and obtain the auth token.

   2. The example redirect request may look as follows: https://app.form.com/code_callback.jsp?code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D
      

5. FORM will send a POST request to the login URL,
   for example, https://login.example.com/services/oauth2/token to validate the code and obtain the auth token.
   The POST request will contain the following parameters:

   1. grant_type - this will always equal to 'authorization_code'

   2. client_id - ID of the FORM system, same as described in 2.a above

   3. client_secret - a code that authorizes the FORM system to access the token service.
      This code must be treated securely (encrypted, not presented in clear text, etc.)

   4. code - the authentication code received in step 4, as described above.

   5. The example POST may look as follows
      

      CODE

      POST /services/oauth2/token HTTP/1.1
      Host: login.example.com
      grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZVEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=Form_com&client_secret=1955279925675241571&redirect_uri=https%3A%2F%2Fapp.form.com%2Fcode_callback.jsp

6. The expected response to the POST request by providing the following parameters in JSON format:

   1. access_token - a random value.

   2. user_id - a unique identifier of the user that would uniquely identify the user in both the FORM Contact Manager and the SSO provider

   3. If the code is not valid, an error response (for example, HTTP code 401) should be returned indicating that the request is not valid. 

   4. CODE

      The example of the response bode may look as follows:

      CODE

      {"access_token" : "00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4",

      CODE

      "user_id": "A765482"}

7. If the response is correct and the token has obtained the FORM system, and the user with the specified 'user_id' exists in the FORM Contact Manager and has access to the Portal, the FORM System will allow the user to enter the application.