17 KiB

Raw Blame History

Authentication for Simple REST Clients

This document describes how authentication, authorization, and accounting are accomplished. For all API calls, your application needs to be authenticated. When an API accesses a user's private data, your application must also be authorized by the user to access the data. For example, accessing a public Google+ post would not require user authorization, but accessing a user's private calendar would. Also, for quota and billing purposes, all API calls involve accounting. This document summarizes the protocols used by Google APIs and provides links to more information.

Note: this is a "general" document, and not specific to this particular service client. In particular, you may find that the examples in this document are for a different client. All simple REST clients follow the same usage patterns, and you should be able to adapt the provided examples to the client you are using.

Access types

It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. For API methods that can use either, some will behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.

Simple API access using API keys

For API calls that do not access any private user data, your application may use an API key, authenticating as an application belonging to your Google API Console project. Every simple access call your application makes must include this key. This is needed to measure project usage for accounting purposes.

Authorized API access using OAuth 2.0

For API calls that access private user data, the user must grant your application access. This also implies that both your application, and the user granting access, must be authenticated. All of this is accomplished with OAuth 2.0 and libraries written for it.

Using API keys

When calling APIs that do not access private user data, you can use simple API keys. These keys are used to authenticate your application for accounting purposes. The Google Developers Console documentation also describes API keys.

Note: If you do need to access private user data, you must use OAuth 2.0 authentication.

To use API keys, set the key attribute on service objects. For example, here is how to use API keys to authenticate for the translate V2 service.

require 'google/apis/translate_v2'

translate = Google::Apis::TranslateV2::TranslateService.new
translate.key = 'YOUR_API_KEY_HERE'
result = translate.list_translations('Hello world!', 'es', source: 'en')
puts result.translations.first.translated_text

All calls made using that service object will include your API key.

Warning: Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your API Console project.

Using OAuth 2.0

This section describes OAuth 2.0, when to use it, how to acquire client IDs and client secrets, and generally how to use OAuth 2.0 with the Google API Client Library for Ruby.

About OAuth 2.0

OAuth 2.0 is the authorization protocol used by Google APIs. It is summarized on the Authentication page of this library's documentation, and there are other good references as well:

The Signet library is included with the Google API Client Library for Ruby. It handles all steps of the OAuth 2.0 protocol required for making API calls. It is available as a separate gem if you only need an OAuth 2.0 library.

OAuth 2.0 Concepts

Scope: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.

Refresh and access tokens: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.

Client ID and client secret: These strings uniquely identify your application and are used to acquire tokens. They are created for your project on the API Console. There are three types of client IDs:

Web application client IDs
Installed application client IDs
Service Account client IDs

Acquiring client IDs and secrets

To find your project's client ID and client secret, do the following:

Select an existing OAuth 2.0 credential or open the Credentials page.
If you haven't done so already, create your project's OAuth 2.0 credentials by clicking Create credentials > OAuth client ID, and providing the information needed to create the credentials.
Look for the Client ID in the OAuth 2.0 client IDs section. For details, click the client ID.

There are different types of client IDs, so be sure to get the correct type for your application:

Web application client IDs
Installed application client IDs
Service Account client IDs

Warning: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google APIs Console project, and request access to user data.

Client Secrets files

The Google APIs Client Library for Ruby uses the client_secrets.json file format for storing the client_id, client_secret, and other OAuth 2.0 parameters.

See Creating authorization credentials for how to obtain a client_secrets.json file.

The client_secrets.json file format is a JSON formatted file containing the client ID, client secret, and other OAuth 2.0 parameters. Here is an example client_secrets.json file for a web application:

{
  "web": {
    "client_id": "asdfjasdljfasdkjf",
    "client_secret": "1912308409123890",
    "redirect_uris": ["https://www.example.com/oauth2callback"],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token"
  }
}

Here is an example client_secrets.json file for an installed application:

{
  "installed": {
    "client_id": "837647042410-75ifg...usercontent.com",
    "client_secret":"asdlkfjaskd",
    "redirect_uris": ["http://localhost", "urn:ietf:wg:oauth:2.0:oob"],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token"
  }
}

The format defines one of two client ID types:

web: Web application.
installed: Installed application.

The web and installed sub-objects have the following mandatory members:

client_id (string): The client ID.
client_secret (string): The client secret.
redirect_uris (list of strings): A list of valid redirection endpoint URIs. This list should match the list entered for the client ID on the API Access pane of the Google APIs Console.
auth_uri (string): The authorization server endpoint URI.
token_uri (string): The token server endpoint URI.

All of the above members are mandatory. The following optional parameters may appear:

client_email (string) The service account email associated with the client.
auth_provider_x509_cert_url (string) The URL of the public x509 certificate, used to verify the signature on JWTs, such as ID tokens, signed by the authentication provider.
client_x509_cert_url (string) The URL of the public x509 certificate, used to verify JWTs signed by the client.

The following shows how you can use a client_secrets.json file and the Google::APIClient::ClientSecrets class to create a new authorization object:

require 'google/api_client/client_secrets'

CLIENT_SECRETS = Google::APIClient::ClientSecrets.load
authorization = CLIENT_SECRETS.to_authorization

# You can then use this with an API client, e.g.:
client.authorization = authorization

Flows

There are three main OAuth 2.0 flows in the Google API Client Library for Ruby: web server, installed application and service account.

Web server

We start by retrieving the client ID and client secret from a preconfigured client_secrets.json file:

client_secrets = Google::APIClient::ClientSecrets.load

For web-based applications, we then redirect the user to an authorization page:

# Request authorization
redirect user_credentials.authorization_uri.to_s, 303

The user completes the steps on her browser, and control gets returned to the application via the callback URL:

get '/oauth2callback' do
  # Exchange token
  user_credentials.code = params[:code] if params[:code]
  user_credentials.fetch_access_token!
  redirect to('/')
end

user_credentials now has everything needed to make authenticated requests:

events = calendar.list_events('primary', options: { authorization: user_credentials })

Below is the full sample we've been looking at.

require 'google/apis/calendar_v3'
require 'google/api_client/client_secrets'
require 'sinatra'
require 'logger'

enable :sessions

def logger; settings.logger end

def calendar; settings.calendar; end

def user_credentials
  # Build a per-request oauth credential based on token stored in session
  # which allows us to use a shared API client.
  @authorization ||= (
    auth = settings.authorization.dup
    auth.redirect_uri = to('/oauth2callback')
    auth.update_token!(session)
    auth
  )
end

configure do
  log_file = File.open('calendar.log', 'a+')
  log_file.sync = true
  logger = Logger.new(log_file)
  logger.level = Logger::DEBUG

  Google::Apis::ClientOptions.default.application_name = 'Ruby Calendar sample'
  Google::Apis::ClientOptions.default.application_version = '1.0.0'
  calendar_api = Google::Apis::CalendarV3::CalendarService.new

  client_secrets = Google::APIClient::ClientSecrets.load
  authorization = client_secrets.to_authorization
  authorization.scope = 'https://www.googleapis.com/auth/calendar'

  set :authorization, authorization
  set :logger, logger
  set :calendar, calendar_api
end

before do
  # Ensure user has authorized the app
  unless user_credentials.access_token || request.path_info =~ /^\/oauth2/
    redirect to('/oauth2authorize')
  end
end

after do
  # Serialize the access/refresh token to the session and credential store.
  session[:access_token] = user_credentials.access_token
  session[:refresh_token] = user_credentials.refresh_token
  session[:expires_in] = user_credentials.expires_in
  session[:issued_at] = user_credentials.issued_at
end

get '/oauth2authorize' do
  # Request authorization
  redirect user_credentials.authorization_uri.to_s, 303
end

get '/oauth2callback' do
  # Exchange token
  user_credentials.code = params[:code] if params[:code]
  user_credentials.fetch_access_token!
  redirect to('/')
end

get '/' do
  # Fetch list of events on the user's default calandar
  events = calendar.list_events('primary', options: { authorization: user_credentials })
  [200, {'Content-Type' => 'application/json'}, events.to_h.to_json]
end

For more detailed information, see the Web Application Flow Documentation.

Installed application

We start by retrieving the client ID and client secret from a preconfigured client_secrets.json file:

client_secrets = Google::APIClient::ClientSecrets.load

For installed applications, we can use the Google::APIClient::InstalledAppFlow helper class to handle most of the setup:

flow = Google::APIClient::InstalledAppFlow.new(
    :client_id => client_secrets.client_id,
    :client_secret => client_secrets.client_secret,
    :scope => ['https://www.googleapis.com/auth/adsense.readonly']
)

The user completes the steps on her browser, which is opened automatically, and the authorization code is fed into the application automatically, so all it takes is:

adsense.authorization = flow.authorize(storage)

The client now has everything needed to make an authenticated request:

  report = adsense.generate_report(start_date: '2011-01-01', end_date: '2011-08-31',
                                   metric: %w(PAGE_VIEWS AD_REQUESTS AD_REQUESTS_COVERAGE
                                              CLICKS AD_REQUESTS_CTR COST_PER_CLICK
                                              AD_REQUESTS_RPM EARNINGS),
                                   dimension: %w(DATE),
                                   sort: %w(+DATE))