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.
• In case you want to use Authorization Code Flow or Refresh Token Flow, 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

• App Flow. Complete flow is handled by Dataddo, you need to redirect user to the supplied URL. Since Dataddo OAuth 2.0 app is used, the users will be exposed to Dataddo branding.
• 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 or App Flow otherwise.

App Flow

1. Call /services/{serviceName}/oauth-request-url to obtain an URL to redirect the user. Make sure to include redirectUri. This parameter represent the URIs where the user will be redirected back in case of successful or unsuccessful authorization attempt. Such URIs needs to represent your actual application, make sure to contact Dataddo support for whitelisting.
2. Redirect the user to provided URL where the actual authorizarion process is performed.
3. Implement login in your application to intercept the parameters provided, when user is redirected back to your application.

Example Implementation

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. After the authorization process is finished, user is redirected according to the provided redirectUri. Dataddo will add additional parameters to the URI which you can intercept for smooth user expirience:
   1. serviceId. Identifier represending the Dataddo authorizer
   2. serviceName. Indetifier of the service used (e.g. facebook)
   3. error. Provided only if the authorization process fails. Contains the description of the authorization error.

Generating redirect URI

First step is to get URL to redirect the user to perform the authorization. Call API /services/google_analytics4/oauth-request-url to obtain the URL where to redirect the user. The URI can contain any additional query parameters.

POST /services/google_analytics4/oauth-request-url

Content-Type:application/json

{
    "redirectUri":"https://my.app.com/ga4Callback"
}

Redirecting the user to the auth service

Dataddo API will respond with URL to redirect the user. Redirect the user to this URL from your application.

{
    "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%2Fapp.dataddo.com%2settings%2Fservice%2GoogleAnalytics4"
}

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 with .

https://my.app.com/ga4Callback?serviceId=identifier&serviceName=google_analytics4

In case the of an error in the process, the error and errorDescription parameters will be provided in the URL.

https://my.app.com/ga4Callback?serviceId=identifier&serviceName=google_analytics4&error=invalid_scope&errorDescription=missing_scope

Reauthorizing the user

In case you need to perform the re-authorization, you can use the same process as for the authorization, only the serviceId indentifier of the existing authorizer needs to be supplied in the serviceId parameter, when generating the authorization URL. See the example below.

POST /services/google_analytics4/oauth-request-url

Content-Type:application/json

{
    "redirectUri":"https://my.app.com/ga4Callback",
    "serviceId":"serviceId"
}

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_analytics4_custom/oauth-request-url to obtain the URL where to redirect the user.

POST /services/google_analytics4_custom/oauth-request-url

Content-Type:application/json

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

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&state=0x9b58c1fa64804b48acb9dcd3cbf3eace"
}

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 and state params to the URL.

https://my.app.com/GoogleAnalytics4Callback?code=aaaaBBBBccc1234&state=0x9b58c1fa64804b48acb9dcd3cbf3eace

The last remaining thing to do is to call /services/google_analytics4_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_analytics4_custom/oauth-request-url.

POST /services/google_analytics4_custom/oauth-process-callback

Content-Type:application/json

{
    "callbackUrl": "https://my.app.com/GoogleAnalytics4Callback?code=aaaaBBBBccc1234&state=0x9b58c1fa64804b48acb9dcd3cbf3eace"
}

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

{
    "id":"1234",
    ...
}

Reauthorizing the user

In case you need to perform the re-authorization, you can use the same process as for the authorization, only the serviceId indentifier of the existing authorizer needs to be supplied in the serviceId parameter, when generating the authorization URL. See the example below.

POST /services/google_analytics4_custom/oauth-request-url

Content-Type:application/json

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

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

{
    "serviceName":"google_analytics_static",
    "config": {
        "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.

{
    "id":"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.