Authentication

Example Call

#!/bin/sh -e
email="john.doe@example.com"   # The email address for your RightScale User in the Dashboard
pswd="SomeSecurePassword"      # Your User's password
account="1234"                 # Account ID, easily obtained from navigation in the Dashboard

curl -i -H X_API_VERSION:1.5 -c mycookie -X POST --data-urlencode "email=$email" --data-urlencode "password=$pswd" -d account_href=/api/accounts/"$account" https://my.rightscale.com/api/session

Sample Output

HTTP/1.1 204 No Content
Server: nginx/1.0.15
Date: Tue, 09 Oct 2012 22:11:46 GMT
Connection: keep-alive
Status: 204 No Content
X-Runtime: 64
X-Request-Uuid: 5687742b86ba40468c037d362d32a2db
Set-Cookie: rs_gbl=eNo1kEFvgjABRv9Lz5DQFmxLsoMMMzQjgJls5NIoLaJTZFBENP338bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEWtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8yw3l7gRiUcallYRCajylzZbbaU_4pK06HipN_Pv3SEL9ej3PG2HehsK0ui0SpTXQ3Eakts2O8YyDrloEjivDhjhUovIG393s_nfZq2KevyJjvFw6egpjMmnuEVfI-02wWrRnlN9HeCHxRdBlrAd53VZeWvz3W76VO6L8zJgps_fXkWuryJ5UZz7WgOXORA-Hk9qR10P; domain=.rightscale.com; path=/; HttpOnly
Set-Cookie: _session_id=e7ee4fd4bce4543a2b258b2c8d54db80; path=/; Secure; HttpOnly
Cache-Control: no-cache

Your API session cookie will be saved to the file 'mycookie'.  The cookie file contains the session ID for use with subsequent API calls used by the examples.  The TTL (time to live) for the session cookie is 2 hours.  An example cookie file looks similar to:

$ cat mycookie   # NOTE:  Below cookie formatted slightly to make more readable.

# Netscape HTTP Cookie File
# http://www.netscape.com/newsref/std/cookie_spec.html
# This file was generated by libcurl! Edit at your own risk.

.rightscale.com TRUE    /       FALSE   0       rs_gbl  eNo1kEFvgjAARv9Lz5DQFmxLsoMMMzQjgJls5WIoLaJTZFBFNP538bDjl3zvHd4d5MAFpxEYQHbAvYO-Uy1wCaXkYQBdABdim1FkEXtmgL2czo5FFHVQbkLkKBNChUzh5M40McQS2jNpoUmn1T9L2Iud7KDe8y
w3l7gRiUcallYRCajylzZbbaU_4pK06HipN_Pv3SEL9ej3PG2HehsK0ui0SpTXQ3Eakts2O8YyDrloEjivDhjh
UovIG393s_nfZq2KevyJjvFw6egpjMmnuEVfI-02wWrRnlN9HeCHxRdBlrAd53VZeWvz3W76VO6L8zJgps_
fXkWuryJ5UZz7WgOWORA-Hk9qR10P
my.rightscale.com       FALSE   /       TRUE    0       _session_id     e7ce4fb4bce4543b2b258b2c8d54db80

If your session cookie expires you will receive:

• HTTP "403 Forbidden"
• "Session cookie is expired or invalid" message

Prerequisites

The authentication example below assumes the following Ruby and RightScale REST API client (right_api_client) installs have been completed.

$ ruby -v
ruby 1.8.7 (2011-06-30 patchlevel 352) [x86_64-linux]

# sudo -i        # switch to root user for installing the Ruby gem
# gem install right_api_client
Building native extensions.  This could take a while...
Successfully installed json-1.7.3
Successfully installed mime-types-1.18
Successfully installed rest-client-1.6.7
Successfully installed right_api_client-1.5.9
4 gems installed
Installing ri documentation for json-1.7.3...
Installing ri documentation for mime-types-1.18...
Installing ri documentation for rest-client-1.6.7...
Installing ri documentation for right_api_client-1.5.9...
Installing RDoc documentation for json-1.7.3...
Installing RDoc documentation for mime-types-1.18...
Installing RDoc documentation for rest-client-1.6.7...
Installing RDoc documentation for right_api_client-1.5.9...

$ exit           # logout from root user, create/run ruby scripts using right_api_client from a non-root user login.

Example Call

# Script:  authenticate - Establish authentication with the RS API.  Requires rubygems and right_api_client. 
# Authentication credentials stored in memory (not a cookie/file on local disk)
require 'rubygems'
require 'pp'                 # require the pp Pretty Print rubygem. 
require 'right_api_client'
@client = RightApi::Client.new(:email => 'greg.doe@example.com', :password => 'SomeSecurePassword', :account_id => '1234')
puts "Available methods: #{pp @client.api_methods}"    # Use pretty print for more readable output
#puts "Available methods: #{@client.api_methods}"      # Use standard puts call.  Less readable.  Commented out so it will not be executed.

$ ruby authenticate          # Run Ruby script 'authenticate' shown above.

Sample Output

Below output displays all methods available to the account that was previously authenticated.  More information on each method is in the RightScale API 1.5 Online Reference.

Note:  The following output uses "pp" (pretty print gem) in the Ruby script, producing more readable output.  Future right_api_client examples will use "pp" instead of the standard Ruby "puts" call (which is shown below for contrast).

["audit_entries",
"deployments",
"cloud_flow_processes",
"cloud_accounts",
"publication_lineages",
"server_templates",
"permissions",
"clouds",
"security_group_rules",
"accounts",
"tags",
"publications",
"server_arrays",
"users",
"alert_specs",
"multi_cloud_images",
"account_groups",
"servers",
"child_accounts",
"backups",
"session",
"identity_providers",
"server_template_multi_cloud_images"]

Important!  Only the resources (or their sub-resources) displayed in the output above can be used by the account. See the RightScale API Online Reference documentation for all API resources.  Note that the resources for your account will likely vary somewhat.

Note:  Below is sample output when using a Ruby "puts" call to display the available methods.  The output is less readable, stringing together all methods on a single line with no delimeters or whitespace.

Available methods: audit_entriesserverscloud_flow_processescloud_accountspublication_lineagesserver_template_multi_cloud_imagespermissionsdeploymentssecurity_group_rulesaccountspublicationsserver_templatesusersbackupscloudssessionalert_specstagsaccount_groupsserver_arrayschild_accountsidentity_providersmulti_cloud_images

Example Call

$email = "greg.doe@example.com"        # Use the Email Address for your RightScale User in the Dashboard
$passwd = "SomeSecurePassword"         # Your User's password
$account = "1234"                      # Your RightScale Account ID, easily obtained via Dashboard navigation
$postURL = "https://my.rightscale.com/api/session"
$stringToPost = "email=$email&password=$passwd&account_href=/api/accounts/$account"
$bytesToPost = [System.Text.Encoding]::UTF8.GetBytes($stringToPost)
$cookieContainer = New-object System.Net.CookieContainer
$webRequest = [System.Net.WebRequest]::Create($postURL)
$webRequest.Method = "POST"
$webRequest.ContentType = "application/x-www-form-urlencoded"
$webRequest.Headers.Add("X_API_VERSION","1.5")
$webRequest.ContentLength = $bytesToPost.Length
$webRequest.PreAuthenticate = $false;
$webRequest.ServicePoint.Expect100Continue = $false
$webRequest.CookieContainer = $cookieContainer
$requestStream = $webRequest.GetRequestStream()
$requestStream.Write($bytesToPost, 0, $bytesToPost.Length)
$requestStream.Close()
[System.Net.WebResponse]$response = $webRequest.GetResponse()
$responseStream = $response.GetResponseStream()
$responseStreamReader = New-Object System.IO.StreamReader -ArgumentList $responseStream
[string]$responseString = $responseStreamReader.ReadToEnd()
#this is the cookie container for subsequent requests: $cookieContainer

Sample Output

Same as http/curl response.