OAuth 2.0 Services

OAuth 2.0 is a widely-used protocol for granting third-party applications access to a user's data without sharing their login credentials. An OAuth 2.0 authorizer is a specific type of authorizer that uses this protocol to authenticate a user's connection to a data source.

In the context of Dataddo, OAuth 2.0 authorizers are commonly used to connect to social media platforms, such as Facebook or Twitter, or advertising networks, such as Google Ads or Facebook Ads. When you create an OAuth 2.0 authorizer in Dataddo, you are granting permission for Dataddo to access your data on your behalf without sharing your login credentials.

OAuth 2.0 authorizers typically involve several steps, including registering your application with the data source, obtaining an access token, and refreshing the token as needed. However, once you have set up an OAuth 2.0 authorizer in Dataddo, you can automate the connection process and ensure that your data remains secure.

Prerequisites

• You have the link to API endpoint documentation.
• You have already setup your OAuth 2.0 app on the application provider side (e.g. using Google Developer Console for Google Analytics, Ads, Local Services etc.)

Supported OAuth 2.0 flows

• Authorization Code Flow. Obtaining Request tokens is handled by Dataddo. Typically you will provide Dataddo via Client ID, Client Secret and Redirect URI of your OAuth 2.0 app.
• Refresh Token Flow. You have already obtained refresh tokens outside Dataddo. In this case, you will typically provide the Refresh Token, Client ID and Client Secret of your OAuth 2.0 app.

Which OAuth 2.0 flow to use?

The key fact to consider is whether you are able to obtain Refresh Token from the user outside Dataddo (e.g. whether you have already implemented OAuth 2.0 user flow in your existing app). If yes, use Refresh Token Flow. Use Authorization Code Flow otherwise.

Authorization Code Flow

OAuth 2.0 authorizers require the following flow:

1. Call /services/{serviceName}/oauth-request-url to obtain an URL to redirect the user.
2. Redirect the user to provided URL where the actual authorizarion process is performed.
3. Handle the call callback. After the authorization is performed by the user, capture the URL to which user is redirected back (it contains vital params in the URL) and send it to /services/{serviceName}/oauth-process-callback. If successful Dataddo API will respond with HTTP ok code and idenfier of the newly created authorizer.

Example Implementation

This example assumes using Google Analytics authorizer. Implementation of other OAuth 2.0 services is analogical. Notice using authorizer ID (in this case google_analytics_custom) in both URL as a serviceId parameter in the JSON payload. Check Authorizer naming section for more details.

Generating redirect URI

First step is to get URL to redirect the user to perform the authorization. Call API /services/google_analytics_custom/oauth-request-url to obtain the URL where to redirect the user.

POST /services/google_analytics_custom/oauth-request-url

Content-Type:application/json

{
    "config": {
        "clientId":"YOUR_APP_CLIENT_ID",
        "clientSecret":"YOUR_APP_CLIENT_TOKEN",
        "redirectUri":"https://my.app.com/GoogleAnalyticsCallback",
        "serviceId":"google_analytics_custom"
    }
}

Redirecting the user to the auth service

Dataddo API will respond with URL to redirect the user. Notice the parameter redirectUri, this represent a URL of your app where the user will be redirected back after the authorization is complete.

{
    "url": "https://accounts.google.com/o/oauth2/auth??client_id=YOUR_APP_CLIENT_ID&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&userAgent=Dataddo&response_type=code&prompt=consent&access_type=offline&redirect_uri=https%3A%2F%2Fmy.app.com%2FGoogleAnalyticsCallback"
}

Handling the callback

After the user completes the authorization he will be redirect back to your application. The URL will be constructed according to the redirectUri parameter that you provided in previous call and typically with add code param to the URL.

https://my.app.com/GoogleAnalyticsCallback?code=aaaaBBBBccc1234

The last remaining thing to do is to call /services/google_analytics_custom/oauth-process-callback API endpoint with full URL user has been redirect to back together with the same config parameters as used in /services/google_analytics_custom/oauth-request-url.

POST /services/google_analytics_custom/oauth-process-callback

Content-Type:application/json

{
    "callbackUrl": "https://my.app.com/GoogleAnalyticsCallback?code=aaaaBBBBccc1234",
    "config": {
        "clientId":"YOUR_APP_CLIENT_ID",
        "clientSecret":"YOUR_APP_CLIENT_TOKEN",
        "redirectUri":"https://my.app.com/GoogleAnalyticsCallback",
        "serviceId":"google_analytics_custom"
    }
}

If everything successful the Dataddo API will respond with new authorized service identifier that can be used in the connector configuration.

{
    "oAuthId":"1234"
}

Refresh Token Flow

Example implementation

This example assumes using Google Analytics authorizer. Implementation of other OAuth 2.0 services is analogical. Notice using authorizer ID (in this case google_analytics_static) in both URL as a serviceId parameter in the JSON payload. Check Authorizer naming section for more details.

Since you already have an access to the refresh tokens, no flow requiring the redirection of the users is needed. Simply send the label, Refresh Token (as staticKey param), Client ID (as clientId param), Client Secret (as clientSecret param) you used to obtain the refresh token to /services endpoint.

POST /services/google_analytics_static

Content-Type:application/json

{
    "service":"google_analytics_static",
    "data": {
        "label":"ANY_VALUE",
        "clientId":"YOUR_APP_CLIENT_ID",
        "clientSecret":"YOUR_APP_CLIENT_TOKEN",
        "staticKey":"REFRESH_TOKEN"
    }
}

If everything successful the Dataddo API will respond with new authorized service identifier that can be used in the connector configuration.

{
    "oAuthId":"1234"
}

Authorizers naming

Naming of the authorizers follows the convention when those allowing authorization code flow have _custom (e.g. google_analytics_custom) suffix and those allowing refresh token flow _static suffix (e.g. google_analytics_static). Check the table below for examples.

To get complete list of authorizers, call /public-data/services endpoint.