AlterEgo

AlterEgo is a Ruby gem for integrating AlterEgo two-factor authentication into your web application. You’ll need an AlterEgo account in order to register your register your app and get your “App Authentication ID”.

Installation

(sudo) gem install alterego

Authorizing Your Application

In order to use AlterEgo, users of your application will need to sign up for their own AlterEgo account. You will need your users to authorize the connection between your application and AlterEgo by simply redirecting them:

redirect_to AlterEgo.authorization_url("your_app_id", "https://yourapp.com/alterego/callback")

AlterEgo imposes the following requirements on the redirect_url value to ensure security. Be sure that your redirect_url meets the following requirements:

Must be served via HTTPS.
Must be under the same domain (or a subdomain of) the website entered when registering your application with AlterEgo.

Once authorized successfully, a POST request will be sent to the redirect_url with a “key” parameter containing the API key for that user’s AlterEgo account. Be sure to store this key somewhere, as you will need it to run API requests later. If authorization fails for some reason, an “error” parameter will be present in the POST request, containing an error message.

if params[:key]
  current_user.alter_ego_key = params[:key]
elsif params[:error]
  flash[:alert] = params[:error]
end

Authenticating With AlterEgo

Once your users have authorized your application and you have retrieved an API key for their account, you can easily integrate two-factor authentication. To authenticate using AlterEgo (either as part of an existing login process, or as a stand-alone authentication system) simply prompt the user to input a valid AlterEgo passcode and verify it:

passcode = params[:alter_ego_passcode]
if AlterEgo.password(current_user.alter_ego_key, passcode)
  # Passcode is valid.
  ...
else
  # Passcode is not valid.
  ...
end

AlterEgo does not provide any kind of error message or explanation as to why a passcode is not valid, so you will want to be sure and keep your error messages appropriately generic.

Pinging The API

The AlterEgo API also has a method for pinging the API, in case you want to periodically check to ensure that your user’s API keys are still valid. A successful ping to the API will always return “PONG!” as a response.

AlterEgo.ping(current_user.alter_ego_api_key)

Contributing to AlterEgo