ruby-goinstant-auth

GoInstant Authentication for Your Ruby Application

This is an implementation of JWT tokens consistent with what's specified in the GoInstant Users and Authentication Guide.

This library is not intended as a general-use JWT library. For a more general library, see progrium/ruby-jwt (but please note its supported version). At the time of this writing, GoInstant supports the JWT IETF draft version 08.

Installation

gem install goinstant-auth

Usage

Construct a signer with your goinstant application key. The application key should be in base64url or base64 string format. To get your key, go to your goinstant dashboard and click on your App.

:warning: Remember, the Secret Key needs to be treated like a password! Never share it with your users!

require 'goinstant/auth'

signer = GoInstant::Auth::Signer.new(secret_key)

You can then use this signer to create as many tokens as you want. The :domain parameter should be replaced with your website's domain. Groups are optional.

token = signer.sign({
  :domain => 'example.com', # TODO: replace me
  :id => user.id,
  :display_name => user.full_name,
  :groups => [
    {
      :id => 'room-42',
      :display_name => 'Room 42 ACL Group'
    }
  ]
})

This token can be safely inlined into an ERB template. For example, a fairly basic template for calling goinstant.connect call might look like this:

<script type="text/javascript">
  (function() {
    var token = "<%= token %>";
    var url = 'https://goinstant.net/YOURACCOUNT/YOURAPP'

    var opts = {
      user: token,
      rooms: [ 'room-42' ]
    };

    goinstant.connect(url, opts, function(err, conn, room) {
      if (err) {
        throw err;
      }
      runYourApp(room);
    });
  }());
</script>

Methods

`GoInstant::Auth::Signer`

Re-usable object for creating user tokens.

`.new(secret_key)`

Constructs a Signer object from a base64url or base64 secret key string.

Throws an Error if the secretKey could not be parsed.

`#sign(user_data, extra_headers={})`

Creates a JWT as a JWS in Compact Serialization format. Can be called multiple times on the same object, saving you from having to load your secret GoInstant application key every time.

user_data is a Hash with the following required fields, plus any other custom ones you want to include in the JWT.

:domain - the domain of your website
:id - the unique, permanent identity of this user on your website
:display_name - the name to initially display for this user
:groups - an array of groups, each group requiring:
- :id - the unique ID of this group, which is handy for defining GoInstant ACLs
- :display_name - the name to display for this group

extra_headers is completely optional. It's used to define any additional JWS header fields that you want to include.

Technicals

The sign() method's user_data maps to the following JWT claims. The authoritative list of claims used in GoInstant can be found in the Users and Authentication Guide.

:domain -> iss (standard claim)
:id -> sub (standard claim)
:display_name -> dn (GoInstant private claim)
:groups -> g (GoInstant private claim)
- :id -> id (GoInstant private claim)
- :display_name -> dn (GoInstant private claim)
'goinstant.net' -> aud (standard claim) automatically added

For the extra_headers parameter in sign(), the alg and typ headers will be overridden by this library.

Contributing

If you'd like to contribute to or modify ruby-goinstant-auth, here's a quick guide to get you started.

Development Dependencies

Base dependencies are as follows.

ruby >= 1.9.2
rubygems >= 2.1

The following gems should then be installed via gem install:

bundler >= 1.5
rake >= 10.1

Set-up

git clone [email protected]:goinstant/ruby-goinstant-auth.git
cd ruby-goinstant-auth

# if you haven't already:
gem install bundler
gem install rake

# then, install dev dependencies:
bundle install

Testing

Testing is done with RSpec. Tests are located in the spec/ folder.

To run the tests:

rake # 'test' is the default

Developer Documentation

You can view the documentation generated by yard easily:

gem install yard
rake doc
open doc/frames.html

Publishing

When publishing $VERSION to master.

Edit goinstant-auth.gemspec and bump the version number
git add *.gemspec && git commit -m '$VERSION'
git tag $VERSION
git push --tags origin master
rake gem
gem push goinstant-auth-$VERSION.gem - note that there may be other .gem files hanging around so don't be lazy and specify *.gem

Check on https://rubygems.org/gems/goinstant-auth to see that it published.

Support

Email GoInstant Support or stop by #goinstant on freenode.

For responsible disclosures, email GoInstant Security.

To file a bug or propose a patch, please use github directly.

Legal

Licensed under the 3-clause BSD license