Trusona Ruby SDK

Easily interact with the Trusona REST API.

Current Status

Requirements

The Trusona SDK requires Ruby version 2.4.0 or higher.

Usage

• Installation
• Configuration
• Device and User Bindings
• Trusonafications
• Devices
• Users
• TruCodes

Installation

The recommended way to add the Trusona gem to your project is to use bundler. To add Trusona to your project, add the following line to your Gemfile.

gem 'trusona'

After adding the line to your Gemfile, running bundle install will install it.

The Trusona gem uses semantic versioning, so it is generally a good idea to lock in the major version in your Gemfile before deploying to production.

Configuration

Configuring the Trusona gem is easy. We recommend using environment variables and a tool like dotenv for managing those environment variables.

Trusona.config do |c|
  c.secret         = ENV['TRUSONA_SECRET']
  c.token          = ENV['TRUSONA_TOKEN']
end

The value of each required configuration parameter are provided by Trusona.

Device and User Bindings

Before Trusonafications can be created for a user, the device registered with the Trusona Mobile SDK must be bound to a unique-to-you user identifier. The user identifier can be any value that helps you uniquely identify the user in your system.

Once this binding has been created, the user should be made to verify their account with your system. This may include:

• Email verification
• Logging in with existing credentials
• Answering security questions

Once the account has been verified, the Device and User Binding must be activated, which is your way of telling Trusona that this user is ready to accept Trusonafications.

Creating a Device and User Binding

The binding requires two values, the user identifier that helps you identify the user in your system and the device identifier as generated by the Trusona Mobile SDK on the user's device.

  binding = Trusona::DeviceUserBinding.create(
    user: '83452353-4F7B-4CA2-BBCD-57ACE7279EA0',
    device: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
  )

Activating a Device and User Binding

  # create the binding
  binding = Trusona::DeviceUserBinding.create(
    user: '83452353-4F7B-4CA2-BBCD-57ACE7279EA0',
    device: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
  )

  # go verify the user...

  # activate the binding
  Trusona::DeviceUserBinding.activate(id: binding.id)

Creating Trusonafications

Creating an Essential Trusonafication

  Trusona::EssentialTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
   })

By default, Essential Trusonafications are built such that the user's presence is required and a prompt asking the user to "Accept" or "Reject" the Trusonafication is presented by the Trusona Mobile SDK. A user's presence is determined by their ability to interact with the device's OS Security, usually by using a biometric or entering the device passcode.

Creating an Essential Trusonafication, without user presence or a prompt

  Trusona::EssentialTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI',
    user_presence: false,
    prompt: false
   })

In the above example, the addition of user_presence: false and prompt: false will result in a Trusonafication that can be accepted solely with possession of the device.

Creating an Essential Trusonafication, with the user's email address

  Trusona::EssentialTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    email: 'user@domain.com'
   })

In some cases you may be able to send a Trusonafication to a user by specifying their email address. This is the case if one of the following is true:

• You have verified ownership of a domain through the Trusona Developer's site
• You have an agreement with Trusona allowing you to send Trusonafications to any email address. Creating a Trusonafication with an email address is similar to the other use cases, except you use the email parameter rather than user_identifier or device_identifier.

Adding custom fields to a Trusonafication

  Trusona::ExecutiveTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'Vdza6-JQMfAJePj2H69oMn1YTyXTu73IiYt9oBa3kj',
    custom_fields: { greeting: 'hello!', last_login: false }
  })

If you are using the mobile SDK to build a custom app that integrates with Trusona, you have the option of including additional data on the Trusonafication which the app can use to affect its behavior.

For example, you may want to include additional context on the Trusonafication prompt.

You can add these custom fields by including a custom_fields hash as shown above.

The custom fields will then be available in the Trusonafication received by the SDK.

Note that the custom fields are not used in the case that the Trusonafication is being handled by the Trusona app.

An Executive level Trusonafication

  Trusona::ExecutiveTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
   })

Trusonafication Options

Name	Parameter Name	Required	Description
Action	action	Y	The action you want the user to take (e.g. 'login', 'verify')
Resource	resource	Y	The resource to which the user is performing the action (e.g. 'website', 'account')
Device Identifier	device_identifier	N1	The device identifier, retrieved from the mobile SDK, of the device to which this Trusonafication will be sent.
User Identifier	user_identifier	N1	The user identifier that has been registered with Trusona.
Tru Code ID	trucode_id	N1	A Tru Code ID that has/will be paired by a device using the Trusona Mobile SDK that can be used to lookup the device_identifier
User Presence	user_presence	N	Should the user be required to demonstrate presence (e.g. via Biometric) when accepting this Trusonafication? Defaults to true.
Prompt	prompt	N	Should the user be prompted to Accept or Reject this Trusonafication? Defaults to true.
Expiration	expires_at	N	The ISO-8601 UTC timestamp of the Trusonafication's expiration. Defaults to 90 seconds from creation.
Custom Fields	custom_fields	N	Arbitrary key-value data fields made available to the Trusonafication. Amount of data in the hash is limited to 1MB
Callback URL	callback_url	N	A HTTPS URL to POST to when the trusonafication has been completed (accepted, rejected, or expired). NOTE: The URL should include a randomized segment so it cannot be guessed and abused by third-parties e.g. https://your.domain.com/completed_authentications/f8abe61d-4e51-493f-97b1-464c157624f2.

Retrieving an existing Trusonafication

After creating a Trusonafication, you can fetch that Trusonafication using the id.

  trusonafication = Trusona::EssentialTrusonafication.create(params: {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
   })

   # ...

   updated = Trusona::Trusonafication.find(trusonafication.id)

Automatically polling for Trusonafication status

Sometimes, you want to send a Trusonafication and wait for its completion by the user before proceeding. This can be accomplished by passing a block, and optional timeout, when creating a Trusonafication.

  params = {
    action: 'login',
    resource: 'Acme Bank',
    device_identifier: 'PBanKaajTmz_Cq1pDkrRzyeISBSBoGjExzp5r6-UjcI'
  }

  Trusona::EssentialTrusonafication.create(params: params) do | trusonafication |
    # Block will be executed when the user has acted on the Trusonafication
    # OR when the Trusonafication has expired.

    if trusonafication.accepted?
      # start the parade
    end
  end

Devices

Finding a Device

If you want to check whether or not a device has been activated, or when it was activated, you can look it up in Trusona using the device's identifier.

  device = Trusona::Device.find(id: 'r1ByVyVKJ7TRgU0RPX0-THMTD_CO3VrCSNqLpJFmhms')
  if device.active
    # dance
  end

Users

Creating a User

Users are created implicitly the first time you bind a user to a device.

Deactivating a User

You may wish to disable a user from having the ability to authenticate from any of the devices they have registered with. To deactivate a user:

  Trusona::User.deactivate(user_identifier: '83452353-4F7B-4CA2-BBCD-57ACE7279EA0')

The deactivated user can be reactivated at a later date by binding them to a new device in Trusona.

Using a specific Trusona region

All users are provisioned in the default region. Unless otherwise noted, you will not need to configure Trusona to use a specific region. If you have been provisioned in a specific region, you will need to point the SDK to use that region. This can be done by configuring the region endpoint as the api_host. For example:

Trusona.config do |c|
  c.api_host       = 'https://api.ap.trusona.net'
  c.secret         = ENV['TRUSONA_SECRET']
  c.token          = ENV['TRUSONA_TOKEN']
end

TruCodes

After a user has scanned a TruCode, it's possible to acquire that user's information by getting the scanned TruCode from the server. The code sample below shows how to do that:

tru_code = Trusona::PairedTruCode.find('DB0C0B0B-0DC9-4118-BF73-68AB864E67FF')
user_id = tru_code.identifier

Footnotes

1. You must provide at least one field that would allow Trusona to determine which user to authenticate. The identifier fields are device_identifier, user_identifier, email, and trucode_id. ↩ ↩² ↩³