Secure Data Connector (Deprecated)

Secure Data Connector Developer's Guide: Installing and Configuring

The information in this section enables you to install and configure Secure Data Connector (SDC).

Installing consistes of:

  • Downloading the release.
  • Unzip the release zip file and follow the diretions in the README file.

Configuring consists of setting parameters in two XML files:

  • The localConfig.xml file is for configuring the SDC agent and it's connection to Google Apps.
  • The resourceRules.xml file is for configuring which Google Apps users and which components can access which resources within your domain.

Contents

  1. Downloading and Installation
  2. Configuring Google Apps Domain Parameters
  3. Configuring Resource Rules
    1. How Rules are Processed
  4. Configuring the Connection to Google Apps
  5. Starting and Stopping SDC

Downloading and Installing

Download the latest zip file. The current pre-release version is 1.3-rc0. Starting with this version, the agent is packaged as a single executable jar file. The only requirement for running the agent is JDK 1.6 and starting up the agent can be as simple as java -jar sdc-agent.jar followed by command-line options.

  • Please read the README file inside the distribution for information specific to this release.
  • There are example shell scripts (bin/start.sh and bin/stop.sh) for starting and stopping the agent on Linux platforms.
  • Please customize the scripts accordingly to your environment. There are script variables that define the paths to directories for the configuration xml file, log file, etc. that should be modified according to your environment.

Configuring Google Apps Domain Parameters

Activate SDC from the Google Apps Domain control panel of the Google Apps for Business and Education:

  1. Locate the Secure Data Connector section on the Advanced Tools page:
    Google Apps control panel Advanced Tools item for activating SDC
  2. Click Activate and configure Secure Data Connector.
  3. Click the Activate Secure Data Connector check box.
  4. Click Change Password and assign a password. Specify a strong password to ensure that you get past the login CAPTCHA requirement.
  5. Store the password value in accordance with your security policy. You will need to add this value to the <password> element in the localConfig.xml file.
  6. Remove the CAPTCHA on the accont:
    1. Visit https://www.google.com/a/<YOUR_DOMAIN>/UnlockCaptcha.
    2. Enter the Username secure-data-connector-user.
    3. Enter the Password you specified in Step 4.

      Note: If you do not specify a strong password, you will be periodically forced to resolve the CAPTCHA.

Configuring the Connection to Google Apps

The local configuration file (localConfig.xml) provides the necessary information that enables the SDC agent to communicate with Google Apps. After you complete configuration, see Starting and Stopping SDC.

To configure the local configuration XML file:

  1. Change to the configuration directory in which you installed SDC. For example /etc/opt/google/secure-data-connector/<version>.
  2. Use a text editor to edit the localConfig.xml file.
  3. Create a unique ID for your SDC. For example sdc1-client.
  4. Specify the Google Apps domain in the <domain> element, for example, <domain>example.com</domain>.
  5. Specify the Google Apps <user> element <user>secure-data-connector-user</user>.
  6. Specify the password for the user account in the <password> element that you created when you activated SDC, for example, <password>42mice54</password>.
  7. Specify which users can use the Health Check gadget in the <healthCheckGadgetUsers> element. For more information, see Health Check Gadget.
  8. All other elements in this file can be left in their default values. However, if a conflict exists between the SOCKS server port and another application on the same computer:
    1. Adjust the <socksServerPort> element.

A completed example localConfig.xml file is as follows:

<entity>
  <sdcServerHost>apps-secure-data-connector.google.com</sdcServerHost>
  <sdcServerPort>443</sdcServerPort>
  <domain>example.com</domain>
  <user>secure-data-connector-user</user>
  <password>ValidDomainUserPassword</password>
  <agentId>client1_example-com</agentId>
  <socksServerPort>1080</socksServerPort>
  <healthCheckGadgetUsers> phedra@example.com, admin@example.com </healthCheckGadgetUsers>
</entity>

The following table lists each local configuration element--all elements are required.

Tag Description
<rule> The data set element.
<sdcServerHost> Google server host IPv4 IP address or fully-qualified domain name for use by SDC access. This value should not be changed unless instructed by Google.
<sdcServerPort> TCP port for the Google host that listens for SDC service requests. If this port conflicts with another service, you can change this port to another value. Ensure that this port is opened in your domain's corporate firewall for continuous outbound connections.
<domain> IPv4 IP address or fully-qualified domain name of the domain where you are installing the SDC Agent.
<user> Always set to the <user>secure-data-connector-user</user> value.
<password> Password that you specify when you activate SDC from the Advanced Tools page in Google Apps for Business or Education. For more information on activating SDC, see Installing.
<agentId> Agent ID. This value must be the same as a <agentId> element in the resource rules file. Each agent across your Google Apps domain must have a unique value.
<socksServerPort> Sockets server port listener. If this port conflicts with another service, you can change this port to another value. Ensure that this port is opened in a corporate firewall for inbound connections.
<healthCheckGadgetUsers> Specifies the users who can access the Health Check gadget (in addition to the <user> login. For more information, see Health Check Gadget.

Configuring Resource Rules

Resource rules specify which users can access which resources in the local domain. SDC applies the <rule> blocks in the order number specified in the <ruleNum> tag. The rules allow access to a URL pattern. After you complete configuration, see Starting and Stopping SDC.

To configure the resource rules XML file:

  1. Change directory to where the SDC configuration resides—e.g., /etc/opt/google/secure-data-connector/<version>.
  2. Use a text editor to edit the resourceRules.xml file.
  3. Create an <rule> element block for users who need access to a URL within your company's domain.
    1. Specify the order number in which Secure Data Connector processes the rule using the <ruleNum> element. The <ruleNum> element is an integer value from 1 to 2147483547.
    2. Set the <agentId> element to the same value as the <agentId> element in the localConfig.xml file.
    3. For each person who needs to access a resource URL, create an <viewerEmail> element. For example, to enable user Polly Hedra at Example.com to access a resource, enter the following element:
      <viewerEmail>pollyhedra@example.com</viewerEmail>
    4. For each resource that a user needs to access, specify a <url> element. For example, to specify access to a URL that lists the contents of a CSV file, the <url> element is:
      <url>http://code.google.com/securedataconnector/docs/tutorials/contacts.csv<url>
      SDC does not presently support self-signed or invalid SSL certificates. Also, ensure that your certificate chain maps to a well-known authority.
    5. For each application that a user needs access, specify an <apps> element block:
      1. Specify the <service> depending on the Google Apps product that you are using to access SDC:
        • Google App Engine: <service>AppEngine</service>
        • Google Apps Script: <service>Apps Script</service>
        • Google Gadgets: <service>Gadgets</service>
        • Google Spreadsheets: <service>Spreadsheets</service>
      2. Specify the <appId> value as follows:
        Service AppId
        AppEngine The name of an application, for example for an application at http://hellosdc.appspot.com, the <appId> value is hellosdc; that is, <appId>hellosdc</appId>.
        Gadgets The URL of a gadget in Google Apps, such as <appId>http://feedserver-enterprise.googleusercontent.com/a/example.com/g/PrivateGadgetSpec/mygadget.xml</appId>.
        The Gadget Tutorial shows how to use the Private Gadget Editor, which displays a link labelled Gadget URL.
        Spreadsheets Use only with the <allowAnyAppId>true</allowAnyAppId> element.

      3. Specify how to match the URL in the <url> element:
        • HOSTPORT: Matches the URL and its port specification. Use this match option for URLs such as the http://www.example.com:8080/ path. Using this match setting, viewers can access a URL such as the http://www.example.com:8080/treefrog path.
          Use the HOSTPORT match value if you set the <url> element to a socket:// path.
        • URLEXACT: Matches the URL based on the <url> element up to the first "?" in the URL request. For example, if you set the <url> element to http://feed.example.com/lookupuser, a viewer can access http://feed.example.com/lookupuser?user=phedra path. The matching criteria in this example is any URL request that has a prefix value of http://feed.example.com/lookupuser?.

The completed resource rule <resourceRules> element block in the resourceRules.xml file that enables Polly Hedra to access the CSV file from a spreadsheet is:

<resourceRules>
  <rule repeatable="true">
    <ruleNum>1</ruleNum>
    <agentId>all</agentId>
    <viewerEmail>pollyhedra@example.com</viewerEmail>
    <url>http://code.google.com/securedataconnector/docs/tutorials/contacts.csv</url>
    <urlMatch>URLEXACT</urlMatch>
    <apps>
      <service>Spreadsheets</service>
      <allowAnyAppId>true</allowAnyAppId>
    </apps>
  </rule>
</resourceRules>

The following table lists each resource rule element. All elements are required.

The <apps>, <rule>, and <viewerEmail> elements can be repeated as needed by including the repeatable="true" attribute.

Tag Parent Description
<allowAnyAppId> <apps> Set to true to enable access all apps from the specified service. This element cannot be used with the <appId> element.

Note: This element must be used with Google Spreadsheets. It is recommended to not use this element for gadgets because doing so would enable third party gadget code that your users installed to make requests over SDC.
<allowDomainViewers> <apps> Set to true to enable all users in your domain to access the pattern URL or application. This element cannot be used with the <viewerEmail> element.
<viewerEmail> <rule>

Indicates a user who is allowed to access the pattern URL or an application. The user ID is a user name registered with Google as a login for Google Apps. Do not specify a host name as the allowed entity.

<appId> <apps>

The ID for an application that a viewer is allowed to execute. The possible values are:

  • AppEngine - The name of an application, for example for an application at http://hellosdc.appspot.com, the <appId> value is hellosdc; that is, <appId>hellosdc</appId>.
  • Gadget - The URL of a gadget in the PrivateGadget feed.
  • Spreadsheets - Only use Google Spreadsheets with the <allowAnyAppId>true element.
<apps> <rule> Indicates the data set that specifies the applications that a viewer can access.
<agentId> <rule> SDC Agent ID associated the <ruleNum> element. Use the default value of <agentId>all</agentId>. This value will be used in future versions to control rules based on specific agentIds.
<service> <apps>

Indicates the Google App product that provides SDC access.
Possible values are:

  • AppEngine - Google App Engine
  • Gadgets - Google Sites or Google Visualization API
  • Spreadsheets - Google Spreadsheets
<rule> <resourceRules> Indicates a data set. If there is more than one entity within the <resourceRules> element block, use the repeatable="true" attribute to the <rule> element. As a best practice, you can use the repeatable="true" attribute for any number of rules without causing an error.
<resourceRules> -- A collection of rules that indicate which viewers can access which resources and applications.
<url> <rule> HTTP, HTTPS or socket:// URL to which users can access within the corporate site. Specify the sequence number in the <ruleNum> element to indicate the order that SDC evaluates each URL.
<ruleNum> <rule> The sequence number for the order that SDC evaluates the <rule> element block. The <ruleNum> element value can be an integer from 1 to 2147483547. The resource rules are indexed by the number value in the <ruleNum> element.

For each sequence number (<ruleNum> element), specify a <agentId> element. There is one <ruleNum> element for an <agentId> element.

<urlMatch> <rule>

Indicates how to match the URL that you specify in the <url> element.
Possible values are:

  • HOSTPORT - Matches the URL and its port specification. Use this match option for URLs such as the http://www.example.com:8080/ path. Using this match setting, viewers can access a URL such as the http://www.example.com:8080/treefrog path.
    Use the HOSTPORT match value if you set the <url> element to a socket:// path.
  • URLEXACT - Matches the URL based on the <url> element up to the first "?" in the URL request. For example, if you set the <url> element to http://feed.example.com/lookupuser, a viewer can access the http://feed.example.com/lookupuser?user=phedra path. The matching criteria in this example is any URL request that has a prefix value of http://feed.example.com/lookupuser?.

Note: A detailed sample resourceRules.xml is included with the downloadable SDC agent.

How Rules are Processed

SDC processes rules in ascending order specified by the <ruleNum> elements. SDC enumerates the rules until it finds a rule whose <url> element matches the resource being requested. After a URL pattern is matched, no further rules are processed.

SDC then checks whether the user who made the request matches any entries in the <viewerEmail> tags. If the user is a match, then the requested resource is returned. Otherwise, an error is returned.

Because of this rule processing model, you should add the rules with the most restrictive URL patterns into the list first and specify the broader resource rules further down in the list order.

Note: You can use the debugging query parameter to check how your requests are matching against resource rules.

Starting and Stopping SDC

You can start and stop the Linux SDC client from the command line.

Note: You need to run the start and stop commands from the root login on your computer. You also need Java JDK 1.6 for the scripts to execute.

Configuring Scripts

Many scripts have supplemental configuration parameters that are governed by environment variables values. You may edit these scripts to fit your needs; however, to override default values, simply uncomment the names prefixed with OVERRIDE_ and provide them with a new value—e.g., uncommenting and initializing OVERRIDE_BINDIR to provide a new value for BINDIR.

The OVERRIDE_ convention has been chosen to allow you to revert to the distributor's pristine settings easily.

Starting

To start the SDC, change directory to the /opt/google/secure-data-connector/<version> folder where you extracted the TAR files and run the start.sh command:

sudo setsid bin/start.sh

Note: The start.sh script is a wrapper to start the client as a detached background process.
The script logs all output to the log file: /var/opt/google/secure-data-connector/<version>/log/agent. The use of setsid is optional but recommended.

You can terminate your login shell and the SDC client continues running as a detached background process.

Stopping

To stop the SDC client, change directory to the /opt/google-secure-data-connector folder where you extracted the TAR files and run the stop.sh command:

sudo bin/stop.sh

Running Interactively

If you would prefer to run the SDC client interactively run the sudo bin/runclient.sh command.

Note: The SDC client closes after your login shell terminates or you use Ctrl-C to break out of the process.

Review the log file /var/opt/google/secure-data-connector/<version>/log/agent for a successful connection. An example log file is described in the Debugging section.

Managing Log Hygiene

Depending on the debug level set in the log configuration, you may want to configure logrotate to operate on a periodic basis.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.