OAuth 2.0 Authentication
OAuth 2.0 Overview
The OAuth 2.0 includes three processes in order for client to get resources from server provider:
- The client will initialize a GET Auth request to server with authorization url, which usually has the pattern like: http://example.com/authorize, along with some query parameters like:
Client_id: Verify identity.
Client_secret: Verify identity.
Response_type: Usually “code” when using for authorization.
Redirect_uri: The URI to redirect to after the user grants or denies permission.
State: Unique identifier for this OAuth request.
Scope: The permissions the user will have when performing the Api request.
The response from the Auth request will contain the State itself and an authorization_code, which is used to exchange for the access_token and refresh_token in the following step.
2. Next the client will make a POST request to get the access_token using the authorization code from the previous step. Usually the token url has the pattern: https://example.com/token, along with request body, which usually contains the following parameters:
Grant_type: Usually “authorization_code”.
Code: The authorization code received from the previous step.
Client_id: Verify identity.
Client_secret: Verify identity.
The resulting response usually contains the following data:
Access_token: the token used for retrieving resources.
Refresh_token: the token used for getting access_token when it is expired.
Token_type: Usually “Bearer”.
Scope: The access permission this client has to perform request.
Expire_in: The expiration time for access_token.
3. Now with the access_token, the client can make request to provider server to retrieve resource within the permission scope
Setup OAuth in Dev Platform
The OAuth setup section in the App details page is shown in the picture below.
a) Add settings
Settings are shared resources for all the APIs within the app. Each setting can have either of two access levels depending on how the setting is intended to be used - user level or organization level. Organization level settings are prompted to be populated when the app is installed from the app store. User level settings are populated when the user interacts with the app.
For this app’s OAuth, we have created three organization level settings: client id, client secret and redirect_uri, and two user level settings: access_token and refresh_token. These settings will be retrieved and used when the endpoint of this app is being called. The settings can also be used in individual APIs as Headers.
The access_token and refresh_token will be populated in our database once the OAuth authentication process is completed. When the same request is made again, we will retrieve the access_token from the database and perform the request.
Alternatively, if you do not want any App store prompts, you can choose to only create the two user level settings: access_token and refresh_token here and leave the other organization level setting in the OAuth Configs as shown in next part.
b) Add OAuth Config
Definitions and templates for each field in the OAuth Config.
Config name: The name you want give to your OAuth config.
Link url: The authorization url along with query parameters.
{{auth_url}}?client_id={{client_id}}&response_type=code&redirect_uri=https:%2F%2Fauth.capacity.com%2Fv1%2Fdev_oauth%2Fcallback&scope={{scope}}&state={{state}}
Extraction path auth code: Json path to retrieve auth code from response received on authorization request.
Extraction path access token: Json path to retrieve the access token from response received on access token request.
Extraction path refresh token: Json path to retrieve the refresh token from response received on access token request.
Access token variable name: The access token setting variable created in step a.
Refresh token variable name: The refresh token setting variable created in step a.
Request body: A JSON formatted string containing key value pairs that will be sent along with the POST request to the token url
The auth code will be populated from database with the value extracted using the JSON path provided above.
{"grant_type": "authorization_code", "redirect_uri": "https://auth.capacity.com/v1/dev_oauth/callback", "code": "{{auth_code}}", "client_id": {{client_id}}, "client_secret": {{client_secret}}}
Refresh token url: The url to make a request to when the token needs to be refreshed
Token url: The url to make a request to when exchanging the auth code for an access token.
Refresh token body: The body to send with the POST request when performing the request to refresh the token.
Example: {"refresh_token": {{refresh_token}}, "grant_type": "refresh_token"}
Logo url: Url of the logo of the app that would show on the landing page where the user allows access.