class Ably::Realtime::Auth

Auth is responsible for authentication with {www.ably.com Ably} using basic or token authentication This {Ably::Realtime::Auth Realtime::Auth} class wraps the {Ably::Auth Synchronous Ably::Auth} class in an EventMachine friendly way using Deferrables for all IO. See {Ably::Auth Ably::Auth} for more information

Find out more about Ably authentication at: www.ably.com/docs/general/authentication/

@!attribute [r] client_id

(see Ably::Auth#client_id)

@!attribute [r] current_token_details

(see Ably::Auth#current_token_details)

@!attribute [r] token

(see Ably::Auth#token)

@!attribute [r] key

(see Ably::Auth#key)

@!attribute [r] key_name

(see Ably::Auth#key_name)

@!attribute [r] key_secret

(see Ably::Auth#key_secret)

@!attribute [r] options

(see Ably::Auth#options)

@!attribute [r] token_params

(see Ably::Auth#options)

@!attribute [r] using_basic_auth?

(see Ably::Auth#using_basic_auth?)

@!attribute [r] using_token_auth?

(see Ably::Auth#using_token_auth?)

@!attribute [r] token_renewable?

(see Ably::Auth#token_renewable?)

@!attribute [r] authentication_security_requirements_met?

(see Ably::Auth#authentication_security_requirements_met?)

Public Class Methods

new(client) click to toggle source
# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 49
def initialize(client)
  @client = client
  @auth_sync = client.rest_client.auth
end

Public Instance Methods

auth_header(&success_callback) click to toggle source

Auth header string used in HTTP requests to Ably Will reauthorize implicitly if required and capable

@return [Ably::Util::SafeDeferrable] @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 216
def auth_header(&success_callback)
  async_wrap(success_callback) do
    auth_header_sync
  end
end
auth_header_sync() click to toggle source

Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 225
def auth_header_sync
  auth_sync.auth_header
end
auth_params(&success_callback) click to toggle source

Auth params used in URI endpoint for Realtime connections Will reauthorize implicitly if required and capable

@return [Ably::Util::SafeDeferrable] @yield [Hash] Auth params for a new Realtime connection

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 235
def auth_params(&success_callback)
  fail_callback = lambda do |error, deferrable|
    logger.error { "Failed to authenticate: #{error}" }
    if error.kind_of?(Ably::Exceptions::BaseAblyException)
      # Use base exception if it exists carrying forward the status codes
      deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, nil, nil, error)
    else
      deferrable.fail Ably::Exceptions::AuthenticationFailed.new(error.message, 500, Ably::Exceptions::Codes::CLIENT_CONFIGURED_AUTHENTICATION_PROVIDER_REQUEST_FAILED)
    end
  end
  async_wrap(success_callback, fail_callback) do
    auth_params_sync
  end
end
auth_params_sync() click to toggle source

Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition @return [Hash] Auth params for a new Realtime connection

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 253
def auth_params_sync
  auth_sync.auth_params
end
authorise(*args, &block) click to toggle source

@deprecated Use {#authorize} instead

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 122
def authorise(*args, &block)
  logger.warn { "Auth#authorise is deprecated and will be removed in 1.0. Please use Auth#authorize instead" }
  authorize(*args, &block)
end
authorise_sync(*args) click to toggle source

@deprecated Use {#authorize_sync} instead

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 148
def authorise_sync(*args)
  logger.warn { "Auth#authorise_sync is deprecated and will be removed in 1.0. Please use Auth#authorize_sync instead" }
  authorize_sync(*args)
end
authorization_in_flight?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 143
def authorization_in_flight?
  @authorization_in_flight
end
authorize(token_params = nil, auth_options = nil) { |token| ... } click to toggle source

For new connections, ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary. If a connection is already established, the connection will be upgraded with a new token

In the event that a new token request is made, the provided options are used

@param (see Ably::Auth#authorize) @option (see Ably::Auth#authorize)

@return [Ably::Util::SafeDeferrable] @yield [Ably::Models::TokenDetails]

@example

# will issue a simple token request using basic auth
client = Ably::Rest::Client.new(key: 'key.id:secret')
client.auth.authorize do |token_details|
  token_details #=> Ably::Models::TokenDetails
end
# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 72
def authorize(token_params = nil, auth_options = nil, &success_callback)
  Ably::Util::SafeDeferrable.new(logger).tap do |authorize_method_deferrable|
    # Wrap the sync authorize method and wait for the result from the deferrable
    async_wrap do
      authorize_sync(token_params, auth_options)
    end.tap do |auth_operation|
      # Authorize operation succeeded and we have a new token, now let's perform inline authentication
      auth_operation.callback do |token|
        case connection.state.to_sym
        when :initialized, :disconnected, :suspended, :closed, :closing, :failed
          connection.connect
        when :connected
          perform_inline_auth token
        when :connecting
          # Fail all current connection attempts and try again with the new token, see #RTC8b
          connection.manager.release_and_establish_new_transport
        else
          logger.fatal { "Auth#authorize: unsupported state #{connection.state}" }
          authorize_method_deferrable.fail Ably::Exceptions::InvalidState.new("Unsupported state #{connection.state} for Auth#authorize")
          next
        end

        # Indicate success or failure based on response from realtime, see #RTC8b1
        auth_deferrable_resolved = false

        connection.unsafe_once(:connected, :update) do
          auth_deferrable_resolved = true
          authorize_method_deferrable.succeed token
        end
        connection.unsafe_once(:suspended, :closed, :failed) do |state_change|
          auth_deferrable_resolved = true
          authorize_method_deferrable.fail state_change.reason
        end
      end

      # Authorize failed, likely due to auth_url or auth_callback failing
      auth_operation.errback do |error|
        client.connection.transition_state_machine :failed, reason: error if error.kind_of?(Ably::Exceptions::IncompatibleClientId)
        authorize_method_deferrable.fail error
      end
    end

    # Call the block provided to this method upon success of this deferrable
    authorize_method_deferrable.callback do |token|
      yield token if block_given?
    end
  end
end
authorize_sync(token_params = nil, auth_options = nil) click to toggle source

Synchronous version of {#authorize}. See {Ably::Auth#authorize} for method definition Please note that authorize_sync will however not upgrade the current connection’s token as this requires an synchronous operation to send the new authentication details to Ably over a realtime connection

@param (see Ably::Auth#authorize) @option (see Ably::Auth#authorize) @return [Ably::Models::TokenDetails]

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 135
def authorize_sync(token_params = nil, auth_options = nil)
  @authorization_in_flight = true
  auth_sync.authorize(token_params, auth_options)
ensure
  @authorization_in_flight = false
end
create_token_request(token_params = {}, auth_options = {}, &success_callback) click to toggle source

Creates and signs a token request that can then subsequently be used by any client to request a token

@param (see Ably::Auth#create_token_request) @option (see Ably::Auth#create_token_request)

@return [Ably::Util::SafeDeferrable] @yield [Models::TokenRequest]

@example

client.auth.create_token_request({ ttl: 3600 }, id: 'asd.asd') do |token_request|
  token_request #=> Ably::Models::TokenRequest
end
# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 195
def create_token_request(token_params = {}, auth_options = {}, &success_callback)
  async_wrap(success_callback) do
    create_token_request_sync(token_params, auth_options)
  end
end
create_token_request_sync(token_params = {}, auth_options = {}) click to toggle source

Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition @param (see Ably::Auth#authorize) @option (see Ably::Auth#authorize) @return [Ably::Models::TokenRequest]

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 206
def create_token_request_sync(token_params = {}, auth_options = {})
  auth_sync.create_token_request(token_params, auth_options)
end
request_token(token_params = {}, auth_options = {}, &success_callback) click to toggle source

Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests

@param (see Ably::Auth#request_token) @option (see Ably::Auth#request_token)

@return [Ably::Util::SafeDeferrable] @yield [Ably::Models::TokenDetails]

@example

# simple token request using basic auth
client = Ably::Rest::Client.new(key: 'key.id:secret')
client.auth.request_token do |token_details|
  token_details #=> Ably::Models::TokenDetails
end
# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 168
def request_token(token_params = {}, auth_options = {}, &success_callback)
  async_wrap(success_callback) do
    request_token_sync(token_params, auth_options)
  end
end
request_token_sync(token_params = {}, auth_options = {}) click to toggle source

Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition @param (see Ably::Auth#authorize) @option (see Ably::Auth#authorize) @return [Ably::Models::TokenDetails]

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 179
def request_token_sync(token_params = {}, auth_options = {})
  auth_sync.request_token(token_params, auth_options)
end

Private Instance Methods

auth_sync() click to toggle source

The synchronous Auth class instanced by the Rest client @return [Ably::Auth]

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 260
def auth_sync
  @auth_sync
end
client() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 264
def client
  @client
end
perform_inline_auth(token) click to toggle source

Sends an AUTH ProtocolMessage on the existing connection triggering an inline AUTH process, see RTC8a

# File lib/submodules/ably-ruby/lib/ably/realtime/auth.rb, line 270
def perform_inline_auth(token)
  logger.debug { "Performing inline AUTH with Ably using token #{token}" }
  connection.send_protocol_message(
    action: Ably::Models::ProtocolMessage::ACTION.Auth.to_i,
    auth: { access_token: token.token }
  )
end