AlterEgo <img src=“http://travis-ci.org/terra-firma/alterego.png” /> <img src=“https://gemnasium.com/terra-firma/alterego.png” alt=“Dependency Status” />

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

Usage

To start with, you will need an AlterEgo account as a developer so that you can register your app. People that want to use your application will also need to signup for an AlterEgo account (obviously) as well.

Register Your App

Login to your AlterEgo account and click “register a new app” on the “Developer” page. Once your app is registered, you will get an “App Authentication ID”, which we refer to in this document at the “App ID”. You’re now ready to get started.

Connect Your App

The first thing you will need to do is prompt your users to authorize the connection between your application and AlterEgo. Once they are logged in, simply redirect 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.

def callback
  # POST /alterego/callback
  if params[:key]
    current_user.alter_ego_key = params[:key]
    current_user.save
    ...
  elsif params[:error]
    flash[:alert] = params[:error]
    ...
  end
end

As you can see, we are saving the key that AlterEgo returns for the currently logged in user, and we have successfully connected this user account to AlterEgo.

Authenticating With AlterEgo

Once the user account has been connected, you can easily integrate two-factor authentication into your app, either as part of an existing login process, or as a stand-alone authentication system. In most cases, AlterEgo is integrated into an existing authentication system such that once the user has provided the correct username/password combination, they are then asked to provide a valid AlterEgo passcode to finalize the login process:

def verify
  # POST /alterego/verify
  passcode = params[:alter_ego_passcode]
  if AlterEgo.password(current_user.alter_ego_key, passcode)
    # Passcode is valid, log this user in...
  else
    # Passcode is not valid.
  end
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

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.