Google Apps Connector

The Google Apps connector implements the Identity Java Connector Integration Framework’s DxmConnector interface and connects to a Google Apps server through the Google Apps API. It can be used for real-time workflows in the Java-based (IdS-J) Server. Like all framework-based connectors, it gets SPML requests from the DirX Identity side and then converts them to the appropriate Google Apps API calls and vice versa. The Google Apps connectivity is based on HTTP protocol. The connector supports membership stored on the accounts level.

The connector is implemented in the GoogleAppsConnector class in the package net.atos.dirx.dxi.connector.googleapps.

The connector implements the common methods for the DirX Identity Connector API: add, modify, delete and search.

The operations are simply converted to the Google Apps Admin Directory API requests. The corresponding responses are again translated to SPMLv1 responses.

The Google Apps Admin Directory API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. The connector uses JavaScript Object Notation (JSON) content types for requests and responses.

The connector communicates using SSL/TLS only.

Prerequisites and Limitations

The connector is based on Admin Directory API version 1.19.0 available at https://developers.google.com/admin-sdk/directory/v1/libraries. The connector functionality is limited by the functionality of the API version in use. Compatibility with other API versions is not guaranteed.

To communicate with the Google servers, the connector needs to authenticate using a Service Account Private Key, a Service Account User and a Service Account Email provided by Google on account creation.

The operations are authorized by an OAuth server, so the privileges and scope need to be set in the Google Admin Console; they cannot be modified at the connector level.

The connector supports common Google Apps user objects (common attributes and navigation properties like memberOf, manager and secretary) and Google Apps group objects (common attributes only).

The connector does not support nested group assignment. Nested group assignments cannot be read or written.

Request and Response Handling

This section describes the supported requests and attributes for the Google Apps connector. All attributes allowed by the Google Apps API can be added.

Add Request

The (user) add request creates a new user in Google Apps. The following attributes are supported:

  • primaryEmail - mandatory, unique

  • givenName - mandatory

  • familyName - mandatory

  • password - mandatory

  • suspended

  • changePasswordAtNextLogin

  • ipWhitelisted

  • externalIds - for type "work"

  • relations - for type "manager" and "assistant"

  • addresses [poBox] - for "primary"

  • addresses [extendedAddress] - for "primary"

  • addresses [streetAddress] - for "primary"

  • addresses [locality] - for "primary"

  • addresses [region] - for "primary"

  • addresses [postalCode] - for "primary"

  • addresses [countryCode] - for "primary"

  • organizations [name] - for "primary"

  • phones [work]

  • phones [work_mobile]

  • phones [home]

  • orgUnitPath

  • includeInGlobalAddressList

  • memberOf

Here is an example request:

<spml:addRequest  returnData="identifier"
    requestID="add-user-01" targetID="users"
    xmlns="urn:oasis:names:tc:SPML:1:0"
    xmlns:spml="urn:oasis:names:tc:SPML:1:0"
    xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
   <spml:identifier type="urn:oasis:names:tc:SPML:1:0#GenericString">
       <spml:id>1234</spml:id>
   </spml:identifier>
      <spml:attributes>
    <dsml:attrname="userName"><dsml:value> Miller Tom</dsml:value></dsml:attr>
     <dsml:attr name="givenName"><dsml:value>Miller</dsml:value></dsml:attr>
     <dsml:attr name="familyName"><dsml:value>Tom</dsml:value></dsml:attr>
     <dsml:attr name="password"><dsml:value>password</dsml:value></dsml:attr>
     <dsml:attr name="state"><dsml:value>ENABLED</dsml:value></dsml:attr>
     <dsml:attr name="primaryMail"><dsml:value> Miller@domain</dsml:value></dsml:attr>
     <dsml:attr name="phones">
          <dsml:value type="string">
             {"value":"0724553207","type":"work_mobile","primary":true}
          </dsml:value>
          <dsml:value type="string">
             {"value":"0724553207","type":"home"}
          </dsml:value>
     </dsml:attr>
     <dsml:attr name="externalIds">
        <dsml:value type="string">{"value":"123","type":"organization"}</dsml:value>
     </dsml:attr>
     <dsml:attr name="relations">
          <dsml:value type="string">
             {"value":"Razvan","type":"manager"}
          </dsml:value>
          <dsml:value type="string">
             {"value":"Rudi","type":"assistant"}
          </dsml:value>
     </dsml:attr>
     <dsml:attr name="addresses">
         <dsml:value type="string">
               {"type":"work","poBox":"21","extendedAddress":"Griviteinr.77","streetAddress":"Grivitei","locality":"Brasov","region":"Brasov",
              "postalCode":"1111","countryCode":"US","primary":true}
      </dsml:value>
    </dsml:attr>
      </spml:attributes>
             <spml:operationalAttributes>
                 <spml:attr name="objType">
                     <dsml:value type="string">user</dsml:value>
                </spml:attr>
     </spml:operationalAttributes>
</spml:addRequest>

The (group) add request creates a new group in Google Apps. The following attributes are supported:

  • email - mandatory, unique

  • name

  • description

Modify Request

In the modify request, the identifier is mandatory. All attributes allowed by the Google Apps API can be modified.

Note that users may experience issues when trying to delete everything under a multiple-valued attribute like "phones" or "addresses". This is a Google API problem: it doesn’t allow you to delete everything at once, just one entry at a time.

Delete Request

In the delete request, the identifier is mandatory. The delete request does not require additional attributes.

Search Request

In the search request, the Google Apps connector supports the standard element searchBase and the operational attributes scope and objType.

To search for all users or groups, the searchBase needs to be empty.

Configuration

Here is a sample configuration snippet for the Google Apps connector:

<connector className="net.atos.dirx.dxi.connector.googleapps.GoogleAppsConnector"
                 name="TS" role="connector">
       <connection user="admin@dirx-interop.com">
           <property name="proxyHost" value="proxy-emea.my-it-solutions.net"/>
           <property name="proxyPort" value="84"/>
           <property name="domain" value="dirx-interop.com"/>
           <property name="applicationName" value="identity"/>
           <property name="clientId" value="developerID@developer.gserviceaccount.com"/>
           <property name="clientSecret"
value="###@dxrConnectionLink@dxmClientSecret###"/>
       </connection>
     </connector>

Supported Connection Parameters

The connector supports the following standard properties of the <connection> element of the XML configuration file:

user - the user identifier to be used for authentication in the format: name@domain.

It also supports the following properties:

proxyHost: optional. This property provides information about the host name or IP address of the HTTP proxy server. Do not use authenticated proxy servers. If the access to the proxy server requires authentication, deploy another local transparent proxy server that can access to the authenticated one. Use only local proxy server instead.

proxyPort: optional. This property provides information about the port number of the HTTP proxy server. Do not use authenticated proxy servers. See description for proxyHost for more details.

clientId: mandatory. This property provides the Service Account Email Key of your registered remote application, used for authenticating to Google Apps.

clientSecret: mandatory. This property provides the Service Account Private of your registered remote application, used for authenticating to Google Apps.

domain: mandatory. This property is the domain of your registered remote application.

applicationName: mandatory. This property is the name you selected for your application. (The value can be anything you want; the name is used by the Google servers to monitor the source of authentication).

Additional Notes

Access to the Google Apps API must be activated using the Google Apps administration web site. (See the online Google Apps documentation.)

The Google Apps Provisioning API has been officially deprecated as of May 15, 2013. It has been replaced by the Admin SDK’s Directory API. The Google Apps Provisioning API will continue to work according to the Deprecation Policy.