Hello there, thank you for visiting us. It is always a delight to help and guide you. This article tells you about the user authorizations supported by Integry. This is the engineering guide and covers technical aspects of integrating with Integry.
We support the most popular authentication mechanisms used by applications around the world and this article will give a high level overview about them. Following are the authorization types we are supporting, to learn how to add them in your app click the authorization type
- OAuth 1.0
- OAuth 2.0
- API-Key with URL
- API-Key with Secret
- Basic with URL
- Basic without URL
- Basic with API-Key
OAuth 1.0 and OAuth 2.0 come under the umbrella of OAuth. It is a framework that delegates limited access to a third party application to user data and other services. Both OAuth 1.0 and OAuth 2.0 uses the same principles for authentication. However, their flows differ from each other.
OAuth is the highly recommended authentication type being used these days. It is secure and does not share any sensitive information of user or third party app while authenticating. It notifies a resource server that the resource owner (user) is granting permission to a third-party app to access their account information. The resource server is assured of user’s identity through a third-party app, this is called Three Legged Communication.
OAuth 1.0 is one of the popular authentication types being used by a number of applications. To study the flow step by step, let us consider an example.
I am a developer, writing a personal finance application. The user can connect to their bank and view account details using this app. The application uses OAuth 1.0 to connect to external server to authorize its users.
The user requested to view the transaction history. Once the request was made, the app sent it to the bank (API) for an access token. It consists of app key and other app metadata. The request is verified at the other end. As a response, a Request Token and a Request Token Secret is sent back to the app.
As a next step, the user is redirected to Bank Authorization Screen, the user is prompted to login and grant permission to app.
Once the permission is granted, bank generates an Access Token along with an Access Token Secret. The Access Token allows the app to retrieve user’s protected account information. The app exchanges the Request Token for Access Token. Once the app gets valid Access Token, it can request bank to access user information. So the user is displayed the transaction history.
A few concepts about OAuth 1.0 that can come in handy
Signing Request: The app and server (API) have pre-established shared information in the form of app secret which is used to validate the app request. This is important to ensure that the app is not spoofed. This secret information needs to be kept safe. For public apps the signature method OAuth supports is HMAC-SHA1. For more information about signature methods, visit More on Signing Request
OAuth 2.0 is an entire rewrite of OAuth 1.0. It is one of the most popular authentication mechanisms. For the detailed workflow, let us consider the example above again.
A few points to be kept in mind
User / Resource Owner: The user who wants to view the transaction history
Third Party Application (Client): The application that will connect to external server for 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 user authorization and access delegation
Resource server: The protected data that user/third party app wants to access
Once the user selects to view transaction history of their bank, an “Authorization Request” is sent to the bank authorization server by the app.
The user is displayed a Bank Authorization Screen where the user is requested to authorize the app with their account. The 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 an Access Token. This request is sent to the authorization server. Once the bank receives request an access token is granted and sent back to the app specifically for that user.
The app sends access token to the bank resource server to retrieve data for which permission was granted at the start. The bank identifies the token as valid and sends back data requested by the user to the app.
The access tokens that are granted to the app are short-lived, unlike in OAuth 1.0 where the access tokens are long-lived. Once they expire they can be renewed using Refresh Tokens.
Refresh Tokens are long-lived tokens and used to re generate access tokens once they are expired. For more information about Refresh Tokens, visit More on Refresh Tokens
For all of this to work, the app has to be registered with the bank (API). This is independent of any user involvement and the app needs to provide the following information to the service it is registering with
Well app’s name and website is pretty obvious whereas, Callback URL is the URL where the bank (API) will redirect the user after they have authorized their account.
If your app uses API-key for authentication, this is the auth type you want to use. It is renowned for its simplicity, as a user signs into service, get their API key, and copy 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 user in an app and perform API request on behalf of that user. For the scope of Integry, once you select API-key Integry will consume your API-key for future communication. Let us see how it works
I was working on Acme hotel and restaurant application (HotelApp), that connected to a food delivery service (API) to manage hotel’s delivery orders. For this to work, I got my API-key from the food delivery service (FoodApp) as a first step.
When a user places an order, the HotelApp sends a request to the FoodApp along with API key. Once the API key was identified as valid, the requested data is retrieved.
API-keys are not a very highly recommended auth type due to security loopholes. As the client, gets hold of the key it has to kept safe as a password, because if an unauthorized user gets hold of it may be dangerous.
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, it’s 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 user entered URL. Every application is associated with a URL, here the user specifies the URL in most of the scenarios.
JSON Web Token (JWT)
JWT works with tokens. The main idea behind using JWTs is to verify that data was actually sent by an authentication server. It contains encrypted user data in the signed payload so that it can be used in subsequent API calls without querying data again and again. JWT's can also be set to expire after which client will need to get another token from server. If you have such needs where you have a server that can publish JWT's, want to cache user data in token and want the ability to expire tokens after sometime, you can go with using it.The token consists of a header, a payload and a signature.. JWT involves three entities, which are the
User: The client who wants to access an API service or retrieve data
Authentication Server : The server that authenticates the user against a set of credentials
Application Server: The server which processes the request of the user
Let us take a simple example
A user signs into Facebook using their username and password. The authentication server authenticates the user and grants him a JWT. The user then sends request to the application server along with the JWT.
The application server is configured such that it identifies JWT as valid. So when a user sends a request along with the JWT, the application server processes user request.
JWTs are a common authentication mechanism observed in a number of applications these days. They are simple and easy. To study JWTs in more detail, please visit More on JWT
Basic with URL
As the name suggests this mechanism uses basic technique to authenticate users. A 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 users to provide their actual username and password along with a custom URL. If your app uses Basic authentication mechanism, then for the scope of Integry you will need to provide us with 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 login. Using the website’s login page, I login 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.
We hope that we have addressed your queries regarding the authorization type you want to use. If you have any query shoot us an email at firstname.lastname@example.org