In this article you will find a step-by-step guide to integrating your Ruby on Rails application with Google Apps and launching it on the Google Apps Marketplace. The Google Apps Marketplace is a great platform to get new clients, show off our product and integrate Floorplanner with the services Google provides. At the beginning of the summer we tried to launch our application on the Marketplace. We found out that a lot of people were struggling with the existing Rails libraries and the OAuth authorization method, therefore we would like to provide this tutorial to help other developers. I would like to thank Dušan Maliarik for building this implementation with me and finding the solution for using the two-legged OAuth authorization.
1. The initial setup
Before you start programming there is some required setup. You first have to add a new application on the Google Apps Marketplace. You will need a Vendor Profile for this and a Google account. Sign In to the Marketplace with your Google account and go to your Vendor Profile using the link at the top-right of the Marketplace homepage.
After you enter some information about your company, there will be a list of your applications called “Listings.” You need to create a new listing to develop and test your application. When you create a new listing, check the box which says “My product may be directly installed into Google Apps domains.” This is necessary if you want the application to have an “Add it Now” button on the listing page, and allows you to add a Manifest to describe the application.
A Manifest describes all the settings of your application, like the name, URL’s and required permissions. Below you can find an example manifest. You will need to change all fields surrounded by brackets [ ].
[ApplicationName]
[Description]
[ApplicationName]
[ApplicationLoginUrl]?domain=${DOMAIN_NAME}
[ApplicationRealm]
https://docs.google.com/feeds/
[Reason]
https://www.google.com/m8/feeds/
[Reason]
You should decide whether you want to create a setup page. During the installation process of the application you will be redirected to the URL you specified in the manifest under “setup”. This is useful for collecting additional information necessary for configuring the app, or setting up a new umbrella account for the company. The umbrella account allows you to use other users of the domain as sub-users. You can also retrieve other information, like the administrators of the domain, the logo of the Google Apps account, or the domain name of the Google Apps account. If you don’t want to redirect customers to your site during the installation process, then just remove the line from your manifest.
2. Rails libraries and OpenID
The code you’re going to use relies on several Rails plugins and gems. The plugins/gems needed for this tutorial are listed below.
After installing these, you will be able to use OpenID, OAuth and the Google Data APIs in your Rails application. First you are going to authenticate the user with OpenID. This way you can retrieve the user’s email address and other information like First and Last name. The OpenID implementation is straight-forward. When using OpenID, a connection will be made to Google’s OpenID service and will check if the user granted access to your application. In typical OpenID, a ‘grant access’ page or login page is presented if the user hasn’t granted access to the app, though this won’t happen if you have a Google Apps Marketplace application installed with a properly configured realm as access is granted by the administrator for all of their users. This process can be found in the example code below.
def login
# The domain needs to be set. For example with params[:domain]
authenticate_with_open_id(params[:domain]),
{ :required => ["http://axschema.org/contact/email"], :return_to => '/login'}) do |result, identity_url, registration|
if result.successful?
# Succesfully logged in, retrieve email address
email = get_email(registration)
else
# Failed to login
end
end
end
def get_email(registration)
ax_response = OpenID::AX::FetchResponse.from_success_response(
request.env[Rack::OpenID::RESPONSE])
ax_response.data["http://axschema.org/contact/email"].first
end
After reviewing this code sample you can alter it for using it with the setup page. Authenticate with OpenID when a user goes into the setup procedure and redirect them to the actual setup page after they are authenticated.
After your setup page is complete you can add your Google Apps Marketplace listing to your Google Apps account. Note that administrator privileges are necessary to add the application to your Google Apps account. You can add the application from the Vendor Profile when you click on your newly created application. A big blue button will appear on the right side of the listing’s information page. More information on this process can be found on the Creating a Listing page in the Marketplace developer documentation.
3. Using the Google Data APIs
When using the Google Data APIs outside of the Apps Marketplace you have to get access to a user’s data using three-legged OAuth, AuthSub or ClientLogin. These authorization methods require your application to redirect the user to Google’s site to request authorization. Because you’ve already authenticated the user by using OpenID and an administrator has granted authorization to the user’s data when they added your application to their Google Apps domain, you don’t want to use these methods.
For the Google Apps Marketplace there is another option– two-legged OAuth. Two-legged OAuth allows your application to use a single consumer key and secret (available from the Vendor Profile) to access the data for all your customers who have installed the Marketplace app and granted the appropriate permissions. Because the administrators have granted permission on behalf of their users, each user does not need to be prompted individually.
The first thing you should try is to retrieve a contact list of a user. You could use it for auto completion on forms, or you can let users quickly add friends to your application.
CONSUMER_KEY = "Your-consumer-key"
CONSUMER_SECRET = "Your-consumer-secret"
def get_contacts
# Retrieve contacts
email = "user@email.com"
url = "https://www.google.com/m8/feeds/contacts/default/full?xoauth_requestor_id=#{email}"
contacts = gdata_request(url, :get)
end
def gdata_request(url, method, headers = {}, data = "")
uri = URI.parse(url)
# Setting up two-legged-oauth
consumer = OAuth::Consumer.new(CONSUMER_KEY, CONSUMER_SECRET)
oauth_params = {:consumer => consumer, :method => method, :request_uri => uri.to_s}
# Set Net:HTTP connection
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.port == 443)
if method == :post
req = Net::HTTP::Post.new(uri.request_uri)
req.body = data
else
req = Net::HTTP::Get.new(uri.request_uri)
end
# Set authorization header
oauth_helper = OAuth::Client::Helper.new(req, oauth_params)
req.initialize_http_header(headers.merge({'Authorization' => oauth_helper.header}))
# Execute request
response = http.request(req)
response.body
end
The feature we struggled with the most during the integration of Floorplanner was the two-legged OAuth authorization. There was no documentation available for the gems and it took some attempts to get it right. We turned to the OAuth Playground to find out the differences between our own request and the working request. After numerous tries we found out that we need to specify the HTTP method in order to get it working. It was important to use the Net::HTTP::Post request when sending information and Net::HTTP::Get request when retrieving information. This sounds logical, but it also needed to be done when retrieving the authorization header in the OAuth Client Helper, as well as in the Net HTTP request. Now we have this code, we can generate a request for almost every call in the Google Data API’s.
In the next example, you will use the Google Docs API to send a CSV file to a user’s Google Docs account. You need to do a POST request to the Google Docs feed. The request is almost the same as in the previous example, only you need to add two more headers. One is the Content-Type where you specify the MIME type you want to send. In this case, you’re uploading a CSV file so “text/csv” will do. Another header you need to send is the Slug. This value specifies the name you want for the document in Google Docs. Another way of doing this is adding meta-data to the body of the request. More information on this method can be found in the the Google Docs documentation.
def submit_csv_to_gdocs
email = 'user@email.com'
url = 'https://docs.google.com/feeds/default/private/full?xoauth_requestor_id=#{email}'
# Create new CSV
csv = StringIO.new
CSV::Writer.generate(csv, ',') do |line|
line << ["Example 1", "Example 2"]
end
csv.rewind
# Send request
gdata_request(url, :post,
{ 'Content-Type' => 'text/csv',
'Slug' => 'test.csv',
'GData-Version' => '3.0' },
csv.read)
end
Now, this is all you need to get started with the Google Data API’s. Be sure to check out the Google Apps Marketplace Developer overview for more information and to see which API’s you could use and how to use these. I would advise to check out the OAuth Playground if you have any problems with authorization. Using the playground with two-legged OAuth is very easy. Just follow these steps:
- Set the signature method to HMAC-SHA1
- Type in your consumer key and consumer secret (these can be found in your Vendor Profile)
- Set your Feed URL (step 6)
- Set GData-version to 3.0 unless the API only supports 2.0
- Click execute
Since the OAuth playground traffic isn’t over SSL, I’d only recommend using it with the consumer key and secret for a test application installed on test domains.
Thank you for reading this tutorial. I know this isn’t the best approach on using two-legged OAuth but it will give you some insight. The best way would be to build in two-legged OAuth support in the Google Data APIs Ruby Utility Library. I haven’t done that yet but am planning to look into that soon. If you have any questions or comments, I would love to hear from you. You can email me at vincent@floorplanner.com.
One last note: These code snippets are just examples of how to use the Google Apps Marketplace with Rails. I would advise you not to use these examples in a production environment.