An app connector helps Integry communicate with an app using its API. You can use these app connectors in your flows and help your end-users create integrations between different apps. The TPA (third-party app) connectors configured in Integry require an authentication method to enable Integry to access the TPA. Depending on the TPA, an authentication method is configured in the app connector that you or your end-users can use to authenticate your accounts.
We support the most popular authentication methods used by applications around the world and this article will give you a high-level overview about them.
Following are the authorization types supported in Integry:
- OAuth
- API-Key
- API-Key with URL
- API-Key with Secret
- Basic with URL
- Basic without URL
- Basic with API-Key
About OAuth
OAuth is a framework that delegates limited access to a third-party application to the end-user's data and other services.
OAuth is a highly recommended authentication type being used these days. It is secure and does not enable access to any sensitive information of the end-user or third-party app while authenticating. It notifies the 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.
OAuth 2.0
OAuth 2.0 is one of the most popular authentication mechanisms. For the detailed workflow, let us consider the following example.
I am a developer, writing a personal finance application. The end-user can connect to their bank and view account details using my app. The application uses OAuth 2.0 to connect to an external server to authorize its end-users.
Before going into the details, let's discuss the following entities:
- Resource Owner: The bank's end-user
- Third-Party Application (Client): The application that will connect to an external server for end-user authorization (the finance application in this case).
-
API: The server that the third-party will connect to for authorization (the bank in this case). This can be technically divided into two types:
- Authorization Server: The server solely responsible for the end-user authorization and access delegation
- Resource Server: The protected data that the end-user or third party app wants to access
Let's say that the end-user requested to view their transaction history via my app. As a result, an “Authorization Request” is sent to the bank's Authorization Server by the app.
The Bank Authorization Screen will be displayed where the end-user will be requested to authorize the app with their account. The end-user grants permission to the app called Authorization Grant along with an Authorization Code.
Authorization Grant along with Authorization Code is sent back to the bank, to request for an Access Token. This request is sent to the bank's Authorization Server. Once the bank receives and verifies the request, an access token is granted and sent back to the app for that end-user.
The app sends the access token to the bank Resource Server to retrieve the end-user's data whose permission was granted. The bank identifies the token as valid and sends back the requested data to the app.
The access tokens that are granted to the app are short-lived. Once they expire they can be renewed using Refresh Tokens. Refresh Tokens are long-lived tokens and used to regenerate access tokens once they are expired.
For all of this to work, the app has to be registered with the bank (API). This is independent of any end-user involvement and the app needs to provide the following information to the service it is registering with.
The app’s name and the website are pretty obvious whereas, Callback URL is the URL where the bank (API) will redirect the end-user after they have authorized their account.
How Does Integry use Access Tokens?
When a TPA's end-user authenticates and authorizes Integry to access the app, its 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.
What are Scopes?
A scope is a mechanism in OAuth 2.0 to limit an app's access to the end-user's TPA account. In this case, Integry can request for one or more scopes from the TPA while authenticating the end-user. These scopes are configured in the TPA connector created inside Integry. This information is then presented to the end-user in the consent screen while authenticating. The access token issued to Integry will be limited to the scopes granted. The scopes could be (but not limited to) read, write, access, create, delete, etc. Meaning, when an end-user allows Integry to access their TPA account, Integry can perform the afore-mentioned actions in the TPA.
API-key
API-key based authorization type is known for its simplicity. The end-user signs into TPA, gets their API key, and copies it in their application to use. API-key is the name given to a secret token that is submitted to a web service along with a request. The key identifies the end-user in the TPA and performs an API request on behalf of that end-user. For the scope of Integry, once you enter your API-key while authenticating, Integry will consume your API-key for future communication.
API-key based authentication is not a highly recommended auth type due to security loopholes. As an entity gets hold of the end-user's API key, they have to keep it safe (just like a password), because it maybe dangerous if an unauthorized entity accesses it.
API-key and Secret
This is a modification of API-key. A combination of API-key and API Secret is used for authentication. It works the same as API-key. When an application is registered with the API, it generates a key and a secret for that application. Whenever the application makes a request, its request consists of the key and secret as well.
API-key With URL
This works the same as API key, but the API calls are sent to the URL specified by the end-user while they're authenticating their TPA accounts.
Basic With URL
As the name suggests, this mechanism uses the basic technique to authenticate the end-users. An end-user communicates with a web server by sending a request with a set of credentials. It is the least recommended way of authentication. It requires your end-users to provide their actual username and password along with a custom URL while authenticating. If a TPA uses Basic authentication mechanism, then for the scope of Integry, you will need to provide us with end-user credentials and the URL for communication. For further understanding, let us take an example.
I am reading blogs on my favorite blog site. The site displays me only five articles when I am not logged in. To read more blogs I have to log in. Using the website’s login page, I log in and I am displayed with a list of all blogs on that site.
When I logged in, the browser sent a request along with my username, password, and the URL to the server. The server identified me as a valid user and sent me back the requested data.
Basic Without URL
This works the same as Basic with URL, but the user does not need to enter a custom URL to authenticate. It requires a username and password only for authorization.
Basic With API-Key
In this authorization type, the end-users are directed to the authorization screen that takes end-user credentials, custom authorization URL and value of the API-Key. If a TPA uses Basic with URL, your end-users can provide with the information required and authenticate themselves and Integry.
We hope that we have addressed your queries regarding the authorization types supported in Integry. If you have any query shoot us an email at support@integry.io.
Happy Integrating!