Class: Signet::OAuth2::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/signet/oauth_2/client.rb

Constant Summary collapse

OOB_MODES = 
%w(urn:ietf:wg:oauth:2.0:oob:auto urn:ietf:wg:oauth:2.0:oob oob)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Creates an OAuth 2.0 client.

Examples:

client = Signet::OAuth2::Client.new(
  :authorization_uri =>
    'https://example.server.com/authorization',
  :token_credential_uri =>
    'https://example.server.com/token',
  :client_id => 'anonymous',
  :client_secret => 'anonymous',
  :scope => 'example',
  :redirect_uri => 'https://example.client.com/oauth'
)

Parameters:

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

    The configuration parameters for the client.

    • :authorization_uri - The authorization server’s HTTP endpoint capable of authenticating the end-user and obtaining authorization.

    • :token_credential_uri - The authorization server’s HTTP endpoint capable of issuing tokens and refreshing expired tokens.

    • :client_id - A unique identifier issued to the client to identify itself to the authorization server.

    • :client_secret - A shared symmetric secret issued by the authorization server, which is used to authenticate the client.

    • :scope - The scope of the access request, expressed either as an Array or as a space-delimited String.

    • :state - An arbitrary string designed to allow the client to maintain state.

    • :code - The authorization code received from the authorization server.

    • :redirect_uri - The redirection URI used in the initial request.

    • :username - The resource owner’s username.

    • :password - The resource owner’s password.

    • :issuer - Issuer ID when using assertion profile

    • :person - Target user for assertions

    • :expiry - Number of seconds assertions are valid for

    • :signing_key - Signing key when using assertion profile

    • :refresh_token - The refresh token associated with the access token to be refreshed.

    • :access_token - The current access token for this client.

    • :id_token - The current ID token for this client.

    • :extension_parameters - When using an extension grant type, this the set of parameters used by that extension.

See Also:



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/signet/oauth_2/client.rb', line 91

def initialize(options={})
  @authorization_uri    = nil
  @token_credential_uri = nil
  @client_id            = nil
  @client_secret        = nil
  @code                 = nil
  @expires_at           = nil
  @expires_in           = nil
  @issued_at            = nil
  @issuer               = nil
  @password             = nil
  @principal            = nil
  @redirect_uri         = nil
  @scope                = nil
  @state                = nil
  @username             = nil
  self.update!(options)
end

Instance Attribute Details

#sub ⇒ Object

The target “sub” when issuing assertions. Used in some Admin SDK APIs.



558
559
560
 
# File 'lib/signet/oauth_2/client.rb', line 558

def sub
  @sub
end

Instance Method Details

#access_token ⇒ String

Returns the access token associated with this client.

Returns:

  • (String) —

    The access token.



673
674
675
 
# File 'lib/signet/oauth_2/client.rb', line 673

def access_token
  return @access_token ||= nil
end

#access_token=(new_access_token) ⇒ Object

Sets the access token associated with this client.

Parameters:

  • new_access_token (String) —

    The access token.



682
683
684
 
# File 'lib/signet/oauth_2/client.rb', line 682

def access_token=(new_access_token)
  @access_token = new_access_token
end

#additional_parameters ⇒ Hash

Returns the set of additional (non standard) parameters to be used by the client.

Returns:

  • (Hash) —

    The pass through parameters.



634
635
636
 
# File 'lib/signet/oauth_2/client.rb', line 634

def additional_parameters
  return @additional_parameters ||= {}
end

#additional_parameters=(new_additional_parameters) ⇒ Object

Sets additional (non standard) parameters to be used by the client.

Parameters:

  • new_additional_parameters (Hash) —

    The parameters.



643
644
645
646
647
648
649
650
 
# File 'lib/signet/oauth_2/client.rb', line 643

def additional_parameters=(new_additional_parameters)
  if new_additional_parameters.respond_to?(:to_hash)
    @additional_parameters = new_additional_parameters.to_hash
  else
    raise TypeError,
          "Expected Hash, got #{new_additional_parameters.class}."
  end
end

#audience ⇒ String

Returns the issuer ID associated with this client. Used only by the assertion grant type.

Returns:

  • (String) —

    Target audience ID.



518
519
520
 
# File 'lib/signet/oauth_2/client.rb', line 518

def audience
  return @audience
end

#audience=(new_audience) ⇒ Object

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

Parameters:

  • new_audience (String) —

    Target audience ID



528
529
530
 
# File 'lib/signet/oauth_2/client.rb', line 528

def audience=(new_audience)
  @audience = new_audience
end

#authorization_uri(options = {}) ⇒ Addressable::URI

Returns the authorization URI that the user should be redirected to.

Returns:

  • (Addressable::URI) —

    The authorization URI.

See Also:



249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/signet/oauth_2/client.rb', line 249

def authorization_uri(options={})
  # Normalize external input
  options = deep_hash_normalize(options)

  return nil if @authorization_uri == nil
  unless options[:response_type]
    options[:response_type] = :code
  end
  unless options[:access_type]
    options[:access_type] = :offline
  end
  options[:client_id] ||= self.client_id
  options[:redirect_uri] ||= self.redirect_uri
  if options[:prompt] && options[:approval_prompt]
    raise ArgumentError, "prompt and approval_prompt are mutually exclusive parameters"
  end
  if !options[:client_id]
    raise ArgumentError, "Missing required client identifier."
  end
  unless options[:redirect_uri]
    raise ArgumentError, "Missing required redirect URI."
  end
  if !options[:scope] && self.scope
    options[:scope] = self.scope.join(' ')
  end
  options[:state] = self.state unless options[:state]
  options.merge!(self.additional_parameters.merge(options[:additional_parameters] || {}))
  options.delete(:additional_parameters)
  options = Hash[options.map do |key, option|
    [key.to_s, option]
  end]
  uri = Addressable::URI.parse(
    ::Signet::OAuth2.generate_authorization_uri(
      @authorization_uri, options
    )
  )
  if uri.normalized_scheme != 'https'
    raise Signet::UnsafeOperationError,
      'Authorization endpoint must be protected by TLS.'
  end
  return uri
end

#authorization_uri=(new_authorization_uri) ⇒ Object

Sets the authorization URI for this client.

Parameters:

  • new_authorization_uri (Addressable::URI, Hash, String, #to_str) —

    The authorization URI.



297
298
299
 
# File 'lib/signet/oauth_2/client.rb', line 297

def authorization_uri=(new_authorization_uri)
  @authorization_uri = coerce_uri(new_authorization_uri)
end

#clear_credentials! ⇒ Object

Removes all credentials from the client.



809
810
811
812
813
814
815
816
817
818
 
# File 'lib/signet/oauth_2/client.rb', line 809

def clear_credentials!
  @access_token = nil
  @refresh_token = nil
  @id_token = nil
  @username = nil
  @password = nil
  @code = nil
  @issued_at = nil
  @expires_in = nil
end

#client_id ⇒ String

Returns the client identifier for this client.

Returns:

  • (String) —

    The client identifier.



332
333
334
 
# File 'lib/signet/oauth_2/client.rb', line 332

def client_id
  return @client_id
end

#client_id=(new_client_id) ⇒ Object

Sets the client identifier for this client.

Parameters:

  • new_client_id (String) —

    The client identifier.



341
342
343
 
# File 'lib/signet/oauth_2/client.rb', line 341

def client_id=(new_client_id)
  @client_id = new_client_id
end

#client_secret ⇒ String

Returns the client secret for this client.

Returns:

  • (String) —

    The client secret.



349
350
351
 
# File 'lib/signet/oauth_2/client.rb', line 349

def client_secret
  return @client_secret
end

#client_secret=(new_client_secret) ⇒ Object

Sets the client secret for this client.

Parameters:

  • new_client_secret (String) —

    The client secret.



358
359
360
 
# File 'lib/signet/oauth_2/client.rb', line 358

def client_secret=(new_client_secret)
  @client_secret = new_client_secret
end

#code ⇒ String

Returns the authorization code issued to this client. Used only by the authorization code access grant type.

Returns:

  • (String) —

    The authorization code.



419
420
421
 
# File 'lib/signet/oauth_2/client.rb', line 419

def code
  return @code
end

#code=(new_code) ⇒ Object

Sets the authorization code issued to this client. Used only by the authorization code access grant type.

Parameters:

  • new_code (String) —

    The authorization code.



429
430
431
 
# File 'lib/signet/oauth_2/client.rb', line 429

def code=(new_code)
  @code = new_code
end

#coerce_uri(incoming_uri) ⇒ Object

Addressable expects URIs formatted as hashes to come in with symbols as keys. Returns nil implicitly for the nil case.



320
321
322
323
324
325
326
 
# File 'lib/signet/oauth_2/client.rb', line 320

def coerce_uri(incoming_uri)
  if incoming_uri.is_a? Hash
    Addressable::URI.new(deep_hash_normalize(incoming_uri))
  elsif incoming_uri
    Addressable::URI.parse(incoming_uri)
  end
end

#decoded_id_token(public_key = nil, options = {}) ⇒ String

Returns the decoded ID token associated with this client.

Parameters:

  • public_key (OpenSSL::PKey::RSA, Object) (defaults to: nil) —

    The public key to use to verify the ID token. Skips verification if omitted.

Returns:

  • (String) —

    The decoded ID token.



711
712
713
714
715
716
717
718
719
720
 
# File 'lib/signet/oauth_2/client.rb', line 711

def decoded_id_token(public_key=nil, options = {})
  payload, _header = JWT.decode(self.id_token, public_key, !!public_key, options)
  if !payload.has_key?('aud')
    raise Signet::UnsafeOperationError, 'No ID token audience declared.'
  elsif payload['aud'] != self.client_id
    raise Signet::UnsafeOperationError,
      'ID token audience did not match Client ID.'
  end
  return payload
end

#expired? ⇒ TrueClass, FalseClass

Returns true if the access token has expired.

Returns:

  • (TrueClass, FalseClass) —

    The expiration state of the access token.



790
791
792
 
# File 'lib/signet/oauth_2/client.rb', line 790

def expired?
  return self.expires_at != nil && Time.now >= self.expires_at
end

#expires_at ⇒ Time

Returns the timestamp the access token will expire at.

Returns:

  • (Time) —

    The access token lifetime.



766
767
768
769
770
771
772
773
774
 
# File 'lib/signet/oauth_2/client.rb', line 766

def expires_at
  if @expires_at
    @expires_at
  elsif @issued_at && @expires_in
    return @issued_at + @expires_in
  else
    return nil
  end
end

#expires_at=(new_expires_at) ⇒ Object

Limits the lifetime of the access token as number of seconds since the Epoch

Parameters:

  • new_expires_at (String, Fixnum, Time) —

    The access token issuance time.



781
782
783
 
# File 'lib/signet/oauth_2/client.rb', line 781

def expires_at=(new_expires_at)
  @expires_at = normalize_timestamp(new_expires_at)
end

#expires_in ⇒ Fixnum

Returns the lifetime of the access token in seconds.

Returns:

  • (Fixnum) —

    The access token lifetime.



726
727
728
 
# File 'lib/signet/oauth_2/client.rb', line 726

def expires_in
  return @expires_in
end

#expires_in=(new_expires_in) ⇒ Object

Sets the lifetime of the access token in seconds. Resets the issued timestamp.

Parameters:

  • new_expires_in (String, Fixnum) —

    The access token lifetime.



736
737
738
739
740
741
742
743
 
# File 'lib/signet/oauth_2/client.rb', line 736

def expires_in=(new_expires_in)
  if new_expires_in != nil
    @expires_in = new_expires_in.to_i
    @issued_at = Time.now
  else
    @expires_in, @issued_at, @expires_at = nil, nil, nil
  end
end

#expires_within?(sec) ⇒ TrueClass, FalseClass

Returns true if the access token has expired or expires within the next n seconds

Parameters:

  • sec (Fixnum) —

    Max number of seconds from now where a token is still considered expired.

Returns:

  • (TrueClass, FalseClass) —

    The expiration state of the access token.



803
804
805
 
# File 'lib/signet/oauth_2/client.rb', line 803

def expires_within?(sec)
  return self.expires_at != nil && Time.now >= (self.expires_at - sec)
end

#expiry ⇒ Fixnum

Returns the number of seconds assertions are valid for Used only by the assertion grant type.

Returns:

  • (Fixnum) —

    Assertion expiry, in seconds



565
566
567
 
# File 'lib/signet/oauth_2/client.rb', line 565

def expiry
  return @expiry
end

#expiry=(new_expiry) ⇒ Object

Sets the number of seconds assertions are valid for Used only by the assertion grant type.

Parameters:

  • new_expiry (Fixnum, String) —

    Assertion expiry, in seconds



575
576
577
 
# File 'lib/signet/oauth_2/client.rb', line 575

def expiry=(new_expiry)
  @expiry = new_expiry ? new_expiry.to_i : nil
end

#extension_parameters ⇒ Hash

Returns the set of extension parameters used by the client. Used only by extension access grant types.

Returns:

  • (Hash) —

    The extension parameters.



611
612
613
 
# File 'lib/signet/oauth_2/client.rb', line 611

def extension_parameters
  return @extension_parameters ||= {}
end

#extension_parameters=(new_extension_parameters) ⇒ Object

Sets extension parameters used by the client. Used only by extension access grant types.

Parameters:

  • new_extension_parameters (Hash) —

    The parameters.



621
622
623
624
625
626
627
628
 
# File 'lib/signet/oauth_2/client.rb', line 621

def extension_parameters=(new_extension_parameters)
  if new_extension_parameters.respond_to?(:to_hash)
    @extension_parameters = new_extension_parameters.to_hash
  else
    raise TypeError,
      "Expected Hash, got #{new_extension_parameters.class}."
  end
end

#fetch_access_token(options = {}) ⇒ Object 



949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
 
# File 'lib/signet/oauth_2/client.rb', line 949

def fetch_access_token(options={})
  if self.token_credential_uri == nil
    raise ArgumentError, 'Missing token endpoint URI.'
  end

  options = deep_hash_normalize(options)

  client = options[:connection] ||= Faraday.default_connection
  url = Addressable::URI.parse(self.token_credential_uri).normalize.to_s
  parameters = self.generate_access_token_request(options)
  if client.is_a?(Faraday::Connection)
    response = client.post url,
      Addressable::URI.form_encode(parameters),
      { 'Content-Type' => 'application/x-www-form-urlencoded' }
    status = response.status.to_i
    body = response.body
    content_type = response.headers['Content-type']
  else
    # Hurley
    response = client.post url, parameters
    status = response.status_code.to_i
    body = response.body
    content_type = response.header[:content_type]
  end

  if status == 200
    return ::Signet::OAuth2.parse_credentials(body, content_type)
  elsif [400, 401, 403].include?(status)
    message = 'Authorization failed.'
    if body.to_s.strip.length > 0
      message += "  Server message:\n#{response.body.to_s.strip}"
    end
    raise ::Signet::AuthorizationError.new(
      message, :response => response
    )
  else
    message = "Unexpected status code: #{response.status}."
    if body.to_s.strip.length > 0
      message += "  Server message:\n#{response.body.to_s.strip}"
    end
    raise ::Signet::AuthorizationError.new(
      message, :response => response
    )
  end
end

#fetch_access_token!(options = {}) ⇒ Object 



995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
 
# File 'lib/signet/oauth_2/client.rb', line 995

def fetch_access_token!(options={})
  options = deep_hash_normalize(options)

  token_hash = self.fetch_access_token(options)
  if token_hash
    # No-op for grant types other than `authorization_code`.
    # An authorization code is a one-time use token and is immediately
    # revoked after usage.
    self.code = nil
    self.issued_at = Time.now
    self.update_token!(token_hash)
  end
  return token_hash
end

#fetch_protected_resource(options = {}) ⇒ Array

Transmits a request for a protected resource.

Examples:

# Using Net::HTTP
response = client.fetch_protected_resource(
  :uri => 'http://www.example.com/protected/resource'
)

Parameters:

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

    The configuration parameters for the request.

    • :request - A pre-constructed request. An OAuth 2 Authorization header will be added to it, as well as an explicit Cache-Control ‘no-store` directive.

    • :method - The HTTP method for the request. Defaults to ‘GET’.

    • :uri - The URI for the request.

    • :headers - The HTTP headers for the request.

    • :body - The HTTP body for the request.

    • :realm - The Authorization realm. See RFC 2617.

    • :connection - The HTTP connection to use. Must be of type Faraday::Connection.

Returns:

  • (Array) —

    The response object.



1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
 
# File 'lib/signet/oauth_2/client.rb', line 1118

def fetch_protected_resource(options={})
  options = deep_hash_normalize(options)

  options[:connection] ||= Faraday.default_connection
  request = self.generate_authenticated_request(options)
  request_env = request.to_env(options[:connection])
  request_env[:request] ||= request
  response = options[:connection].app.call(request_env)
  if response.status.to_i == 401
    # When accessing a protected resource, we only want to raise an
    # error for 401 responses.
    message = 'Authorization failed.'
    if response.body.to_s.strip.length > 0
      message += "  Server message:\n#{response.body.to_s.strip}"
    end
    raise ::Signet::AuthorizationError.new(
      message, :request => request, :response => response
    )
  else
    return response
  end
end

#generate_access_token_request(options = {}) ⇒ Array

Generates a request for token credentials.

Parameters:

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

    The configuration parameters for the request.

    • :code - The authorization code.

Returns:

  • (Array) —

    The request object.



918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
 
# File 'lib/signet/oauth_2/client.rb', line 918

def generate_access_token_request(options={})
  options = deep_hash_normalize(options)

  parameters = {"grant_type" => self.grant_type}
  case self.grant_type
  when 'authorization_code'
    parameters['code'] = self.code
    parameters['redirect_uri'] = self.redirect_uri
  when 'password'
    parameters['username'] = self.username
    parameters['password'] = self.password
  when 'refresh_token'
    parameters['refresh_token'] = self.refresh_token
  when 'urn:ietf:params:oauth:grant-type:jwt-bearer'
    parameters['assertion'] = self.to_jwt(options)
  else
    if self.redirect_uri
      # Grant type was intended to be `authorization_code` because of
      # the presence of the redirect URI.
      raise ArgumentError, 'Missing authorization code.'
    end
    parameters.merge!(self.extension_parameters)
  end
  parameters['client_id'] = self.client_id unless self.client_id.nil?
  parameters['client_secret'] = self.client_secret unless self.client_secret.nil?
  parameters['scope'] = options[:scope] if options[:scope]
  additional = self.additional_parameters.merge(options[:additional_parameters] || {})
  additional.each { |k, v| parameters[k.to_s] = v }
  parameters
end

#generate_authenticated_request(options = {}) ⇒ Faraday::Request

Generates an authenticated request for protected resources.

Parameters:

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

    The configuration parameters for the request.

    • :request - A pre-constructed request. An OAuth 2 Authorization header will be added to it, as well as an explicit Cache-Control ‘no-store` directive.

    • :method - The HTTP method for the request. Defaults to ‘GET’.

    • :uri - The URI for the request.

    • :headers - The HTTP headers for the request.

    • :body - The HTTP body for the request.

    • :realm - The Authorization realm. See RFC 2617.

Returns:

  • (Faraday::Request) —

    The request object.



1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
 
# File 'lib/signet/oauth_2/client.rb', line 1038

def generate_authenticated_request(options={})
  options = deep_hash_normalize(options)

  if self.access_token == nil
    raise ArgumentError, 'Missing access token.'
  end
  options = {
    :realm => nil
  }.merge(options)

  if options[:request].kind_of?(Faraday::Request)
    request = options[:request]
  else
    if options[:request].kind_of?(Array)
      method, uri, headers, body = options[:request]
    else
      method = options[:method] || :get
      uri = options[:uri]
      headers = options[:headers] || []
      body = options[:body] || ''
    end
    headers = headers.to_a if headers.kind_of?(Hash)
    request_components = {
      :method => method,
      :uri => uri,
      :headers => headers,
      :body => body
    }
    # Verify that we have all pieces required to return an HTTP request
    request_components.each do |(key, value)|
      unless value
        raise ArgumentError, "Missing :#{key} parameter."
      end
    end
    method = method.to_s.downcase.to_sym
    request = options[:connection].build_request(method.to_s.downcase.to_sym) do |req|
      req.url(Addressable::URI.parse(uri).normalize.to_s)
      req.headers = Faraday::Utils::Headers.new(headers)
      req.body = body
    end
  end

  request['Authorization'] = ::Signet::OAuth2.generate_bearer_authorization_header(
    self.access_token,
    options[:realm] ? [['realm', options[:realm]]] : nil
  )
  request['Cache-Control'] = 'no-store'
  return request
end

#grant_type ⇒ String

Returns the inferred grant type, based on the current state of the client object. Returns ‘“none”` if the client has insufficient information to make an in-band authorization request.

Returns:

  • (String) —

    The inferred grant type.



828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
 
# File 'lib/signet/oauth_2/client.rb', line 828

def grant_type
  @grant_type ||= nil
  if @grant_type
    return @grant_type
  else
    if self.code && self.redirect_uri
      'authorization_code'
    elsif self.refresh_token
      'refresh_token'
    elsif self.username && self.password
      'password'
    elsif self.issuer && self.signing_key
      'urn:ietf:params:oauth:grant-type:jwt-bearer'
    else
      # We don't have sufficient auth information, assume an out-of-band
      # authorization arrangement between the client and server, or an
      # extension grant type.
      nil
    end
  end
end

#grant_type=(new_grant_type) ⇒ Object 



850
851
852
853
854
855
856
857
858
 
# File 'lib/signet/oauth_2/client.rb', line 850

def grant_type=(new_grant_type)
  case new_grant_type
  when 'authorization_code', 'refresh_token',
      'password', 'client_credentials'
    @grant_type = new_grant_type
  else
    @grant_type = Addressable::URI.parse(new_grant_type)
  end
end

#id_token ⇒ String

Returns the ID token associated with this client.

Returns:

  • (String) —

    The ID token.



690
691
692
 
# File 'lib/signet/oauth_2/client.rb', line 690

def id_token
  return @id_token ||= nil
end

#id_token=(new_id_token) ⇒ Object

Sets the ID token associated with this client.

Parameters:

  • new_id_token (String) —

    The ID token.



699
700
701
 
# File 'lib/signet/oauth_2/client.rb', line 699

def id_token=(new_id_token)
  @id_token = new_id_token
end

#issued_at ⇒ Time

Returns the timestamp the access token was issued at.

Returns:

  • (Time) —

    The access token issuance time.



749
750
751
 
# File 'lib/signet/oauth_2/client.rb', line 749

def issued_at
  return @issued_at
end

#issued_at=(new_issued_at) ⇒ Object

Sets the timestamp the access token was issued at.

Parameters:

  • new_issued_at (String, Fixnum, Time) —

    The access token issuance time.



758
759
760
 
# File 'lib/signet/oauth_2/client.rb', line 758

def issued_at=(new_issued_at)
  @issued_at = normalize_timestamp(new_issued_at)
end

#issuer ⇒ String

Returns the issuer ID associated with this client. Used only by the assertion grant type.

Returns:

  • (String) —

    Issuer id.



499
500
501
 
# File 'lib/signet/oauth_2/client.rb', line 499

def issuer
  return @issuer
end

#issuer=(new_issuer) ⇒ Object

Sets the issuer ID associated with this client. Used only by the assertion grant type.

Parameters:

  • new_issuer (String) —

    Issuer ID (typical in email adddress form).



509
510
511
 
# File 'lib/signet/oauth_2/client.rb', line 509

def issuer=(new_issuer)
  @issuer = new_issuer
end

#password ⇒ String

Returns the password associated with this client. Used only by the resource owner password credential access grant type.

Returns:

  • (String) —

    The password.



480
481
482
 
# File 'lib/signet/oauth_2/client.rb', line 480

def password
  return @password
end

#password=(new_password) ⇒ Object

Sets the password associated with this client. Used only by the resource owner password credential access grant type.

Parameters:

  • new_password (String) —

    The password.



490
491
492
 
# File 'lib/signet/oauth_2/client.rb', line 490

def password=(new_password)
  @password = new_password
end

#principal ⇒ String Also known as: person

Returns the target resource owner for impersonation. Used only by the assertion grant type.

Returns:

  • (String) —

    Target user for impersonation.



537
538
539
 
# File 'lib/signet/oauth_2/client.rb', line 537

def principal
  return @principal
end

#principal=(new_person) ⇒ Object Also known as: person=

Sets the target resource owner for impersonation. Used only by the assertion grant type.

Parameters:

  • new_person (String) —

    Target user for impersonation



547
548
549
 
# File 'lib/signet/oauth_2/client.rb', line 547

def principal=(new_person)
  @principal = new_person
end

#redirect_uri ⇒ String

Returns the redirect URI for this client.

Returns:

  • (String) —

    The redirect URI.



437
438
439
 
# File 'lib/signet/oauth_2/client.rb', line 437

def redirect_uri
  return @redirect_uri
end

#redirect_uri=(new_redirect_uri) ⇒ Object

Sets the redirect URI for this client.

Parameters:

  • new_redirect_uri (String) —

    The redirect URI.



446
447
448
449
450
451
452
453
454
 
# File 'lib/signet/oauth_2/client.rb', line 446

def redirect_uri=(new_redirect_uri)
  new_redirect_uri = Addressable::URI.parse(new_redirect_uri)
  #TODO - Better solution to allow google postmessage flow. For now, make an exception to the spec.
  if new_redirect_uri == nil|| new_redirect_uri.absolute? || uri_is_postmessage?(new_redirect_uri) || uri_is_oob?(new_redirect_uri)
    @redirect_uri = new_redirect_uri
  else
    raise ArgumentError, "Redirect URI must be an absolute URI."
  end
end

#refresh!(options = {}) ⇒ Object

Refresh the access token, if possible



1012
1013
1014
1015
1016
 
# File 'lib/signet/oauth_2/client.rb', line 1012

def refresh!(options={})
  options = deep_hash_normalize(options)

  self.fetch_access_token!(options)
end

#refresh_token ⇒ String

Returns the refresh token associated with this client.

Returns:

  • (String) —

    The refresh token.



656
657
658
 
# File 'lib/signet/oauth_2/client.rb', line 656

def refresh_token
  return @refresh_token ||= nil
end

#refresh_token=(new_refresh_token) ⇒ Object

Sets the refresh token associated with this client.

Parameters:

  • new_refresh_token (String) —

    The refresh token.



665
666
667
 
# File 'lib/signet/oauth_2/client.rb', line 665

def refresh_token=(new_refresh_token)
  @refresh_token = new_refresh_token
end

#scope ⇒ Array

Returns the scope for this client. Scope is a list of access ranges defined by the authorization server.

Returns:

  • (Array) —

    The scope of access the client is requesting.



367
368
369
 
# File 'lib/signet/oauth_2/client.rb', line 367

def scope
  return @scope
end

#scope=(new_scope) ⇒ Object

Sets the scope for this client.

Parameters:

  • new_scope (Array, String) —

    The scope of access the client is requesting. This may be expressed as either an Array of String objects or as a space-delimited String.



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/signet/oauth_2/client.rb', line 378

def scope=(new_scope)
  case new_scope
  when Array
    new_scope.each do |scope|
      if scope.include?(' ')
        raise ArgumentError,
          "Individual scopes cannot contain the space character."
      end
    end
    @scope = new_scope
  when String
    @scope = new_scope.split(' ')
  when nil
    @scope = nil
  else
    raise TypeError, "Expected Array or String, got #{new_scope.class}"
  end
end

#signing_algorithm ⇒ String

Algorithm used for signing JWTs

Returns:

  • (String) —

    Signing algorithm



602
603
604
 
# File 'lib/signet/oauth_2/client.rb', line 602

def signing_algorithm
  self.signing_key.is_a?(String) ? "HS256" : "RS256"
end

#signing_key ⇒ String, OpenSSL::PKey

Returns the signing key associated with this client. Used only by the assertion grant type.

Returns:

  • (String, OpenSSL::PKey) —

    Signing key



585
586
587
 
# File 'lib/signet/oauth_2/client.rb', line 585

def signing_key
  return @signing_key
end

#signing_key=(new_key) ⇒ Object

Sets the signing key when issuing assertions. Used only by the assertion grant type.

Parameters:

  • new_key (String, OpenSSL::Pkey) —

    Signing key. Either private key for RSA or string for HMAC algorithm



595
596
597
 
# File 'lib/signet/oauth_2/client.rb', line 595

def signing_key=(new_key)
  @signing_key = new_key
end

#state ⇒ String

Returns the client’s current state value.

Returns:

  • (String) —

    The state value.



401
402
403
 
# File 'lib/signet/oauth_2/client.rb', line 401

def state
  return @state
end

#state=(new_state) ⇒ Object

Sets the client’s current state value.

Parameters:

  • new_state (String) —

    The state value.



410
411
412
 
# File 'lib/signet/oauth_2/client.rb', line 410

def state=(new_state)
  @state = new_state
end

#to_json ⇒ String

Note:

A serialized client contains sensitive information. Persist or transmit with care.

Serialize the client object to JSON.

Returns:

  • (String) —

    A serialized JSON representation of the client.



883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
 
# File 'lib/signet/oauth_2/client.rb', line 883

def to_json
  return MultiJson.dump({
    'authorization_uri' => self.authorization_uri ? self.authorization_uri.to_s : nil,
    'token_credential_uri' => self.token_credential_uri ? self.token_credential_uri.to_s : nil,
    'client_id' => self.client_id,
    'client_secret' => self.client_secret,
    'scope' => self.scope,
    'state' => self.state,
    'code' => self.code,
    'redirect_uri' => self.redirect_uri ? self.redirect_uri.to_s : nil,
    'username' => self.username,
    'password' => self.password,
    'issuer' => self.issuer,
    'audience' => self.audience,
    'person' => self.person,
    'expiry' => self.expiry,
    'expires_at' => self.expires_at ? self.expires_at.to_i : nil,
    'signing_key' => self.signing_key,
    'refresh_token' => self.refresh_token,
    'access_token' => self.access_token,
    'id_token' => self.id_token,
    'extension_parameters' => self.extension_parameters
  })
end

#to_jwt(options = {}) ⇒ Object 



860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
 
# File 'lib/signet/oauth_2/client.rb', line 860

def to_jwt(options={})
  options = deep_hash_normalize(options)

  now = Time.new
  skew = options[:skew] || 60
  assertion = {
    "iss" => self.issuer,
    "aud" => self.audience,
    "exp" => (now + self.expiry).to_i,
    "iat" => (now - skew).to_i
  }
  assertion['scope'] = self.scope.join(' ') unless self.scope.nil?
  assertion['prn'] = self.person unless self.person.nil?
  assertion['sub'] = self.sub unless self.sub.nil?
  JWT.encode(assertion, self.signing_key, self.signing_algorithm)
end

#token_credential_uri ⇒ Addressable::URI

Returns the token credential URI for this client.

Returns:

  • (Addressable::URI) —

    The token credential URI.



305
306
307
 
# File 'lib/signet/oauth_2/client.rb', line 305

def token_credential_uri
  return @token_credential_uri
end

#token_credential_uri=(new_token_credential_uri) ⇒ Object

Sets the token credential URI for this client.

Parameters:

  • new_token_credential_uri (Addressable::URI, Hash, String, #to_str) —

    The token credential URI.



314
315
316
 
# File 'lib/signet/oauth_2/client.rb', line 314

def token_credential_uri=(new_token_credential_uri)
  @token_credential_uri = coerce_uri(new_token_credential_uri)
end

#update!(options = {}) ⇒ Object

Updates an OAuth 2.0 client.

Examples:

client.update!(
  :code => 'i1WsRn1uB1',
  :access_token => 'FJQbwq9',
  :expires_in => 3600
)

Parameters:

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

    The configuration parameters for the client.

    • :authorization_uri - The authorization server’s HTTP endpoint capable of authenticating the end-user and obtaining authorization.

    • :token_credential_uri - The authorization server’s HTTP endpoint capable of issuing tokens and refreshing expired tokens.

    • :client_id - A unique identifier issued to the client to identify itself to the authorization server.

    • :client_secret - A shared symmetric secret issued by the authorization server, which is used to authenticate the client.

    • :scope - The scope of the access request, expressed either as an Array or as a space-delimited String.

    • :state - An arbitrary string designed to allow the client to maintain state.

    • :code - The authorization code received from the authorization server.

    • :redirect_uri - The redirection URI used in the initial request.

    • :username - The resource owner’s username.

    • :password - The resource owner’s password.

    • :issuer - Issuer ID when using assertion profile

    • :audience - Target audience for assertions

    • :person - Target user for assertions

    • :expiry - Number of seconds assertions are valid for

    • :signing_key - Signing key when using assertion profile

    • :refresh_token - The refresh token associated with the access token to be refreshed.

    • :access_token - The current access token for this client.

    • :id_token - The current ID token for this client.

    • :extension_parameters - When using an extension grant type, this is the set of parameters used by that extension.

See Also:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/signet/oauth_2/client.rb', line 170

def update!(options={})
  # Normalize all keys to symbols to allow indifferent access.
  options = deep_hash_normalize(options)

  self.authorization_uri = options[:authorization_uri] if options.has_key?(:authorization_uri)
  self.token_credential_uri = options[:token_credential_uri] if options.has_key?(:token_credential_uri)
  self.client_id = options[:client_id] if options.has_key?(:client_id)
  self.client_secret = options[:client_secret] if options.has_key?(:client_secret)
  self.scope = options[:scope] if options.has_key?(:scope)
  self.state = options[:state] if options.has_key?(:state)
  self.code = options[:code] if options.has_key?(:code)
  self.redirect_uri = options[:redirect_uri] if options.has_key?(:redirect_uri)
  self.username = options[:username] if options.has_key?(:username)
  self.password = options[:password] if options.has_key?(:password)
  self.issuer = options[:issuer] if options.has_key?(:issuer)
  self.person = options[:person] if options.has_key?(:person)
  self.sub = options[:sub] if options.has_key?(:sub)
  self.expiry = options[:expiry] || 60
  self.audience = options[:audience] if options.has_key?(:audience)
  self.signing_key = options[:signing_key] if options.has_key?(:signing_key)
  self.extension_parameters = options[:extension_parameters] || {}
  self.additional_parameters = options[:additional_parameters] || {}
  self.update_token!(options)
  return self
end

#update_token!(options = {}) ⇒ Object

Updates an OAuth 2.0 client.

Examples:

client.update!(
  :refresh_token => 'n4E9O119d',
  :access_token => 'FJQbwq9',
  :expires_in => 3600
)

Parameters:

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

    The configuration parameters related to the token.

    • :refresh_token - The refresh token associated with the access token to be refreshed.

    • :access_token - The current access token for this client.

    • :id_token - The current ID token for this client.

    • :expires_in - The time in seconds until access token expiration.

    • :expires_at - The time as an integer number of seconds since the Epoch

    • :issued_at - The timestamp that the token was issued at.

See Also:



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/signet/oauth_2/client.rb', line 224

def update_token!(options={})
  # Normalize all keys to symbols to allow indifferent access internally
  options = deep_hash_normalize(options)

  self.expires_in = options[:expires] if options.has_key?(:expires)
  self.expires_in = options[:expires_in] if options.has_key?(:expires_in)
  self.expires_at = options[:expires_at] if options.has_key?(:expires_at)

  # By default, the token is issued at `Time.now` when `expires_in` is
  # set, but this can be used to supply a more precise time.
  self.issued_at = options[:issued_at] if options.has_key?(:issued_at)

  self.access_token = options[:access_token] if options.has_key?(:access_token)
  self.refresh_token = options[:refresh_token] if options.has_key?(:refresh_token)
  self.id_token = options[:id_token] if options.has_key?(:id_token)

  return self
end

#username ⇒ String

Returns the username associated with this client. Used only by the resource owner password credential access grant type.

Returns:

  • (String) —

    The username.



461
462
463
 
# File 'lib/signet/oauth_2/client.rb', line 461

def username
  return @username
end

#username=(new_username) ⇒ Object

Sets the username associated with this client. Used only by the resource owner password credential access grant type.

Parameters:

  • new_username (String) —

    The username.



471
472
473
 
# File 'lib/signet/oauth_2/client.rb', line 471

def username=(new_username)
  @username = new_username
end