Ruby SDK for Castle

Castle adds real-time monitoring of your authentication stack, instantly notifying you and your users on potential account hijacks.

Installation

Add the castle-rb gem to your Gemfile

gem 'castle-rb'

Load and configure the library with your Castle API secret in an initializer or similar.

Castle.api_secret = 'YOUR_API_SECRET'

A Castle client instance will automatically be made available as castle in your Rails, Sinatra or Padrino controllers.

Tracking security events

track lets you record the security-related actions your users perform. The more actions you track, the more accurate Castle is in identifying fraudsters.

Event names and detail properties that have semantic meaning are prefixed $, and we handle them in special ways.

When you have access to a logged in user, set user_id to the same user identifier as when you initiated Castle.js.

castle.track(
  name: '$login.succeeded',
  user_id: user.id)

When you don't have access to a logged in user just omit user_id, typically when tracking $login.failed and $password_reset.requested. Instead, whenever you have access to the user-submitted form value, add this to the event details as $login.

castle.track(
  name: '$login.failed',
  details: {
    '$login' => 'johan@castle.io'
  })

Supported events

• $login.succeeded: Record when a user attempts to log in.
• $login.failed: Record when a user logs out.
• $logout.succeeded: Record when a user logs out.
• $registration.succeeded: Capture account creation, both when a user signs up as well as when created manually by an administrator.
• $registration.failed: Record when an account failed to be created.
• $challenge.requested: Record when a user is prompted with additional verification, such as two-factor authentication or a captcha.
• $challenge.succeeded: Record when additional verification was successful.
• $challenge.failed: Record when additional verification failed.
• $password_reset.requested: An attempt was made to reset a user’s password.
• $password_reset.succeeded: The user completed all of the steps in the password reset process and the password was successfully reset. Password resets do not required knowledge of the current password.
• $password_reset.failed: Use to record when a user failed to reset their password.
• $password_change.succeeded: Use to record when a user changed their password. This event is only logged when users change their own password.
• $password_change.failed: Use to record when a user failed to change their password.

Supported detail properties

• $login: The submitted email or username from when the user attempted to log in or reset their password. Useful when there is no user_id available.

Exceptions

Castle::Error will be thrown if the Castle API returns a 400 or a 500 level HTTP response. You can also choose to catch a more finegrained error.

begin
  castle.track(
    name: '$login.succeeded',
    user_id: user.id)
rescue Castle::Error => e
  puts e.message
end

Configuration

Castle.configure do |config|
  # Same as setting it through Castle.api_secret
  config.api_secret = 'secret'

  # Castle::RequestError is raised when timing out (default: 30.0)
  config.request_timeout = 2.0
end