Zoho Creator - OAuth 2.0 PKCE

Multiuser connector for any OAuth services

View video
MORE

OAuth 2.0 PKCE

This application is the middle layer between your creator app and third party services which require OAuth 2.0 authentication.
App allow you to manage all your OAuth integrations in one place along with multiuser environment and absolutely new flexible API.

LEARN MORE LIVE DEMO

OAuth 2.0 PKCE

key features

  • OAuth Wizard - Wizard From that lead you through the all steps you need to setup OAuth 2.0
  • Multiuser Environment - You can configure separate connection for each of your users or customers and utilise their connections inside your application (for example user dropbox or contact list). 
  • Advance Setup - flexible configuration options in manual mode that allow you to cover most of OAuth 2.0 API and additional parameters
  • PKCE Support - Proof Key for Code Exchange Flow - enhanced Authorization Code Flow required by some modern API and considered as a new OAuth standard.
  • Flexible API - rich set of functions that provide you the method to interact with connector (create service, application connector along with authorization url generation)

Application documentation

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

Official documentation you can find here.


Type of OAuth. 

Generally, there are four types of OAuth 2.0 Authorization flow  - Authorization Code, Authorization Code with PKCE, Implicit grant and Client Credentials (Password flow).

This application covered only two of them - Authorization Code and Authorization Code with PKCE -since only those type of Authorization allow to call API when the user is «offline».

In this application we will use following terminology:


1. Authoriser (authorization server).

Authoriser - the server issuing access tokens to the client. 

The things you have to know before you staring OAuth 2.0 configuration:

- Authorization Endpoint - URI that you have to open in browser to get access code.

- Token Endpoint  - URI which exchange access code with access token

- Refresh Token Endpoint (usually the same as Token Endpoint)

- Type of client authentication - does it need header like Authorization: Basic [client_id:client_secret]

- PKCE -  does it need Code Verifier also known as Proof Key for Code Exchange Flow


2. Application

This is usually the form on authoriser side which contains:

- Name of your app

- Client ID - login generated by authoriser

- Client Secret - password generated by authoriser

- Redirection URL - landing page on client side where authoriser returns result of authorization.

- Scopes - friendly names of resource groups allowed for the application


3. Connection

This is the way how you calling your authoriser for particular user. You can specify the scopes allowed for this user that you want to use in this connection, type of screen that you will show (prompt for login/or select account) and additional parameters required by API.


4. Authorization




Mobirise

Getting authorization code

First step of OAuth dancing is opening authorisation url in the users browser. After that you lost control over user and pass user to authorisation server (often provider).
Second step - Provider ask for user credentials, validate user and return to your application special code that you can use for token generation. This code returned to Redirect Url as a parameter in the browser line.

Exchange code with token

Third step is exchange the code from previous step with access token that you can use for calling API 

See our Terms & Conditions and Privacy policy 

Setting up connection

Advance service configuration

1

Setup Provider

Create new record in the Provider form.
Give unique name to your service and fill Authorization URI, Token URI and Refresh Token URI if different then Token URI
Find out in the API documentation whether your service require Basic Authentication Header for token request.
(SalesForce, QuickBook and RingCentral)
Find out whether your service require PKCE flow - in this case app generate secret passphrase (code_verifier) and add special parameter to authorization url - base64 encoded SHA256 hash of your code_verifier
(Xero, RingCentral, Google)


APi Methods:  get_providers, new_provider

2

Setup Application

Create Application on Authoriser side (usually in developer section).
Use as a Redirect URI: 
https://creatorapp.zoho.com/<admin_username>/<application_link_name>/form-perma/oauth_callback
(substitute admin_username and application_link_name from your account or create new record in application form in app and copy your url from Redirect URL field)
Populate on Zoho Creator side in Application form Application name (should be unique), client_id and client_secret.
NOTE: You can configure different application for same service - for example for google contacts and google drive.

API Methods:  get_applications, new_application

3

Setup Conection

Connection is User specific records. You can create one connection for all users  (corporate account) or you can setup separate connection for each user using the same provider and same application.
In this case using connection id you can get user specific token to access users data.
You can dynamically add users using API methods and authorise them using openUrl statement. Return Url is the endpoint where your user will redirect after success token generation.
NOTE: If you use simplify flow or you have already generated  tokens - you can populate access_code/refresh_token in this form and omit authorization flow.

API Methods:  get_connections, get_connection_info, new_connection

4

Authorization

You can Authorize users manually by clicking «Authorize» button in Connection Report. Application generates authorization url and open this in current browser.


API Methods: get_authorization_url, token, force_refresh_token, get_token_info, get_token_response

5

Fetching your API

In the most of cases all you need to do - attach token into your request in the header like this:

url = "https://people.googleapis.com/v1/people/" + username + "?personFields=addresses,emailAddresses,phoneNumbers,metadata";
response = getUrl(url,{"Authorization":"Bearer " + oauth_connect.token("my-connection-id")});

or

url = "https://people.googleapis.com/v1/people/" + username + ":updateContact?updatePersonFields=addresses,emailAddresses,phoneNumbers,metadata";
info url;
resp = invokeurl
[
    url :url
    type :PATCH
    parameters: request.toString()
    headers:{"Authorization":"Bearer " + oauth_connect.token("my-connection-id"),"Content-Type":"application/json"}
];

You can reach original response from API using get_token_response method.

API Methods

Application generates namespace in your account usually oauth_connect that you can use as a prefix to the listed below functions 

list:map oauth_connect.get_providers()

Returns configured providers as a List:Map()

[
  {
         "provider_id":"Google",
         "authorization_uri":"https://accounts.google.com/o/oauth2/v2/auth",
         "token_uri":"https://oauth2.googleapis.com/token",
         "refresh_token_uri":"",
         "basic_authentication_header":false,
         "pkce":true
  },
  ...
]

list:map oauth_connect.get_applications()

Returns configured application as a List:Map()

[
  {
        "application_id":"zoho-crm",
        "provider_id":"Zoho",
        "redirect_uri":"https://creatorapp.zoho.com/.../.../form-perma/oauth_callback",
        "client_id":"1000.0X...AZN",
        "client_secret":"100...123456"
  },

 ...
]

list:map oauth_connect.get_connections()

Returns connections as a List:Map()

[
  {
      "connection_id":"crm-user",
      "provider_id":"Zoho",
      "application_id":"zoho-crm",
      "flow_type":"Have access_code",
      "access_type":"offline",
      "scopes":[],
      "login":"...@gmail.com",
      "prompt":"none",
      "additional_parameters":"",
      "return_uri":"https://creatorapp.zoho.com/.../.../#Report:Connections"
  },
  ...
]

string oauth_connect.new_provider(Map:params)

Create new provider configured in map variable.
provider_id, authorization_uri and token_uri are mandatory
Sample of deluge code:

// Create Provider - expected parameters like this
/*
{
"provider_id":"Xero",
"authorization_uri":"https://login.xero.com/identity/connect/authorize",
"token_uri":"https://identity.xero.com/connect/token",
"refresh_token_uri":"",
"basic_authentication_header":false,
"pkce":true
}
*/
provider = Map();
provider.put("provider_id","Xero");
provider.put("authorization_uri","https://login.xero.com/identity/connect/authorize");
provider.put("token_uri","https://identity.xero.com/connect/token");
provider.put("basic_authentication_header",false);
provider.put("pkce",true);
provider_id = thisapp.new_provider(provider);

string oauth_connect.new_application(Map:params)

Create new application configured in map variable.
application_id, provider_id, client_id and client_secret are mandatory

Sample of deluge code:
//Create Application - expected parameters like this
/*
{
"application_id":"zoho-connect",
"provider_id":"Xero",
"client_id":"34......7",
"client_secret":""
}
*/
app = Map();
app.put("provider_id","Xero");
app.put("application_id","zoho-connect");
app.put("client_id","3433676B311A47FA8241DE5398F32737");
app.put("client_secret","");
app_id = thisapp.new_application(app);

string oauth_connect.new_connection(Map:params)

Create New connection configured in map variable.
connection_id, provider_id, application_id and login are mandatory.
NOTE: scopes parameter should be a string of scopes separated by comma

//Create Connection - expected parameters like this
/*
{
"connection_id":"xero-userid",
"provider_id":"Xero",
"application_id":"zoho-connect",
"flow_type":"Authorization",
"access_type":"offline",
"scopes":"offline_access,email,profile,openid"
"login":"<user_email>",
"prompt":"none",
"additional_parameters":"",
"return_uri":"https://creatorapp.zoho.com/igorvatsenko11/oauth-connect/#Report:Connections"
}
*/
client = Map();
client.put("provider_id","Xero");
client.put("application_id","zoho-connect");
client.put("connection_id","xero-userid");
client.put("flow_type","Authorization");
client.put("access_type","offline");
client.put("scopes","offline_access,email,profile,openid");
client.put("login","<user_email>");
client_id = thisapp.new_connection(client);

map oauth_connect.get_connection_info(string connection_id)

Return connection configuration with tokens

list oauth_connect.get_scopes(string provider_id)

returns list of the scopes for current provider

string oauth_connect.get_authorization_url(string connection_id)

Returns url that you can open in browser for user authentification. You can configure Return Url to your application or customer portal after token generation.

string oauth_connect.token(string connection_id)

Returns active token for specified connection. (or refresh token if expired)

map oauth_connect.get_token_response(string connection_id)

Get original token response comes from API 

string oauth_connect.force_refresh_token(string connection_id)

Manually refresh token.

Terms & Conditions

THESE TERMS & CONDITIONS are entered between Malthinae, Sole Proprietorship company located in Ukraine, Heorgia Hongadze ave 18, 38, Kiev, Tax ID#2575524253, (the “Company”) and the user of the “Malthinae software” (the “Customer”), together referred to as the “Parties”;

WHEREAS, Company grants Customer a license to use “Malthinae app” (the “Software”, “System”) for the period of time of subscription and on the conditions described in this document and in the Customer’s subscription plan, which is part of the agreement;

NOW, THEREFORE, the Parties hereby agree as follows:

Temporary Usage License. Effective the date of execution of this agreement, the Company grants the Customer the right to use the Software free-of-charge during the trial period and then based on a paid basis on the conditions described in the subscription plan chosen by the Customer.

Price. The Customer shall pay for using the Software in accordance with the conditions of the Customer’s Subscription Plan, provided that Plan requires such payment. Payments are charged from the Customer’s bank card, which the Customer designates for this purpose.

Term. This Agreement, as well as the granted temporary license, shall terminate automatically once the term of the Customer’s Subscription expires. The term shall automatically prolong in accordance with the Subscription Plan, if neither Party expresses desire to cancel the Subscription.

Attorney’s fees. In the event a Party to this Agreement initiates litigation against the other Party, the prevailing Party shall be reimbursed by the other Party for attorneys’ fees and court costs, including any costs of appeal.

WARRANTY WAIVER. CUSTOMER EXPRESSLY ACKNOWLEDGES AND AGREES THAT (I) THE COMPANY DOES NOT WARRANT THAT THE SYSTEM WILL MEET ALL OF CUSTOMER’S NEEDS OR THAT ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE; AND (II) THE COMPANY SHALL NOT HAVE ANY OBLIGATIONS FOR ENSURING OR PERFECTING ITS OPERATION ON OR COMPATIBILITY WITH ANY CURRENT OR FUTURE VERSION OR RELEASE OF ANY HARDWARE, EQUIPMENT OR OPERATING SOFTWARE OR OTHER SOFTWARE PRODUCTS, WHICH CUSTOMER MAY ACQUIRE OR RECEIVE FROM ANY SOURCE, EXCLUDING THE COMPANY.

THERE ARE NO EXPRESS OR IMPLIED WARRANTIES, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, RESPECTING THIS AGREEMENT, THE SYSTEM AND THE SERVICES.

THE CUSTOMER ACKNOWLEDGES THAT THE COMPANY SHALL NOT BE LIABLE FOR ANY COSTS, DAMAGES, EXPENSES, LOST PROFITS THAT MAY RESULT FROM OR RELATED TO WORK PRODUCT OR ITS USAGE BY ANY PARTY, INCLUDING, WITHOUT LIMITATION, ERRORS IN THE DEVELOPED SOFTWARE OR ITS BEHAVIOR.

No SLA. The Company does not guarantee any particular share of time the system will be available for use (uptime). The Company will take reasonable efforts to notify the Customer of forthcoming maintenance but does not guarantee uninterrupted work of the Software at any time.

Indemnity. Each Party shall indemnify, defend, and hold the other Party harmless from and against any and all claims, actions, suits, demands, assessments, or judgments asserted, and any and all losses, liabilities, damages, costs, and expenses (including, without limitation, attorneys fees, accounting fees, and investigation costs to the extent permitted by law) alleged or incurred arising out of or relating to any operations, acts, or omissions of the indemnifying party or any of its employees, agents, and invitees in the exercise of the indemnifying party’s rights or the performance or observance of the indemnifying party’s obligations under this agreement. Prompt notice must be given of any claim, and the party who is providing the indemnification will have control of any defense or settlement.

Entire agreement. This Agreement supersedes all previous agreements between the Parties, both oral and written, except for the Non-Disclosure Agreement, in case if the Parties have signed such an agreement prior to this Agreement.

Cumulative Rights. Any specific right or remedy provided in this contract will not be exclusive but will be cumulative of all other rights and remedies.

Modification of Agreement. No waiver or modification of this Agreement or of any covenant, condition, or limitation herein contained shall be valid unless in writing – including electronic form – and duly executed by both parties.

LIMIT OF LIABILITY. IN NO EVENT SHALL EITHER PARTY BE LIABLE TO THE OTHER OR ANY THIRD PARTY IN CONTRACT, TORT OR OTHERWISE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, INCLUDING, WITHOUT LIMITATION, PUNITIVE OR ECONOMIC DAMAGES OR LOST PROFITS, REGARDLESS OF WHETHER EITHER PARTY SHALL BE ADVISED, SHALL HAVE OTHER REASON TO KNOW OR IN FACT SHALL KNOW OF THE POSSIBILITY.

Severability. If any provision of this agreement shall be declared by any court of competent jurisdiction to be illegal, void, or unenforceable, the other provisions shall not be affected but shall remain in full force and effect. If the non-solicitation provision are found to be unreasonable or invalid, these restrictions shall be enforced to the maximum extent valid and enforceable.

Survival. All provisions that logically ought to survive termination of this agreement shall survive the termination or expiration of this Agreement.

Waiver. Failure of either party to insist on strict compliance with any of the terms, covenants, and conditions of this agreement shall not be deemed a waiver of such terms, covenants, and conditions, or of any similar right or power hereunder at any subsequent time.

Successors and Assigns. This agreement shall be binding on and inure to the benefit of the Parties hereto and their respective heirs, legal or personal representatives, successors, and assigns.

Privacy Policy

Malthinae (the “Company”) provides the following information relating to your privacy. In general you can use our website without telling us who you are or revealing information about yourself.

The Company website and widgets that collect data of any type are required to abide by and provide a link to our Privacy Policy.

Our Information Collection and Use Practices

Your information may be collected by the Company for internal marketing and development purposes. The Company will not sell any personal information to third parties for purposes of marketing, advertising, or promotion. The Company does, however, use Google Analytics as described later in this policy.

Company Widget

The Company uses various methods to collect information, including information that you provide, cookies, web beacons, Google Analytics, referrers, IP addresses, and system information.

Personal Information

The Company website may collect personally identifiable information, including your name and contact information (email, address, telephone number), and other identifiers to contact you directly.

Forms and Transactions

The Company website may use online data entry forms to collect personal information from web visitors who choose to identify themselves for the purpose of transacting e-commerce or receiving products, services, or information.

Some websites covered by this policy may request personal information from you in order to complete a form or transaction. Your information, including personal information, may be shared with third parties, such as event registration systems, to complete your transaction.

Website Analytics

The Company uses website analytics tools to retrieve information from your browser, such as the site you came from, the search engine(s) and keywords you used to find our site, and the pages you view within our site.

Cookies, Web Beacons, and Google Analytics

We use technologies such as cookies, web beacons, and Google Analytics, to collect information about your age and gender, the pages you view, the links you click, and other actions you take on our website and to advertise on other websites. See below for a detailed description of these technologies.

IP Address and Browser Information

We collect certain standard information that your browser sends to every website you visit such as your IP address, browser type and language, access times, and referring website addresses.

When you visit the Company website we gather and store this information to allow us to evaluate the use of our website and make improvements. This information is stored and used in the aggregate only and is not used to obtain personal data or to contact you personally.

Cookies and Web Beacons

Cookies

We use cookies, small snippets of data sent to your computer, to track usage patterns, traffic trends, visitor behavior, demographics, visitor interests, and for remarketing. First Party Cookies are set through this website directly, including the Google Analytics cookie. Third Party Cookies are set by third parties, also through this website. Most web browsers automatically accept cookies. Choosing to accept cookies enables some online services to work more efficiently or makes the use of those services more convenient. You may set your browser to refuse cookies from any website that you visit. If you set your browser to refuse cookies, you may be unable to fully use certain portions of the website.

Web Beacons

We may utilize web beacons, also known as clear GIFS, from third parties to help us compile aggregated statistics regarding the effectiveness of our site. Web beacons are used in combination with cookies to help understand how visitors interact with our site. We may include web beacons in promotional email messages or our newsletters in order to determine whether messages have been opened and acted upon. We prohibit web beacons on our website from being used by third parties to collect or access personal information.


Referrers

A referrer is the information passed along by a web browser that references the web URL you linked from. Our web server automatically gathers this information.

IP Addresses

Web servers use your IP address to identify your computer so that data, such as the web pages you request, can be sent to you. Our web server automatically gathers them.

System Information

System information includes time, type of browser being used, the operating system or platform, and CPU speed. Your web browser sends this information automatically when you are connected to a website. This information is used by the Company to identify broad demographic statistics and may be used to provide information appropriate for your computer system. The Company will not use this information to attempt to identify your personal information.

Security

While no system can provide guaranteed security, we take reasonable efforts to keep information you provide to us secure. We implement safeguards including encryption technology and physical security at the location of the server where information is stored.

Do Not Track

the Company does not track visitors over time and across third party websites to provide targeted advertising and therefore does not respond to “do not track” signals. Third party signals such as Google Analytics use cookies to collect information that is not considered personally identifiable and is not combined with information that is personally identifiable.

Links to Other Sites

The Company website includes hyperlinks to sites maintained or controlled by others. The Company is not responsible for and does not routinely screen, approve, review, or endorse the contents of or use of any of the products or services that may be offered at this or any other website. We advise you to review the individual privacy policies of the respective sites.

Updates to Privacy Policy

The Company reserves the right to modify this privacy policy at any time. We encourage visitors to frequently check this page for any changes to its Privacy Policy. Your continued use of this site after any change in this Privacy Policy will constitute your acceptance of such change.


If you have questions about our Privacy Policy, we would like to hear from you.
Last revised on: Feb 24, 2021

Designed with Mobirise ‌

Free Web Site Design Software