Class: Google::Auth::Credentials

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/googleauth/credentials.rb

Overview

Credentials is a high-level base class used by Google’s API client libraries to represent the authentication when connecting to an API. In most cases, it is subclassed by API-specific credential classes that can be instantiated by clients.

## Options

Credentials classes are configured with options that dictate default values for parameters such as scope and audience. These defaults are expressed as class attributes, and may differ from endpoint to endpoint. Normally, an API client will provide subclasses specific to each endpoint, configured with appropriate values.

Note that these options inherit up the class hierarchy. If a particular options is not set for a subclass, its superclass is queried.

Some older users of this class set options via constants. This usage is deprecated. For example, instead of setting the ‘AUDIENCE` constant on your subclass, call the `audience=` method.

## Example

class MyCredentials < Google::Auth::Credentials
  # Set the default scope for these credentials
  self.scope = "http://example.com/my_scope"
end

# creds is a credentials object suitable for Google API clients
creds = MyCredentials.default
creds.scope  # => ["http://example.com/my_scope"]

class SubCredentials < MyCredentials
  # Override the default scope for this subclass
  self.scope = "http://example.com/sub_scope"
end

creds2 = SubCredentials.default
creds2.scope  # => ["http://example.com/sub_scope"]

Constant Summary collapse

TOKEN_CREDENTIAL_URI =

The default token credential URI to be used when none is provided during initialization.

"https://oauth2.googleapis.com/token".freeze
AUDIENCE =

The default target audience ID to be used when none is provided during initialization.

"https://oauth2.googleapis.com/token".freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(keyfile, options = {}) ⇒ Credentials

Creates a new Credentials instance with the provided auth credentials, and with the default values configured on the class.

Parameters:

  • keyfile (String, Hash, Signet::OAuth2::Client) —

    The keyfile can be provided as one of the following:

    • The path to a JSON keyfile (as a String)

    • The contents of a JSON keyfile (as a Hash)

    • A Signet::OAuth2::Client object

  • options (Hash) (defaults to: {}) —

    The options for configuring the credentials instance. The following is supported:

    • :scope - the scope for the client

    • “project_id” (and optionally “project”) - the project identifier for the client

    • :connection_builder - the connection builder to use for the client

    • :default_connection - the default connection to use for the client



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/googleauth/credentials.rb', line 368

def initialize keyfile, options = {}
  verify_keyfile_provided! keyfile
  @project_id = options["project_id"] || options["project"]
  @quota_project_id = options["quota_project_id"]
  case keyfile
  when Signet::OAuth2::Client
    update_from_signet keyfile
  when Hash
    update_from_hash keyfile, options
  else
    update_from_filepath keyfile, options
  end
  CredentialsLoader.warn_if_cloud_sdk_credentials @client.client_id
  @project_id ||= CredentialsLoader.load_gcloud_project_id
  @client.fetch_access_token!
  @env_vars = nil
  @paths = nil
  @scope = nil
end

Instance Attribute Details

#audience ⇒ String (readonly)

Returns The target audience ID when issuing assertions. Used only by the assertion grant type.

Returns:

  • (String) —

    The target audience ID when issuing assertions. Used only by the assertion grant type.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#client ⇒ Signet::OAuth2::Client

The Signet::OAuth2::Client object the Credentials instance is using.

Returns:



301
302
303
 
# File 'lib/googleauth/credentials.rb', line 301

def client
  @client
end

#issuer ⇒ String (readonly)

Returns The issuer ID associated with this client.

Returns:

  • (String) —

    The issuer ID associated with this client.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#project_id ⇒ String (readonly)

Identifier for the project the client is authenticating with.

Returns:

  • (String) 


308
309
310
 
# File 'lib/googleauth/credentials.rb', line 308

def project_id
  @project_id
end

#quota_project_id ⇒ String? (readonly)

Identifier for a separate project used for billing/quota, if any.

Returns:

  • (String, nil) 


315
316
317
 
# File 'lib/googleauth/credentials.rb', line 315

def quota_project_id
  @quota_project_id
end

#scope ⇒ String+ (readonly)

Returns The scope for this client. A scope is an access range defined by the authorization server. The scope can be a single value or a list of values.

Returns:

  • (String, Array<String>) —

    The scope for this client. A scope is an access range defined by the authorization server. The scope can be a single value or a list of values.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#signing_key ⇒ String, OpenSSL::PKey (readonly)

Returns The signing key associated with this client.

Returns:

  • (String, OpenSSL::PKey) —

    The signing key associated with this client.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#target_audience ⇒ String (readonly)

Returns The final target audience for ID tokens returned by this credential.

Returns:

  • (String) —

    The final target audience for ID tokens returned by this credential.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#token_credential_uri ⇒ String (readonly)

Returns The token credential URI. The URI is the authorization server’s HTTP endpoint capable of issuing tokens and refreshing expired tokens.

Returns:

  • (String) —

    The token credential URI. The URI is the authorization server’s HTTP endpoint capable of issuing tokens and refreshing expired tokens.



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

#updater_proc ⇒ Proc (readonly)

Returns a reference to the Signet::OAuth2::Client#apply method, suitable for passing as a closure.

Returns:



346
347
348
 
# File 'lib/googleauth/credentials.rb', line 346

def_delegators :@client,
:token_credential_uri, :audience,
:scope, :issuer, :signing_key, :updater_proc, :target_audience

Class Method Details

.audience ⇒ String

The default target audience ID to be used when none is provided during initialization. Used only by the assertion grant type.

Returns:

  • (String) 


117
118
119
120
121
 
# File 'lib/googleauth/credentials.rb', line 117

def self.audience
  lookup_auth_param :audience do
    lookup_local_constant :AUDIENCE
  end
end

.audience=(new_audience) ⇒ Object

Sets the default target audience ID to be used when none is provided during initialization.

Parameters:

  • new_audience (String) 


128
129
130
 
# File 'lib/googleauth/credentials.rb', line 128

def self.audience= new_audience
  @audience = new_audience
end

.default(options = {}) ⇒ Credentials

Creates a new Credentials instance with auth credentials acquired by searching the environment variables and paths configured on the class, and with the default values configured on the class.

The auth credentials are searched for in the following order:

  1. configured environment variables (see env_vars)

  2. configured default file paths (see paths)

  3. application default (see Google::Auth.get_application_default)

Parameters:

  • options (Hash) (defaults to: {}) —

    The options for configuring the credentials instance. The following is supported:

    • :scope - the scope for the client

    • “project_id” (and optionally “project”) - the project identifier for the client

    • :connection_builder - the connection builder to use for the client

    • :default_connection - the default connection to use for the client

Returns:



409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/googleauth/credentials.rb', line 409

def self.default options = {}
  # First try to find keyfile file or json from environment variables.
  client = from_env_vars options

  # Second try to find keyfile file from known file paths.
  client ||= from_default_paths options

  # Finally get instantiated client from Google::Auth
  client ||= from_application_default options
  client
end

.env_vars ⇒ Array<String>

The environment variables to search for credentials. Values can either be a file path to the credentials file, or the JSON contents of the credentials file. The env_vars will never be nil. If there are no vars, the empty array is returned.

Returns:

  • (Array<String>) 


199
200
201
 
# File 'lib/googleauth/credentials.rb', line 199

def self.env_vars
  env_vars_internal || []
end

.env_vars=(new_env_vars) ⇒ Object

Sets the environment variables to search for credentials. Setting to ‘nil` “unsets” the value, and defaults to the superclass (or to the empty array if there is no superclass).

Parameters:

  • new_env_vars (String, Array<String>, nil) 


223
224
225
226
 
# File 'lib/googleauth/credentials.rb', line 223

def self.env_vars= new_env_vars
  new_env_vars = Array new_env_vars unless new_env_vars.nil?
  @env_vars = new_env_vars
end

.env_vars_internal ⇒ Object

Internal recursive lookup for env_vars.



207
208
209
210
211
212
213
214
 
# File 'lib/googleauth/credentials.rb', line 207

def self.env_vars_internal
  lookup_auth_param :env_vars, :env_vars_internal do
    # Pull values when PATH_ENV_VARS or JSON_ENV_VARS constants exists.
    path_env_vars = lookup_local_constant :PATH_ENV_VARS
    json_env_vars = lookup_local_constant :JSON_ENV_VARS
    (Array(path_env_vars) + Array(json_env_vars)).flatten.uniq if path_env_vars || json_env_vars
  end
end

.lookup_auth_param(name, method_name = name) ⇒ Object

Return the given parameter value, defaulting up the class hierarchy.

First returns the value of the instance variable, if set. Next, calls the given block if provided. (This is generally used to look up legacy constant-based values.) Otherwise, calls the superclass method if present. Returns nil if all steps fail.

Parameters:

  • name (Symbol) —

    The parameter name

  • method_name (Symbol) (defaults to: name) —

    The lookup method name, if different

Returns:

  • (Object) —

    The value



276
277
278
279
280
281
282
 
# File 'lib/googleauth/credentials.rb', line 276

def self.lookup_auth_param name, method_name = name
  val = instance_variable_get "@#{name}".to_sym
  val = yield if val.nil? && block_given?
  return val unless val.nil?
  return superclass.send method_name if superclass.respond_to? method_name
  nil
end

.lookup_local_constant(name) ⇒ Object

Return the value of the given constant if it is defined directly in this class, or nil if not.

Parameters:

  • Name (Symbol) —

    of the constant

Returns:

  • (Object) —

    The value



292
293
294
 
# File 'lib/googleauth/credentials.rb', line 292

def self.lookup_local_constant name
  const_defined?(name, false) ? const_get(name) : nil
end

.paths ⇒ Array<String>

The file paths to search for credentials files. The paths will never be nil. If there are no paths, the empty array is returned.

Returns:

  • (Array<String>) 


234
235
236
 
# File 'lib/googleauth/credentials.rb', line 234

def self.paths
  paths_internal || []
end

.paths=(new_paths) ⇒ Object

Set the file paths to search for credentials files. Setting to ‘nil` “unsets” the value, and defaults to the superclass (or to the empty array if there is no superclass).

Parameters:

  • new_paths (String, Array<String>, nil) 


257
258
259
260
 
# File 'lib/googleauth/credentials.rb', line 257

def self.paths= new_paths
  new_paths = Array new_paths unless new_paths.nil?
  @paths = new_paths
end

.paths_internal ⇒ Object

Internal recursive lookup for paths.



242
243
244
245
246
247
248
 
# File 'lib/googleauth/credentials.rb', line 242

def self.paths_internal
  lookup_auth_param :paths, :paths_internal do
    # Pull in values if the DEFAULT_PATHS constant exists.
    vals = lookup_local_constant :DEFAULT_PATHS
    vals ? Array(vals).flatten.uniq : nil
  end
end

.scope ⇒ String, ...

The default scope to be used when none is provided during initialization. A scope is an access range defined by the authorization server. The scope can be a single value or a list of values.

Either #scope or #target_audience, but not both, should be non-nil. If #scope is set, this credential will produce access tokens. If #target_audience is set, this credential will produce ID tokens.

Returns:

  • (String, Array<String>, nil) 


143
144
145
146
147
148
 
# File 'lib/googleauth/credentials.rb', line 143

def self.scope
  lookup_auth_param :scope do
    vals = lookup_local_constant :SCOPE
    vals ? Array(vals).flatten.uniq : nil
  end
end

.scope=(new_scope) ⇒ Object

Sets the default scope to be used when none is provided during initialization.

Either #scope or #target_audience, but not both, should be non-nil. If #scope is set, this credential will produce access tokens. If #target_audience is set, this credential will produce ID tokens.

Parameters:

  • new_scope (String, Array<String>, nil) 


159
160
161
162
 
# File 'lib/googleauth/credentials.rb', line 159

def self.scope= new_scope
  new_scope = Array new_scope unless new_scope.nil?
  @scope = new_scope
end

.target_audience ⇒ String?

The default final target audience for ID tokens, to be used when none is provided during initialization.

Either #scope or #target_audience, but not both, should be non-nil. If #scope is set, this credential will produce access tokens. If #target_audience is set, this credential will produce ID tokens.

Returns:

  • (String, nil) 


174
175
176
 
# File 'lib/googleauth/credentials.rb', line 174

def self.target_audience
  lookup_auth_param :target_audience
end

.target_audience=(new_target_audience) ⇒ Object

Sets the default final target audience for ID tokens, to be used when none is provided during initialization.

Either #scope or #target_audience, but not both, should be non-nil. If #scope is set, this credential will produce access tokens. If #target_audience is set, this credential will produce ID tokens.

Parameters:

  • new_target_audience (String, nil) 


188
189
190
 
# File 'lib/googleauth/credentials.rb', line 188

def self.target_audience= new_target_audience
  @target_audience = new_target_audience
end

.token_credential_uri ⇒ String

The default token credential URI to be used when none is provided during initialization. The URI is the authorization server’s HTTP endpoint capable of issuing tokens and refreshing expired tokens.

Returns:

  • (String) 


96
97
98
99
100
 
# File 'lib/googleauth/credentials.rb', line 96

def self.token_credential_uri
  lookup_auth_param :token_credential_uri do
    lookup_local_constant :TOKEN_CREDENTIAL_URI
  end
end

.token_credential_uri=(new_token_credential_uri) ⇒ Object

Set the default token credential URI to be used when none is provided during initialization.

Parameters:

  • new_token_credential_uri (String) 


107
108
109
 
# File 'lib/googleauth/credentials.rb', line 107

def self.token_credential_uri= new_token_credential_uri
  @token_credential_uri = new_token_credential_uri
end