Secure Data Connector (Deprecated)

Secure Data Connector Developer's Guide Tutorial: Google App Engine

This guide helps you write a Google App Engine application that works with enterprise access and security features, that is private to your domain, and that uses private data that is secure.

Private data means data that resides behind a firewall and is accessed with a URL from a web server in your intranet. The Secure Data Connector (SDC) ensures that private data is securely accessible to your Google App Engine application.

Contents

  1. Google App Engine Development
    1. Create an Application That Accesses Public Data
    2. Verify That the Application Works
    3. Register the Application
  2. Access Private Data
    1. Providing Private Data Access
      1. Download and Host the CSV File
    2. Modify the Application to Access Private Data
    3. Ensure that the Application Works

Google App Engine Development

The sections that follow enable you to create an application that uses Google App Engine and enterprise data.

Before starting the tutorial:

App Engine requires Java 1.5 or later.

Create an Application That Accesses Public Data

The easiest way to understand how the system works is to write a simple example application that uses the URL Fetch service to access public data.

To get started, create a directory called hellosdc. Underneath we'll create a src directory where we can write our source code and compile it.

$ mkdir hellosdc
$ cd hellosdc
$ mkdir src
$ cd src

Next, write a Java servlet that fetches a file from the Internet and displays its content. Create a file called HelloSDC.java:

hellosdc/src/HelloSDC.java
import java.io.IOException;
import java.net.URL;
import javax.servlet.http.*;
import com.google.appengine.api.users.User;
import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import com.google.appengine.api.urlfetch.*;


public class HelloSDC extends HttpServlet {
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();
    User user = userService.getCurrentUser();

    URLFetchService fetcher = URLFetchServiceFactory.getURLFetchService();

    URL dataURL = new URL("http://code.google.com/securedataconnector/docs/tutorials/contacts.csv");
    HTTPRequest fetchreq = new HTTPRequest(dataURL);

    if (user != null) {
      resp.setContentType("text/plain");
      resp.getWriter().println("Hello, " + user.getNickname());
      resp.getWriter().println("Fetching your data...");

      HTTPResponse fetchresp = fetcher.fetch(fetchreq);

      resp.getWriter().println("Response Code: " + fetchresp.getResponseCode());
      resp.getWriter().print(new String(fetchresp.getContent()));
    } else {
      resp.sendRedirect(userService.createLoginURL(req.getRequestURI()));
    }
  }
}

Note: The application prompts for user name and password authentication, which is described later in this tutorial.

To compile this code, you need to reference the Java Servlet API. A servlet library is included with the App Engine SDK (for example, geronimo-servlet_2.5_spec-1.2.jar). To compile, you need to add the servlet library to your CLASSPATH or copy it to your project src directory.

Notice that you also have a dependency on the package com.google.appengine.api.users. The appengine-api-1.0-sdk-1.2.2.jar file is provided in the Google App Engine SDK download. To resolve the dependency, you need to add the appengine-api-1.0-sdk-1.2.2.jar file to your CLASSPATH or copy it to your src directory before compiling this code.

Now we're ready to compile your servlet using the following command:

$ javac -classpath geronimo-servlet_2.5_spec-1.2.jar:appengine-api.jar:. HelloSDC.java

For Windows, use this command:

> javac -classpath .;geronimo-servlet_2.5_spec-1.2.jar;appengine-api-1.0-sdk-1.2.2.jar; HelloSDC.java

Package this class as a valid web application. Create a new directory under the hellosdc folder that is called deploy with the following structure:

$ cd ..
$ mkdir deploy
$ mkdir deploy/WEB-INF
$ mkdir deploy/WEB-INF/classes
$ cp src/HelloSDC.class deploy/WEB-INF/classes
$ mkdir deploy/WEB-INF/lib
$ cp src/appengine-api-1.0-sdk-1.2.2.jar deploy/WEB-INF/lib

For Windows, use:

> cd ..
> mkdir deploy\WEB-INF\classes
> mkdir deploy\WEB-INF\lib
> copy src\HelloSDC.class deploy\WEB-INF\classes
> copy src\appengine-api-1.0-sdk-1.2.2.jar deploy\WEB-INF\lib

To make this a valid web application, we also need to create a web.xml file that lists the servlets and specifies how they map to URL patterns. In this case our web.xml file is very simple:

hellosdc/deploy/WEB-INF/web.xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
  <servlet>
    <servlet-name>hw</servlet-name>
    <servlet-class>HelloSDC</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>hw</servlet-name>
    <url-url>/hello</url-url>
  </servlet-mapping>
</web-app>

There is one additional configuration file that you need: appengine-web.xml.

Create your appengine-web.xml so that it looks similar to the following -- note that you need to replace user.nickname with a valid user name:

hellosdc/deploy/WEB-INF/appengine-web.xml
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>hellosdc-java-user.nickname</application>
  <version>1</version>

  <static-files/>

  <resource-files/>
</appengine-web-app>

Now that you have your application and your web.xml and appengine-web.xml files, you can test the application.

Note: The development App Engine server requires Java 5, otherwise the NoClassDefFoundError: java/util/ServiceLoader error displays.

$ java -jar appengine-local-runtime.jar ./deploy

The appengine-local-runtime.jar replicates the environment in the real application_name server and runs your application on port 8080. You can access your newly created application at http://localhost:8080/hello.

Verify That the Application Works

Once you have an application running locally using the appengine-local-runtime.jar, the next step is to deploy your application to your domain with the Google App Engine Admin Console.

Important: You must edit the authentication options when you register your application to restrict the application to your Google Apps domain. For more information, see the Google Apps Admin Console documentation.

Register the Application

You need to upload your application to Google App Engine as follows for Linux:

$ appcfg.sh update ./deploy

For Windows, use:

> appcfg.com update deploy

When the script completes successfully, your application is available at:
https://hellosdc-java-user.nickname.appspot.com/hello

Where: user.nickname is a user's login name.

Access Private Data

The sections that follow explain how to modify your application to access a file which is hosted not on the internet, but instead hosted inside your intranet, and is not otherwise accessible to the public.

Note: This section assumes you have Installed the SDC. If SDC is not currently installed, you should complete that activity before returning to this tutorial to complete the remaining sections.

In the sections that follow we modify your application to access private data by adding one statement and supplying a new URL to where you host the CSV file. The statement that we add is as follows and is explained in the next sections:

fetchreq.setHeader(new HTTPHeader("use_intranet","yes"));

Providing Private Data Access

The sections that follow help you install the SDC and download and host a CSV file.

Download and Host the CSV File

Download the Contacts CSV file.

Put the CSV file on a web server in your domain. The URL of the web server needs to be specific to your company.

Create a rule in resourceRules.xml for the location and access of the CSV file (or add the <rule> code block to the existing resourceRules.xml file). See Configuring for more information. For example, if Polly Hedra wants to access the CSV file, specify the following resource rule:

<resourceRules>
  <rule repeatable="true">
    <ruleNum>1</ruleNum>
    <agentId>sdc42-agent</agentId>
    <viewerEmail repeatable="true">pollyhedra@example.com</viewerEmail>
    <url>http://www.corp.example.com/contacts.csv</url>
    <urlMatch>URLEXACT</urlMatch>
    <apps>
      <service>AppEngine</service>
      <allowAnyAppId>true</allowAnyAppId>
    </apps>
  </rule>
</resourceRules>

SDC uses resource rules to limit which users can access which corporate resources. The <resourceRules> element defines a source of information that is made available from a web server. The <rule> element defines what resources or applications that a Google App can access. This rule states that this is the first resource rule to be processed (by the <ruleNum>1 statement), that Polly Hedra may access the contacts.csv file at example.com (<url> statement).

Start (or restart) the SDC as described in the Configuring to ensure that the resource rules are visible to the SDC.

Notice that you must specify a set of accounts which are allowed to access the resource in the allowedEntities element. This is why you forced users to authenticate to access your application in the previous section of the tutorial.

Modify the Application to Access Private Data

To access private data, you need to add a special reserved header to your HTTP request from Google App Engine.

Add the following statement to your HelloSDC.java class, right after the declaration of the local HTTPRequest variable, fetchreq:

fetchreq.setHeader(new HTTPHeader("use_intranet","yes"));

The use_intranet header instructs the URL fetch service to resolve the specified URL within the intranet linked to your domain through SDC.

Next, modify the URL you are fetching to specify the location of the CSV file you are hosting within your intranet.

The completed HelloSDC class now appears as follows:

import java.io.IOException;
import java.net.URL;
import javax.servlet.http.*;
import com.google.appengine.api.users.User;
import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import com.google.appengine.api.urlfetch.*;


public class HelloSDC extends HttpServlet {
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();
    User user = userService.getCurrentUser();

    URLFetchService fetcher = URLFetchServiceFactory.getURLFetchService();

    //modified for secure data access
    URL dataURL = new URL("http://www.corp.example.com/contacts.csv");
    HTTPRequest fetchreq = new HTTPRequest(dataURL);
    fetchreq.setHeader(new HTTPHeader("use_intranet","yes"));

    if (user != null) {
      resp.setContentType("text/plain");
      resp.getWriter().println("Hello, " + user.getNickname());
      resp.getWriter().println("Fetching your data...");

      HTTPResponse fetchresp = fetcher.fetch(fetchreq);

      resp.getWriter().println("Response Code: " + fetchresp.getResponseCode());
      resp.getWriter().print(new String(fetchresp.getContent()));
    } else {
      resp.sendRedirect(userService.createLoginURL(req.getRequestURI()));
    }
  }
}

Ensure that the Application Works

You must now recompile the HelloSDC class and redeploy your application to Google:

$ javac -classpath geronimo-servlet_2.5_spec-1.2.jar:appengine-api.jar:. HelloSDC.java
$ cp src/HelloSDC.class deploy/WEB-INF/classes
$ appcfg.sh update ./deploy

For Windows, use:

> javac -classpath .;geronimo-servlet_2.5_spec-1.2.jar;appengine-api.jar; HelloSDC.java
> cp src/HelloSDC.class deploy/WEB-INF/classes
> appcfg.cmd update deploy

You can access your application, now integrated with your enterprise data source, at:

https://hellosdc-java-user.nickname.appspot.com/hello

If you have problems with the SDC connection, use the Debugging Query Parameters to test your connection.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.