signet - Class Signet::OAuth2::Client (v0.20.0)

Reference documentation and code samples for the signet class Signet::OAuth2::Client.

Inherits

  • Object

Methods

#access_token

def access_token() -> String

Returns the access token associated with this client.

Returns
  • (String) — The access token.

#access_token=

def access_token=(new_access_token)

Sets the access token associated with this client.

Parameter
  • new_access_token (String) — The access token.

#access_type

def access_type() -> String, Symbol

Returns the current access type parameter for #authorization_uri.

Returns
  • (String, Symbol) — The current access type.

#access_type=

def access_type=(new_access_type)

Sets the current access type parameter for #authorization_uri.

Parameter
  • new_access_type (String, Symbol) — The current access type.

#additional_parameters

def additional_parameters() -> Hash

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

Returns
  • (Hash) — The pass through parameters.

#additional_parameters=

def additional_parameters=(new_additional_parameters)

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

Parameter
  • new_additional_parameters (Hash) — The parameters.

#audience

def audience() -> String

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

Returns
  • (String) — Target audience ID.

#audience=

def audience=(new_audience)

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

Parameter
  • new_audience (String) — Target audience ID

#authorization_uri

def authorization_uri(options = {}) -> Addressable::URI

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

Returns
  • (Addressable::URI) — The authorization URI.
Raises
  • (ArgumentError)

#authorization_uri=

def authorization_uri=(new_authorization_uri)

Sets the authorization URI for this client.

Parameter
  • new_authorization_uri (Addressable::URI, Hash, String, #to_str) — The authorization URI.

#clear_credentials!

def clear_credentials!()

Removes all credentials from the client.

#client_id

def client_id() -> String

Returns the client identifier for this client.

Returns
  • (String) — The client identifier.

#client_id=

def client_id=(new_client_id)

Sets the client identifier for this client.

Parameter
  • new_client_id (String) — The client identifier.

#client_secret

def client_secret() -> String

Returns the client secret for this client.

Returns
  • (String) — The client secret.

#client_secret=

def client_secret=(new_client_secret)

Sets the client secret for this client.

Parameter
  • new_client_secret (String) — The client secret.

#code

def code() -> String

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

Returns
  • (String) — The authorization code.

#code=

def code=(new_code)

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

Parameter
  • new_code (String) — The authorization code.

#coerce_uri

def coerce_uri(incoming_uri)

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

#decoded_id_token

def decoded_id_token(public_key = nil, options = {}) -> String

Returns the decoded ID token associated with this client.

Parameter
  • public_key (OpenSSL::PKey::RSA, Object) — The public key to use to verify the ID token. Skips verification if omitted.
Returns
  • (String) — The decoded ID token.
Raises

#expired?

def expired?() -> TrueClass, FalseClass

Returns true if the access token has expired. Returns false if the token has not expired or has an nil @expires_at.

Returns
  • (TrueClass, FalseClass) — The expiration state of the access token.

#expires_at

def expires_at() -> Time, nil

Returns the timestamp the access token will expire at. Returns nil if the token does not expire.

Returns
  • (Time, nil) — The access token lifetime.

#expires_at=

def expires_at=(new_expires_at)

Limits the lifetime of the access token as number of seconds since the Epoch. Nil values will be treated as though the token does not expire.

Parameter
  • new_expires_at (String, Integer, Time, nil) — The access token expiration time.

#expires_in

def expires_in() -> Integer, nil

Returns the lifetime of the access token in seconds. Returns nil if the token does not expire.

Returns
  • (Integer, nil) — The access token lifetime.

#expires_in=

def expires_in=(new_expires_in)

Sets the lifetime of the access token in seconds. Resets the issued_at timestamp. Nil values will be treated as though the token does not expire.

Parameter
  • new_expires_in (String, Integer, nil) — The access token lifetime.

#expires_within?

def expires_within?(sec) -> TrueClass, FalseClass

Returns true if the access token has expired or expires within the next n seconds. Returns false for tokens with a nil @expires_at.

Parameter
  • sec (Integer) — Max number of seconds from now where a token is still considered expired.
Returns
  • (TrueClass, FalseClass) — The expiration state of the access token.

#expiry

def expiry() -> Integer

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

Returns
  • (Integer) — Assertion expiry, in seconds

#expiry=

def expiry=(new_expiry)

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

Parameter
  • new_expiry (Integer, String) — Assertion expiry, in seconds

#extension_parameters

def 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.

#extension_parameters=

def extension_parameters=(new_extension_parameters)

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

Parameter
  • new_extension_parameters (Hash) — The parameters.

#fetch_access_token

def fetch_access_token(options = {})
Raises
  • (ArgumentError)

#fetch_access_token!

def fetch_access_token!(options = {})

#fetch_protected_resource

def fetch_protected_resource(options = {}) -> Array

Transmits a request for a protected resource.

Parameter
  • options (Hash) —

    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.
Raises
Example 
# Using Net::HTTP
response = client.fetch_protected_resource(
  :uri => 'http://www.example.com/protected/resource'
)

#generate_authenticated_request

def generate_authenticated_request(options = {}) -> Faraday::Request

Generates an authenticated request for protected resources.

Parameter
  • options (Hash) —

    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.
Raises
  • (ArgumentError)

#grant_type

def 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.

#grant_type=

def grant_type=(new_grant_type)

#granted_scopes

def granted_scopes() -> Array, nil

Returns the scopes granted by the authorization server.

Returns
  • (Array, nil) — The scope of access returned by the authorization server.

#granted_scopes=

def granted_scopes=(new_granted_scopes)

Sets the scopes returned by authorization server for this client.

Parameter
  • new_granted_scopes (String, Array, nil) — The scope of access returned by authorization server. This will ideally be expressed as space-delimited String.

#id_token

def id_token() -> String

Returns the ID token associated with this client.

Returns
  • (String) — The ID token.

#id_token=

def id_token=(new_id_token)

Sets the ID token associated with this client.

Parameter
  • new_id_token (String) — The ID token.

#initialize

def initialize(options = {}) -> Client

Creates an OAuth 2.0 client.

Parameter
  • options (Hash) —

    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.
    • :target_audience - The final target audience for ID tokens fetched by this client, as a 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.
    • :granted_scopes - All scopes granted by authorization server.
Returns
  • (Client) — a new instance of Client
Example 
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'
)

#issued_at

def issued_at() -> Time, nil

Returns the timestamp the access token was issued at.

Returns
  • (Time, nil) — The access token issuance time.

#issued_at=

def issued_at=(new_issued_at)

Sets the timestamp the access token was issued at.

Parameter
  • new_issued_at (String, Integer, Time) — The access token issuance time.

#issuer

def issuer() -> String

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

Returns
  • (String) — Issuer id.

#issuer=

def issuer=(new_issuer)

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

Parameter
  • new_issuer (String) — Issuer ID (typical in email adddress form).

#password

def password() -> String

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

Returns
  • (String) — The password.

#password=

def password=(new_password)

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

Parameter
  • new_password (String) — The password.

#person

def person() -> String
Alias Of: #principal

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

Returns
  • (String) — Target user for impersonation.

#person=

def person=(new_person)
Alias Of: #principal=

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

Parameter
  • new_person (String) — Target user for impersonation

#principal

def principal() -> String
Aliases

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

Returns
  • (String) — Target user for impersonation.

#principal=

def principal=(new_person)
Aliases

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

Parameter
  • new_person (String) — Target user for impersonation

#redirect_uri

def redirect_uri() -> String

Returns the redirect URI for this client.

Returns
  • (String) — The redirect URI.

#redirect_uri=

def redirect_uri=(new_redirect_uri)

Sets the redirect URI for this client.

Parameter
  • new_redirect_uri (String) — The redirect URI.

#refresh!

def refresh!(options = {})

Refresh the access token, if possible

#refresh_token

def refresh_token() -> String

Returns the refresh token associated with this client.

Returns
  • (String) — The refresh token.

#refresh_token=

def refresh_token=(new_refresh_token)

Sets the refresh token associated with this client.

Parameter
  • new_refresh_token (String) — The refresh token.

#scope

def 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.

#scope=

def scope=(new_scope)

Sets the scope for this client.

Parameter
  • 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.

#signing_algorithm

def signing_algorithm() -> String

Algorithm used for signing JWTs

Returns
  • (String) — Signing algorithm

#signing_key

def 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

#signing_key=

def signing_key=(new_key)

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

Parameter
  • new_key (String, OpenSSL::Pkey) — Signing key. Either private key for RSA or string for HMAC algorithm

#state

def state() -> String

Returns the client's current state value.

Returns
  • (String) — The state value.

#state=

def state=(new_state)

Sets the client's current state value.

Parameter
  • new_state (String) — The state value.

#sub

def sub()

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

#sub=

def sub=(value)

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

#target_audience

def target_audience() -> String

Returns the final target audience for ID tokens fetched by this client.

Returns
  • (String) — The target audience.

#target_audience=

def target_audience=(new_target_audience)

Sets the final target audience for ID tokens fetched by this client.

Parameter
  • new_target_audience (String) — The new target audience.

#to_json

def to_json(*_args) -> String

Serialize the client object to JSON.

Returns
  • (String) — A serialized JSON representation of the client.

#to_jwt

def to_jwt(options = {})

#token_credential_uri

def token_credential_uri() -> Addressable::URI

Returns the token credential URI for this client.

Returns
  • (Addressable::URI) — The token credential URI.

#token_credential_uri=

def token_credential_uri=(new_token_credential_uri)

Sets the token credential URI for this client.

Parameter
  • new_token_credential_uri (Addressable::URI, Hash, String, #to_str) — The token credential URI.

#update!

def update!(options = {})

Updates an OAuth 2.0 client.

Parameter
  • options (Hash) —

    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.
    • :target_audience - The final target audience for ID tokens fetched by this client, as a 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.
    • :access_type - The current access type parameter for #authorization_uri.
    • :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.
    • :granted_scopes - All scopes granted by authorization server.
Example 
client.update!(
  :code => 'i1WsRn1uB1',
  :access_token => 'FJQbwq9',
  :expires_in => 3600
)

#update_token!

def update_token!(options = {})

Updates an OAuth 2.0 client.

Parameter
  • options (Hash) —

    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.
Example 
client.update!(
  :refresh_token => 'n4E9O119d',
  :access_token => 'FJQbwq9',
  :expires_in => 3600
)

#username

def username() -> String

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

Returns
  • (String) — The username.

#username=

def username=(new_username)

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

Parameter
  • new_username (String) — The username.

Constants

OOB_MODES

value: ["urn:ietf:wg:oauth:2.0:oob:auto", "urn:ietf:wg:oauth:2.0:oob", "oob"].freeze