Data Virtualization Tutorial… OAuth Example using Google Sheets Hello, and welcome to the Demoette series for Cisco Information Server, or CIS. Demoettes are brief instructional videos that demonstrate specific features of CIS. In this Demoette, we discuss using Oauth with CIS. The information in this presentation applies to all Oauth data sources, but we will use Google Sheets as our example.

Agenda What is it and why does it matter? A basic demo Summary Here is our agenda. We begin by defining Oauth and outlining its importance for our customers. Next we walk through a very basic demo of using Oauth to access a Google Sheets data source. Finally, we summarize the contents of this demoette.

Agenda What is it and why does it matter? A basic demo Summary Let’s begin by discussing what Oauth is, and why it is important for our customers.

What is it? OAuth Open standard for Authorization Enables a user to give secure delegated access to user-owned resources Used by many cloud services, including Microsoft, Google, Facebook, and Twitter Oauth is an open Authorization standard that specifies a set of REST-based interactions that enable a user to give secure delegated access to user-owned resources. Oauth is used by many cloud-based services, including those provided by Microsoft, Google, Facebook, Twitter, and many others.

Why does it matter? OAuth Used by many CIS adapters, including: REST Adapter Bundle for Social Media Adapter Bundle for NoSQL and Cloud DB’s Adapter Bundle for Marketing Automation Adapter Bundle for Collaboration Oauth is important to our customers because it is either a required or optional protocol for many CIS adapters, including the REST adapter, and many of our adapter bundles.

Agenda What is it and why does it matter? A basic demo Summary Next, let’s walk through a very basic demo of Oauth with Google Sheets.

Demo: Here is the business problem… Here is the business problem that we illustrate in this demo. We have a Google Sheets data source, and we want to bring it into the Cisco Information Server so it can be federated with other enterprise data sources and published for data consumers. The Google Sheets API requires the use of Oauth. <CLICK> In this demoette, we’ll give examples of all three Oauth initiation styles supported by CIS: OFF, REFRESH, and GETANDREFRESH. OFF REFRESH GETANDREFRESH

Before you begin Google Account Create a Google Sheet This demo focuses on using Oauth in CIS. It is NOT meant to be a general-purpose introduction to Oauth. In addition, this demoette focuses on the Oauth aspect of the Google Sheets adapter. It does NOT provide a complete look at the adapter’s capabilities. To run this demo, you will need a Google account. You will also need to create a simple Google Sheet for CIS to introspect.

Demo: OAuth Initiate OFF We’ll begin by using the simplest Oauth initiation mode, which CIS calls OFF. In this mode, we only need to supply CIS with an Authorization token. However, we’ll take a look at how to use the Google Cloud Console to do some basic setup that we’ll need for all of the Oauth initiation modes. To begin, point a browser at the Google Cloud console. <CLICK> Drop down the project list, and select Create a Project. <CLICK> Give the project a name and click Create.

Demo: OAuth Initiate OFF Type Sheet to find the Google Sheets API… <CLICK> … and click Enable. <CLICK> Then click Go to Credentials.

Demo: OAuth Initiate OFF On the Credentials page, under “Where will you be calling the API from?” select Other UI. <CLICK> Under “What data will you be accessing?” select User Data. <CLICK> Click “What credentials do I need?” <CLICK> Now enter a name and click Create Client ID.

Demo: OAuth Initiate OFF Now make sure the email address is correct, and create a product name for display. <CLICK> Click Continue. <CLICK> Google creates a Client ID and Client Secret. You can click Download to download a JSON file containing this information. We don’t need the Client ID and Secret for CIS in this mode, but we have now created a context for getting an authorization token.

Demo: OAuth Initiate OFF Now go to Google’s Oauth playground, at the URL shown here. <CLICK> Open and select the Spreadsheets V3 API. Note that Google has released version 4 of the Sheets API, but the CIS adapter requires version 3 as of CIS 7.0.3. <CLICK> Click Authorize APIs. <CLICK> Google requests offline access. Click Allow.

Demo: OAuth Initiate OFF Google presents an Authorization Code. <CLICK> Click Exchange authorization code for tokens. <CLICK> Copy the access token. This is what we need for the CIS adapter. <CLICK> Note that this token will expire in about an hour. That’s important to understand for CIS’s Initiate OFF mode, as we’ll see in a moment.

Demo: OAuth Initiate OFF Now we can create the adapter in CIS Studio. In this example, we are running Studio and Server on different machines. For Oauth Initiate Mode of OFF, the behavior is identical regardless of whether Studio and Server are on the same machine or not. This distinction will become important when we look at the GETANDREFRESH mode later in the demo. To begin, Select Google Sheets as the new adapter.

Demo: OAuth Initiate OFF On the Basic tab, paste in the access token… <CLICK> … and enter the name of the spreadsheet you want to introspect. Note that the data source can only introspect one spreadsheet, although the spreadsheet can have many tabs and each will be introspected.

Demo: OAuth Initiate OFF On the Advanced tab, note that the default setting for Initiate Oauth is OFF. This is the setting we will be using in this first example.

Demo: OAuth Initiate OFF Here is the list of introspectable resources. Most of them are procedures that let us do CRUD operations or Oauth operations. Spreadsheet tabs appear as tables. <CLICK> This is my sample spreadsheet, which contains only one tab. <CLICK> There is also a Spreadsheets table, which contains metadata for all the spreadsheets available to me in my Google Sheets account.

Demo: OAuth Initiate OFF After introspection, I can open my spreadsheet in CIS and work with it like any other data source.

Demo: OAuth Initiate OFF However, Google sets my token to expire after one hour, and with our Oauth initiation mode set to OFF, we have no way to refresh the token. Although CIS’s Oauth Initiate mode of OFF is easy to set up, it is only practical for services that provide tokens with very long lifetimes. Next, let’s look at how we can tell CIS to automatically refresh access tokens.

Demo: OAuth Initiate REFRESH Let’s try REFRESH mode, which will automatically refresh expired tokens. Just as before, we’ll begin at the Google Cloud Console. <CLICK> We’ll create a new project, just to keep our work separate. <CLICK> Name the project… <CLICK> … and click to enable APIs.

Demo: OAuth Initiate REFRESH Find the Google Sheets API… <CLICK> … enable it… <CLICK> … and go to Credentials.

Demo: OAuth Initiate REFRESH In the previous example, we selected Other as the calling application. This time, select Web browser.

Demo: OAuth Initiate REFRESH Because we selected Web Browser, our credentials page now presents a field called Authorized Redirect URIs. Enter the url for Google Oauth Developer’s Playground, as shown here. This gives us a mechanism for authorizing issuance of Refresh tokens. <CLICK> Click Create Client ID. <CLICK> Now verify your email address and enter a Product name you want to show users. <CLICK> Download your credentials to obtain the Client ID and Client Secret.

Demo: OAuth Initiate REFRESH Now go to the Google Developer’s Playground, and drop down the Settings. <CLICK> Click “Use your own Oauth credentials” and enter your Client ID and Client Secret. <CLICK> Authorize the Spreadsheets V3 API… <CLICK> … allow it… <CLICK> Click “Exchange authorization code for tokens…” <CLICK> … and copy the resulting Refresh token, which we will use in CIS. We don’t need the Access token, because we’ll be using the Client ID and Client Secret instead.

Demo: OAuth Initiate REFRESH Now create a new Google Sheets data source in Studio. On the Basic tab, enter the spreadsheet name, but leave the Access Token field blank.

Demo: OAuth Initiate REFRESH On the Advanced tab, select REFRESH as the Initiate Oauth mode. <CLICK> Enter the Client ID and Client Secret that you downloaded earlier. <CLICK> Enter the Refresh token. <CLICK> Note the Oauth Settings location. CIS stores the access information in a text file. I like to customize the location, as shown here. The default path for this field uses an Environment Variable called APPDATA, which resolves to the current user’s Roaming Directory. This can provide flexibility for migration, but might also be a point of confusion. In addition, note that this file is stored on the CIS Server machine. In this example, we had Studio and Server on different machines, in order to verify that the Settings file is written on the Server machine.

Demo: OAuth Initiate REFRESH Now you can introspect and work with the data, just as we did before. The difference with REFRESH mode, though, is that when access expires, CIS will automatically refresh its token. This action is transparent to users.

Demo: OAuth Initiate GETANDREFRESH Finally, let’s try GETANDREFRESH mode. This mode provides security advantages, because we only need to provide a Client ID and Client Secret. We do not directly manipulate Access or Refresh Tokens. In addition, human interaction is required to authorize initial access. However, GETANDREFRESH does add some complexity to the process of data source creation, for two reasons. First, we must create the data source with Studio and Server running on the same machine. We can do this in a development environment, and then migrate to production, but we must begin the process on a single machine. Second, we must run CIS Server without Monitor, because Monitor will not permit the human interaction we need for the authorization process. To do this, Stop the CIS Server service, but leave the Repository and Cache services running. <CLICK> Now go to the CIS Home’s bin directory, and run composite_server.bat with the run parameter, as shown here.

Demo: OAuth Initiate GETANDREFRESH Go to the Google Cloud Console, and click Enable and Manage APIs. <CLICK> On the Credentials tab, drop down Create Credentials and select Oauth Client ID. <CLICK> Select Application Type of Other, Name the credential, and click Create. <CLICK> A Client ID and Client Secret are returned.

Demo: OAuth Initiate GETANDREFRESH Now create the data source in Studio. On the Basic tab, name the spreadsheet, and leave the Access Token blank.

Demo: OAuth Initiate GETANDREFRESH On the Advanced tab, set the initiation mode to GETANDREFRESH. <CLICK> Enter the Client ID and Client Secret. Note that we do not enter a Refresh token. <CLICK> Again, I like to customize the settings file location. This can be especially useful with GETANDREFRESH. As noted earlier, the default path uses the APPDATA environment variable. Keep in mind that we are now running CIS from a command window. The path defined by APPDATA can be problematic if the user account for the command window is different than the user account that normally starts CIS as a service. By specifying a path here, we can avoid any possible confusion. On the other hand, the APPDATA variable might be useful in migration scenarios. When the settings are complete, click Create and Introspect.

Demo: OAuth Initiate GETANDREFRESH At this point a browser window appears. Google is asking for access approval. This is why GETANDREFRESH initial introspection must be done with Studio and Server on the same machine, with Monitor off. <CLICK> Click Allow, and Google responds with a success message.

Demo: OAuth Initiate GETANDREFRESH Introspection then proceeds normally, and we can work with the data as before.

Demo: OAuth Initiate GETANDREFRESH Now return to the command window and hit Control-C to terminate CIS. <CLICK> Start the CIS server as a service and resume normal operation. Running CIS from the console is only required for the initial introspection. We have seen examples of all three styles of Oauth initiation supported by CIS. Our demo is complete.

Agenda What is it and why does it matter? A basic demo Summary Let’s summarize what we have seen in this presentation.

Summary OAuth Open standard for Authorization Enables a user to give secure delegated access to user-owned resources Used by many cloud services, including Microsoft, Google, Facebook, and Twitter Used by many CIS adapters, including: REST Adapter Bundle for Social Media Adapter Bundle for NoSQL and Cloud DB’s Adapter Bundle for Marketing Automation Adapter Bundle for Collaboration Oauth is an open Authorization standard that specifies a set of REST-based interactions that enable a user to give secure delegated access to user-owned resources. Oauth is used by many cloud-based services, including those provided by Microsoft, Google, Facebook, Twitter, and many others. Oauth is important to our customers because it is either a required or optional protocol for many CIS adapters, including the REST adapter, and many of our adapter bundles. Thank you.

TOMORROW starts here.