To learn about the details of OAuth2 authorization and the mechanism behind we refer to The OAuth Bible which we highly recommend. The exaplanation below is based on that extensive document customised to the case of this iPaaS.
Please note: Every OAuth2 API provider has its own specific requirements. Make sure to check the documentation of the service before assuming anything and building the OAuth2 routines in your private component.
- Establishing the initial connections
- Redirecting the User to Service
- User authenticates
- Application asks for an access
- Refreshing the token
Establishing the initial connections
The purpose of any basic integration scenario is to communicate the data between the systems. In order to prevent any third party from getting access to this data, 2 communicating systems need to talk securely. This is done by establishing a secure connection via OAuth where the data is communicated to and between known parties.
Within the scope of the platform the known parties are:
User - This is the individual (perhaps you) which holds the ultimate rights to the data. This data is protected by the
credentialswhich are unique to this individual, the user.
- Service - This is the external resource where the protected data is hosted. For example Salesforce, Google, SAP, etc.
- Application - This is the program which is going to access the external data on behalf of the user. In our case, it is the iPaaS.
Before the platform (the Application) would be given access to the protected data it needs to be ready to receive greetings and then would need to be introduced to that party (the Service). Here are the necessary steps:
- At the Application, we need to configure the OAuth Callback URL to receive the greetings. We have an example of how to configure the OAuth Callback redirect URL. This is the URL where the Service is going to send the Authentication confirmation.
- The Application needs to be registered with the Service as a reliable party. This is done by creating an OAuth App at the Service like it is explained in the case of Creating OAuth App for Salesforce.
At this stage, no data belonging to any User is being exchanged. The systems are just getting to know each other. This stage is usually done once per each external Service. What we get from this stage are specific values for
client_secret. These values are used afterwards by Application to get an access to the Service to authenticate the User credentials.
Redirecting the User to Service
At this stage the User is being redirected to the Service by Application using the following information:
client_id- this is a unique identification of Application.
client_secret- this is also provided by the Application.
auth_uri- this is the URL which the Application is going to use to get the User authenticated.
token_uri- the is the URL which is going to be used by Application to request the
scopes- Optional, this is usually to indicate what is the given scope of access.
Some OAuth API providers support more parameters which can be sent with this redirect. What additional parameters and how they are sent could be different from OAuth API provider to provider. This is the reason we recommend to consult the documentation for each API provider to customise this procedure accordingly.
This is the moment when the User gives his/her explicit consent to Application so that it can access the protected data stored at Service provider on his/her behalf.
For example in the case of Google Spreadsheets component User would need to just start the process of verification like this:
This would send the special request to Google with all the necessary information already encoded in the request. If the User is already logged into the Google then a screen like this would be presented:
In some other cases the User might need to log-in to the system and authorise:
Some Service providers might require a slightly different sequence of events but the whole procedure is quite similar.
In the end, the Service is redirecting our User back to the Application using the specific OAuth Callback URL with a specific
code will be used by the Application for further negotiation.
Please note that if everything is done properly this would be the last instance where the User would need to manually interfere to authorise the Application to act on behalf of him/her to access the protected data at Service provider.
Application asks for an access
From this point on the Application and Service are negotiating the connection terms and establishing the rules.
code which was given the User after giving an explicit access to the Application is taken and included in the next call to the Service by Application to acquire an
This time Application sends the request to the
token_uri. Here is what this request includes:
client_id- the same unique ID for this Application
client_secret- the same secret for this Application.
code- this is exactly the
codethat User was given earlier.
redirect_uri- this is the same OAuth Callback URL for the Application to receive the response from the Service.
"authorization_code"- this values is required in order the procedure to go further.
After receiving the above information Service checks the validity of
client_secret together with the
code and issues a call to
redirect_uri containing the
access_token- this token is going to be used by the Application to request the secured data on Service side.
expires_in- this is the time until which the
refresh_token- this is the token which is going to be used by the Application to request for a new
access_tokenwhen it gets expired after
Refreshing the tokens
In most of the cases
access_token has some specific timespan (determined by
expires_in) during which it is valid. When this time passes Service responds with 401 UNAUTHORIZED error. Upon encountering this error Application must initiate the procedure of refreshing the
access_token using the earlier given
When Application receives the access error it initiates a call to
token_uri with the following content:
"refresh_token"- this is a required parameter and must be passed in order for the call to be accepted.
scope- this is an optional parameter which can be included if it is required, however, it should not have a different value from the ones earlier defined during the initial establishment.
What follows is similar in nature. Service validates the supplied parameters and issues a call including:
access_token- this is the new one.
issued_at- this is the timestamp of the
access_tokenissue which together with
expires_inparameter can be used to initiate an automatic refreshing of tokens if needed.
refresh_token- some OAuth API providers might issue a new
refresh_tokenduring this procedure. It is the responsibility of the developer to encounter for this.
After the tokens are refreshed Application can resume accessing the protected data stored at Service side.