OAuth2.0 is the most popular authorization type being used by apps. It notifies a Resource Server that the Resource Owner (end-user) is granting permission to a Third-Party App to access their account information. The Resource Server is assured of the end-user’s identity through a Third-Party App, this is called Three Legged Communication. For more info about OAuth2.0, read our guide.
Configuring Your App's Authorization Via OAuth2
Step 1: Go to the Authorization tab and select the Authorization Type as OAuth2, then click on 'Continue.'
Note: The Authorization Type cannot be changed once saved.
Before proceeding, make sure you have registered Integry's redirect URL (https://app.integry.io/auth/redirect) in your app. This URL always remains the same, no matter which app you're connecting. Using this URL, your app will return the access token to Integry and will respond to all the API calls Integry makes in future. We're using Capsule CRM in this example.
How Does Integry use Access Tokens?
Token-based authentications use access tokens to allow an application to access an API. When the end-user authenticates and authorizes Integry to access their application, the application's Authorization Server returns an access token to Integry. This access token is then used in the API call that Integry makes to access the protected resources from the application's Resource Server. The access token in the API call notifies the API that the bearer of the token (Integry) has been authorized to perform certain actions. These actions are specified by the scope that is granted during the authorization. Read on to see how you can configure this process while creating your App Connector.
Step 2: In the Authorization tab, provide the following information.
- Client ID: Once you'll register Integry's URL inside the app, it'll provide a Client ID to allow Integry to access its API.
- Client Secret: The app also provides a Client Secret when you'll register Integry's URL. The Client ID and Client Secret strings help the app authenticate Integry.
- Grant Type: Grant Type refers to the way your application provides an access token to Integry. The most common Grant types are Authorization Code and Client Credentials. Choose the Grant type your app supports.
- Authorization URL: The authorization URL is where Integry sends your end-users to authenticate their account.
- Token URL: It is the URL through which the application shares the access token with Integry.
Adding URL Parameters
Sometimes, some APIs and applications require you to pass some non-standard parameters when you're redirecting the end-user to the Authorization URL.
Step 3: If your app requires that, you can add those parameters by clicking the 'Add URL parameter' button. URL Parameters are a way to structure additional information for a given URL.
You can configure the keys and values by providing a parameter name and value here.
Since, we require the access token in the form of a "code", we'll notify the Authorization Server to provide us the response in the form of a code through the URL parameter.
This name and value will be appended to the Authorization URL.
Step 4: Click on Advanced Settings to enter Scopes.
A scope is a mechanism in OAuth 2.0 to limit an application's access to the end-user's account. In this case, Integry can request one or more scopes, this information is then presented to the end-user in the consent screen, and the access tokenissued to Integry will be limited to the scopes granted.
Step 5: Next, you'll test the OAuth flow. Click on 'Test Authorization.'
This will save all this configuration into Integry's database and launch the OAuth authentication flow in a separate pop-up window.
Note: You need to enable the pop-ups in your browser to access the flow.
If you aren't already logged into your Capsule account, you will be redirected to Capsule's Authorization URL to authenticate your account. If you're already logged in, Integry will make a request to access your Capsule Account.
Click on 'Allow' to enable Integry to access your Capsule account.
If the OAuth flow is working fine until now, you'll be taken to the App Connector Builder screen where you can see that your OAuth flow was tested successfully. Click on 'Continue.'
Testing the API Call
Step 6: In this step, you'll configure your API call and test how the call will be made for every individual end-user.
Enter the following information.
- Request URL: The Request URL consists of an HTTP method, a Base URL, and a resource URI. This is the URL that will be hit when API requests are made on the Resource Server.
- Headers: Each API request is authenticated with the end-user's access token. This access token is included in the Header of each request that is made to the Resource Server. The Bearer token is generated by the Authorization Server in response to a login request.
Click on 'Test Authorization' after entering the Request URL and Header(s). Then, click on 'Continue.'
You have successfully configured your application's authorization via the OAuth2 authorization method. Now, you can start creating Activities inside your newly created App Connector.
OAuth Flow Between Integry and Third-Party App
Here is the flow diagram that explains the OAuth process between Integry and a third-party app.
- Integry's user starts to creates the authorization in Integry. Integry starts the OAuth process by asking to access the user's account on the Third-Party App.
- Integry passes this request to the Authorization Server.
- The user's browser opens the Authorization URL. Here, the user is presented with the Authorization UI of the Third-Party App.
- The user enters their login credentials and allows Integry to access the Third-Party App.
- The user-submitted data is presented to the Third-Party App's Authorization Server.
- The Authorization Server verifies the user, creates the Authorization Code, and sends it back to the browser.
- Integry uses this Authorization Code to get access token from the Authorization Server.
- The Authorization Server returns the access token to Integry.
- Integry uses this access token in the Header of the API call it will make to access the protected resources from the Third-Party App's Resource Server.
- The Resource Server returns the protected resources to Integry.