goinstant-auth 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e57579ef9a598241a353985a3e2196c9356595a8
+  data.tar.gz: 791f93734b346080b6cef9b2f2fb96f89c167de2
+SHA512:
+  metadata.gz: 93cbae429b8bf7f8404159209c383454c998b04e21aa617ce33b816191b7fd6a051369f172cdde902b066e6f1f3668ce5fdec242042faf0bb394438398962ac1
+  data.tar.gz: 948cbffa95ab09c084b18616928aa4b4e8ec83ff5f3164fbc8590e9c53da0ed81b69fa4ec36597374d8f44c0df3830ecfc14559e8aa697a08d182bfcb203fb9d

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2013, GoInstant Inc., a salesforce.com company
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of GoInstant Inc., a salesforce.com company, nor the names
+  of its contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,191 @@
+# ruby-goinstant-auth
+
+GoInstant Authentication for Your Ruby Application
+
+[![Build Status](https://magnum.travis-ci.com/goinstant/ruby-goinstant-auth.png?token=fy6GC4GtQkNjSzNF3geU&branch=master)](https://magnum.travis-ci.com/goinstant/ruby-goinstant-auth)
+
+This is an implementation of JWT tokens consistent with what's specified in the
+[GoInstant Users and Authentication
+Guide](https://developers.goinstant.com/v1/guides/users_and_authentication.html).
+
+This library is not intended as a general-use JWT library.  For a more general
+library, see [progrium/ruby-jwt](https://github.com/progrium/ruby-jwt) (but
+please note its supported version).
+At the time of this writing, GoInstant supports the [JWT IETF draft
+version 08](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-08).
+
+# Installation
+
+```sh
+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](https://goinstant.com/dashboard) and click on your App.
+
+:warning: **Remember, the Secret Key needs to be treated like a password!**
+Never share it with your users!
+
+```ruby
+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.
+
+```ruby
+jwt = 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](https://developers.goinstant.com/v1/javascript_api/connect.html) might
+look like this:
+
+```html
+<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](https://developers.goinstant.com/v1/guides/creating_and_managing_acl.html)
+  - `:display_name` - the name to display for this group
+
+`extra_headers` is completely optional.  It's used to define any additional
+[JWS header fields](http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-11#section-4.1)
+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](https://developers.goinstant.com/v1/guides/users_and_authentication.html#which-reserved-claims-are-required).
+
+- `: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
+
+## Development Dependencies
+
+Base dependencies are as follows.
+
+- [ruby](https://www.ruby-lang.org/en/downloads/) >= 1.9.2
+- [rubygems](https://rubygems.org/pages/download) >= 2.1
+
+The following gems should then be installed via `gem install`:
+
+- [bundler](http://bundler.io/) >= 1.5
+- [rake](http://rake.rubyforge.org/) >= 10.1
+
+## Set-up
+
+```sh
+git clone git@github.com: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.
+
+```sh
+rake # 'test' is the default
+```
+
+## Developer Documentation
+
+You can view the documentation generated by `yard` easily:
+
+```sh
+gem install yard
+rake doc
+open doc/frames.html
+```
+
+# Support
+
+Email [GoInstant Support](mailto:support@goinstant.com) or stop by [#goinstant
+on freenode](irc://irc.freenode.net/#goinstant).
+
+For responsible disclosures, email [GoInstant Security](mailto:security@goinstant.com).
+
+To [file a bug](https://github.com/goinstant/node-goinstant-auth/issues) or
+[propose a patch](https://github.com/goinstant/node-goinstant-auth/pulls),
+please use github directly.
+
+# Legal
+
+&copy; 2013 GoInstant Inc., a salesforce.com company.  All Rights Reserved.
+
+Licensed under the 3-clause BSD license

data/lib/goinstant/auth.rb

@@ -0,0 +1,51 @@
+require 'json'
+require 'base64'
+require_relative 'auth/signer'
+
+# GoInstant Ruby Modules
+module GoInstant
+
+  # Authentication classes and functions for use with GoInstant
+  module Auth
+
+    # Pads base64 strings.
+    # @param str [String]
+    # @return [String] padded (extra '=' added to multiple of 4).
+    def self.pad64(str)
+      rem = str.size % 4
+      if rem > 0 then
+        str << ("=" * (4-rem))
+      end
+      return str
+    end
+
+    # Encodes base64 and base64url encoded strings.
+    # @param str [String]
+    # @return [String]
+    def self.encode64(str)
+      return Base64.urlsafe_encode64(str).sub(/=+$/,'')
+    end
+
+    # Decodes base64 and base64url encoded strings.
+    # @param str [String]
+    # @return [String]
+    def self.decode64(str)
+      str = str.gsub(/\s+/,'').tr('-_','+/').sub(/=+$/,'')
+      return Base64.decode64(pad64(str))
+    end
+
+    # Decode the Compact Serialization of a thing.
+    # @param str [String]
+    # @return [Hash|String|Object]
+    def self.compact_decode(str)
+      return JSON.parse(decode64(str))
+    end
+
+    # Create a Compact Serialization of a thing.
+    # @param thing [Hash|String|Object] anything, passed to JSON.generate.
+    # @return [String]
+    def self.compact_encode(thing)
+      return encode64(JSON.generate(thing))
+    end
+  end
+end

data/lib/goinstant/auth/signer.rb

@@ -0,0 +1,140 @@
+#encoding: UTF-8
+require 'openssl'
+
+module GoInstant
+  module Auth
+
+    # Thrown when a Signer has problems with its input.
+    class SignerError < StandardError
+    end
+
+    # Creates JWTs from user-hashes, signing with your GoInstant app secret key.
+    class Signer
+
+      # Create a Signer with a particular key.
+      #
+      # A single Signer can be used to create multiple tokens.
+      #
+      # @param secret_key [String] A base64 or base64url format string
+      # representing the secret key for your GoInstant App.
+      #
+      # @raise [TypeError] when the key isn't in base64/base64url format.
+      # @raise [StandardError] when the key is too short
+      #
+      def initialize(secret_key)
+        if secret_key.nil? then
+          raise TypeError.new('Signer requires key in base64url or base64 format')
+        end
+
+        @binary_key = Auth.decode64(secret_key)
+        if !@binary_key or @binary_key == '' then
+          raise TypeError.new('Signer requires key in base64url or base64 format')
+        end
+
+        if @binary_key.size < 32 then
+          raise StandardError.new(
+            'expected key length >= 32 bytes, got %d bytes' % @binary_key.size
+          )
+        end
+      end
+
+      # Create and sign a token for a user.
+      #
+      # @param user_data [Hash] properties about this user.
+      #   See README.md for a complete list of options.
+      # @param extra_headers [Hash] Optional, additional JWT headers to include.
+      #
+      # @raise [SignerError] if a required user or group claim is missing
+      #
+      # @return [String] a JWS Compact Serialization format-string representing this user.
+      #
+      def sign(user_data, extra_headers={})
+        if !user_data.is_a?(Hash) then
+          raise SignerError.new('Signer#sign() requires a user_data Hash')
+        end
+        claims = user_data.clone
+        Signer.map_required_claims(claims, REQUIRED_CLAIMS)
+        Signer.map_optional_claims(claims, OPTIONAL_CLAIMS)
+        claims[:aud] = 'goinstant.net'
+
+        if claims.has_key?(:g) then
+          groups = claims[:g]
+          if !groups.is_a?(Array) then
+            raise SignerError.new('groups must be an Array')
+          end
+          i = 0
+          claims[:g] = groups.map do |group|
+            group = group.clone
+            msg = "group #{i} missing required key: %s"
+            i += 1
+            Signer.map_required_claims(group, REQUIRED_GROUP_CLAIMS, msg)
+          end
+        else
+          claims[:g] = []
+        end
+
+        headers = extra_headers.clone
+        headers[:typ] = 'JWT'
+        headers[:alg] = 'HS256'
+
+        signing_input = '%s.%s' % [headers, claims].map{ |x| Auth.compact_encode(x) }
+        sig = OpenSSL::HMAC::digest('SHA256', @binary_key, signing_input)
+        return '%s.%s' % [ signing_input, Auth.encode64(sig) ]
+      end
+
+    private
+
+      # Required user_data properties and their corresponding JWT claim name
+      #
+      REQUIRED_CLAIMS = {
+        :domain => :iss,
+        :id => :sub,
+        :display_name => :dn
+      }
+
+      # Optional user_data properties and their corresponding JWT claim name
+      #
+      OPTIONAL_CLAIMS = {
+        :groups => :g
+      }
+
+      # Required group properties and their corresponding JWT claim name
+      #
+      REQUIRED_GROUP_CLAIMS = {
+        :id => :id,
+        :display_name => :dn
+      }
+
+      # Maps required claims, mutating in-place (caller should clone).
+      #
+      # @raise [SignerError] if a required claim is missing
+      # @param claims [Hash] modified to use JWT claim names
+      # @param table [Hash] conversion table of required keys
+      # @param msg [String] message format for the SignerError
+      def self.map_required_claims(claims, table, msg="missing required key: %s")
+        table.each do |name,claimName|
+          if !claims.has_key?(name) then
+            raise SignerError.new(msg % name)
+          end
+          claims[claimName] = claims.delete(name)
+        end
+        return claims
+      end
+
+      # Maps optional claims, mutating in-place (caller should clone).
+      #
+      # @param claims [Hash] modified to use JWT claim names
+      # @param table [Hash] conversion table of optional keys
+      def self.map_optional_claims(claims, table)
+        table.each do |name,claimName|
+          if claims.has_key?(name) then
+            claims[claimName] = claims.delete(name)
+          end
+        end
+        return claims
+      end
+
+    end
+
+  end
+end

data/spec/goinstant/auth/signer_spec.rb

@@ -0,0 +1,188 @@
+require 'spec_helper'
+require 'rspec'
+
+describe GoInstant::Auth::Signer do
+  it "doesn't accept nil" do
+    expect {
+      GoInstant::Auth::Signer.new(nil)
+    }.to raise_error(TypeError, 'Signer requires key in base64url or base64 format')
+  end
+
+  it "needs base64" do
+    expect {
+      GoInstant::Auth::Signer.new('!@#$%^&*()')
+    }.to raise_error(TypeError, 'Signer requires key in base64url or base64 format')
+  end
+
+  it "decodes base64url" do
+    signer = GoInstant::Auth::Signer.new('HKYdFdnezle2yrI2_Ph3cHz144bISk-cvuAbeAAA999')
+    signer.should_not == nil
+  end
+
+  it "decodes base64" do
+    signer = GoInstant::Auth::Signer.new('HKYdFdnezle2yrI2/Ph3cHz144bISk+cvuAbeAAA999')
+    signer.should_not == nil
+  end
+
+  it "handles base64 with padding too" do
+    signer = GoInstant::Auth::Signer.new('HKYdFdnezle2yrI2/Ph3cHz144bISk+cvuAbeAAA999=')
+    signer.should_not == nil
+  end
+
+  it "can compact serialization encode" do
+    str = GoInstant::Auth.compact_encode({ :asdf => 42 })
+    str.should == 'eyJhc2RmIjo0Mn0' # note: no padding
+    decoded = GoInstant::Auth.compact_decode(str)
+    expect(decoded).to be_a_kind_of(Hash)
+  end
+
+  it "complains if too short" do
+    expect {
+      GoInstant::Auth::Signer.new('abcd')
+    }.to raise_error(StandardError, 'expected key length >= 32 bytes, got 3 bytes')
+  end
+
+  def validate_jwt(jwt, expect_claims, expect_sig)
+    parts = jwt.split(/\./)
+    parts.size.should == 3
+
+    header = GoInstant::Auth.compact_decode(parts[0])
+    header['typ'].should == 'JWT'
+    header['alg'].should == 'HS256'
+
+    claims = GoInstant::Auth.compact_decode(parts[1])
+    expect(claims).to eql(expect_claims)
+
+    sig = parts[2]
+    sig.size.should == 43
+    sig.should == expect_sig
+  end
+
+  context "with valid key," do
+    before do
+      secret_key = 'HKYdFdnezle2yrI2_Ph3cHz144bISk-cvuAbeAAA999'
+      @signer = GoInstant::Auth::Signer.new(secret_key)
+    end
+
+    it "won't accept string user_data" do
+      expect {
+        @signer.sign('asdfasdf')
+      }.to raise_error(GoInstant::Auth::SignerError, 'Signer#sign() requires a user_data Hash')
+    end
+
+    it "needs user_data to have an id" do
+      user_data = {
+        :domain => 'example.com',
+        :display_name => 'bob'
+      }
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'missing required key: id')
+    end
+
+    it "needs user_data to have a display_name" do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com'
+      }
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'missing required key: display_name')
+    end
+
+    it "needs user_data to have a domain" do
+      user_data = {
+        :id => 'bar',
+        :display_name => 'bob'
+      }
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'missing required key: domain')
+    end
+
+    it "checks that groups is an array, if present" do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com',
+        :display_name => 'bob',
+        :groups => 'nope'
+      }
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'groups must be an Array')
+    end
+
+    it "happily signs without groups" do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com',
+        :display_name => 'bob'
+      }
+
+      jwt = @signer.sign(user_data)
+      validate_jwt(jwt, {
+        'aud' => 'goinstant.net',
+        'sub' => 'bar',
+        'iss' => 'example.com',
+        'dn' => 'bob',
+        'g' => []
+      }, 'GtNNsSjgB4ubwW4aFQlgT2E1F8UO7VMxf7ppXmBRlGc')
+    end
+
+    it 'needs groups to have an id' do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com',
+        :display_name => 'bob',
+        :groups => [
+          { :display_name => 'MyGroup' }
+        ]
+      }
+
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'group 0 missing required key: id')
+    end
+
+    it 'needs groups to have a display_name' do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com',
+        :display_name => 'bob',
+        :groups => [
+          { :id => 99, :display_name => 'Gretzky Lovers' },
+          { :id => 1234 }
+        ]
+      }
+
+      expect {
+        @signer.sign(user_data)
+      }.to raise_error(GoInstant::Auth::SignerError, 'group 1 missing required key: display_name')
+    end
+
+    it 'happily signs with groups' do
+      user_data = {
+        :id => 'bar',
+        :domain => 'example.com',
+        :display_name => 'bob',
+        :groups => [
+          { :id => 1234, :display_name => 'Group 1234' },
+          { :id => 42, :display_name => 'Meaning Group' }
+        ]
+      }
+
+      jwt = @signer.sign(user_data)
+      validate_jwt(jwt, {
+        'aud' => 'goinstant.net',
+        'sub' => 'bar',
+        'iss' => 'example.com',
+        'dn' => 'bob',
+        'g' => [
+          { 'id' => 1234, 'dn' => 'Group 1234' },
+          { 'id' => 42, 'dn' => 'Meaning Group' }
+        ]
+      }, '5isd3i1A4so7MwKm0VHWYHuWRy3WwGFipO0kkelNRLU')
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require 'bundler'
+Bundler.setup(:default, :test)
+
+require 'goinstant/auth'

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: goinstant-auth
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- GoInstant Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-19 00:00:00.000000000 Z
+dependencies: []
+description: Lets your users log-in to your GoInstant app
+email: support@goinstant.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/goinstant/auth/signer.rb
+- lib/goinstant/auth.rb
+- spec/goinstant/auth/signer_spec.rb
+- spec/spec_helper.rb
+- LICENSE
+- README.md
+homepage: https://github.com/goinstant/ruby-goinstant-auth
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: GoInstant Authentication for Your Ruby Application
+test_files: []
+has_rdoc: