Configuring OAuth 2.0 for TDV Advanced Adapters
If your Advanced Data Source Adapters will make use of OAuth authentication, then there is extra configuration that you must perform. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service for:
• A resource owner by authorizing the resource owner and the HTTP service
• A third-party application to manage authorization separately
This section includes:
OAuth Options Provided by TDV Advanced Adapters
TDV provides the following OAuth options:
Initiate OAuth field options | Description |
GETANDREFRESH | Typically, this option can be established quickly by most users. The Get and Refresh option uses the client id and client secret to initiate the OAuth as described in the OAuth 2 RFC and requires interaction between client, resource owner, and the Authorization and Resource Servers. A browser must be launched on the local machine to enable the granting of permissions. The OAuth settings file must point to a location on the TDV Server machine. Required field: Client Id, Client Secret, OAuth Settings file Location |
OFF | This configuration uses an OAuth Access Token to authorize to the back end; it doesn’t initiate any OAuth flow. The OAuth access token needs to be provided as part of configuration. This method is recommended if the access token is already obtained using other means. Most OAuth providers have a way to generate access tokens, with the help of developer consoles or APIs. Access tokens do expire and it is your responsibility to provide a new access token, when the previous one expires. This makes it suitable for one time use or when the access tokens have long life. Required Field: OAuth Access Token |
REFRESH | This option refreshes the access token using a refresh token, client id, and client secret, when the current access token is expired and the refresh is transparent to the user. It stores the new access token in the OAuth settings file. Typically, users do not need to enter anything. This option is best where the Studio and the TDV Server cannot be run on the same machine. It does require that a refresh token be obtained out side of TDV using OAuth provider tools. Required fields: OAuth Refresh Token, Client Id, Client Secret, OAuth Settings file Location |
Preparing Eloqua for OAuth Access through TDV
The Eloqua data source adapter does not permit the use of the loopback address "localhost" or "127.0.0.1" in the callback URL. To use Eloqua with TDV and OAuth, you must configure your system resolver to resolve the new hostname you choose for this purpose to the loopback address 127.0.0.1, and use that new hostname in the callback URL. You must also identify an unused port.
To prepare Eloqua for OAuth access
1. On your TDV Server host, add a new hosts file entry that maps the loopback address 127.0.0.1 to a fully qualified hostname not actually used on your network, such as "eloqualoopback.mycisserver.com."
For example, on Windows add the following entry to your c:\windows\system32\drivers\etc\hosts file:
127.0.0.1 eloqualoopback.mycisserver.com # the fully qualified hostname for the Eloqua Callback URL
2. Choose an available port on the host running TDV for use in the Callback URL. For example: 12481.
3. Log into Eloqua and configure your app's AppCloud Developer Settings to reference that hostname and port in the Callback URL. For example:
https://eloqualoopback.mycisserver.com:12481/
The https protocol is required.
Configuring GETANDREFRESH OAuth access for Advanced Data Source Adapters
The GETANDREFRESH option is the most typical configuration method for configuring OAuth access for your TDV Advanced Data Source adapters.
To configure GETANDREFRESH OAuth access for Advanced Data Source Adapters
1. Start the TDV from the UNIX or Windows command line.
2. Start Studio on the machine where you are running the TDV Server.
3. Add a new data source for one of your Advanced Data Source Adapters.
4. Provide a unique name for your data source.
5. On the Basic tab, type your company name (or account identifier).
6. On the Advanced tab, enter values for the following fields:
Field | Description of Value |
Initiate OAuth | Typically, et this to GETANDREFRESH. Or a refresh token can be obtained from the OAuth provider and provided along with the client id and client secret. Getting a Refresh token requires experience in using the developer APIs and console of the OAuth provider. Also, the token has to be obtained using the same client id and client secret that is configured in the data source. |
OAuth Client Id App ID | Set this to the client Id (app Id) of your data source. |
OAuth Client Secret App Secret | Set this to the client secret of your data source. |
Other | Set this to the value of your data sources callback URL. For Eloqua, obtaining the callback URL requires some extra steps. https://eloqualoopback.mycisserver.com:12481/ |
After the initial authentication is run and the tokens have been obtained, they are written into the configured OAuth settings file.
7. Save your new data source.
8. From the Studio resource tree, open the data source that you just added, and select Test Connection. Or introspect the data source.
The adapter opens the OAuth endpoint in your system default browser.
9. Using the browser, log in and grant TDV permission to the adapter application.
For example, Eloqua calls your specified callback URL, appending the access token and other needed values, such as:
https://eloqualoopback.mycisserver.com:12481/callback#access_token=2YotnFZFEjr1zCsicMWpAA&token_type=bearer&expires_in=86400&state=xyz
10. If or when the authentication certificates expire, you must perform this procedure again to allow TDV permission to the data in the data source.
Replicating your OAuth Configuration on Other Machines
After initial testing and development work with your Advanced Data Source Adapters within TDV and Studio, it is typical that authorization settings will need to be migrated or replicated on other machines within your TDV environment. You can do this using CAR files and by migrating the OAuth settings file.
Occasionally, your usage focus might also require the replication of the authorization settings. Some of these usage focuses include:
Usage Focus | Description |
Importing/Exporting Archives and Deployment Manager | When the archive contains a data source configured for OAuth and when it is imported or migrated to the target server, the OAuth settings file is not automatically imported or migrated. OAuth settings file needs to be externally migrated or the OAuth flow has to be reinitiated in the target server. |
Clustered Environment | In a cluster, data source configuration is synced across the members of the cluster. For OAuth providers, who allow multiple valid tokens, configure OAuth settings location to be same path. If that is not possible, provide a path on the shared file system, which is accessible to all the members. Shared file system path is needed in case, where the OAuth provider does not support multiple valid tokens. |
To replicate your OAuth configuration on Other Machines
1. From the Studio resource tree open the data source for which you want to replicate OAuth configuration.
2. On the Advanced tab, locate and save the value of the following field:
OAuth Settings Location | The value of this field is the location where the adapter writes the authentication information. If working in a clustered environment, make sure this location is central to all the nodes of the cluster, or replicate the OAuth settings file to each cluster |
3. Create a CAR file export of the data source for which you want to replicate OAuth configuration.
4. Copy the OAuth settings file and the CAR file to the new host machine.
5. Copy the settings file to the same directory location as was specified in the OAuth Settings Location for the data source that you are replicating.
Doing this allows a data source imported from the source to be used in target without modifications.
6. Use Studio on the new host machine to import the CAR file of the data source you are migrating.
7. Test the connection of the data source. If necessary resolve any issues.