rack-oauth2-server 2.5.1 → 2.6.0

data/CHANGELOG

@@ -1,3 +1,8 @@
+2012-03-27 Version 2.6.0
+
+Adding support for JWT tokens in the "assertion" grant type (Brian Ploetz)
+
+
 2012-03-26 Version 2.5.1
 
 Issue #13: Fix bug in oauth2-server introduced by pull request #9 (Rafael Chacon)

data/README.md

@@ -28,7 +28,7 @@ different database engine, send us a pull request.
 For Rails 2.3/3.0, `Rack::OAuth2::Server` automatically adds itself as middleware when required, but you do need to
 configure it from within `config/environment.rb` (or one of the specific environment files). For example:
 
-```
+```ruby
 Rails::Initializer.run do |config|
   . . .
   config.after_initialize do
@@ -44,7 +44,7 @@ end
 For Sinatra and Padrino, first require `rack/oauth2/sinatra` and register `Rack::OAuth2::Sinatra` into your application.
 For example:
 
-```
+```ruby
 require "rack/oauth2/sinatra"
 
 class MyApp < Sinatra::Base
@@ -88,7 +88,7 @@ The authenticator is a block that receives either two or four parameters.  The f
 other two are the client identifier and scope. It authenticated, it returns an identity, otherwise it can return nil or
 false. For example:
 
-```
+```ruby
 oauth.authenticator = lambda do |username, password|
   user = User.find_by_username(username)
   user.id if user && user.authenticated?(password)
@@ -117,7 +117,7 @@ the user back to the client application with a suitable error code.
 
 In Rails, the entire flow would look something like this:
 
-```
+```ruby
 class OauthController < ApplicationController
   def authorize
     if current_user
@@ -143,7 +143,7 @@ cannot render anything, but can set the right response headers and return a stat
 
 In Sinatra/Padrino, it would look something like this:
 
-```
+```ruby
 get "/oauth/authorize" do
   if current_user
     render "oauth/authorize"
@@ -207,7 +207,7 @@ header `oauth.no_scope` to the scope name, or using `oauth_required` with the sc
 
 In Rails, it would look something like this:
 
-```
+```ruby
 class MyController < ApplicationController
 
   before_filter :set_current_user
@@ -244,7 +244,7 @@ end
 
 In Sinatra/Padrino, it would look something like this:
 
-```
+```ruby
 before do
   @current_user = User.find(oauth.identity) if oauth.authenticated?
 end
@@ -309,7 +309,7 @@ Loading development environment (Rails 2.3.8)
 You may want your application to register its own client application, always with the same client ID and secret, which
 are also stored in a configuration file. For example, your `db/seed.rb` may contain:
 
-```
+```ruby
 oauth2 = YAML.load_file(Rails.root + "config/oauth2.yml")
 Rack::OAuth2::Server.register(id: oauth2["client_id"], secret: oauth2["client_secret"],
   display_name: "UberClient", link: "http://example.com",
@@ -332,6 +332,41 @@ authorization process. This is typically used in server to server scenarios wher
 two-legged flow, send the grant_type of "none" along with the client_id and client_secret to the access token path, and
 a new access token will be generated (assuming the client_id and client_secret check out).
 
+## Assertions
+
+Rack::OAuth2::Server supports the use of assertions (in the form of the `assertion` grant_type)
+to obtain access tokens. Currently JSON Web Tokens (JWT) are the only supported assertion_type.
+
+http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4.1.3
+
+http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-03
+
+In order to verify the signatures of assertions, you will need to create assertion Issuers.
+You can register assertion Issuers using the command line tool `oauth2-server`:
+
+```
+$ oauth2-server register_issuer --db my_db
+```
+
+Programatically, registering a new Issuer is as simple as:
+
+```
+$ ./script/console
+  Loading development environment (Rails 2.3.8)
+> issuer = Rack::OAuth2::Server.register_issuer(:identifier => "http://www.someidp.com",
+   :hmac_secret => "foo",
+   :public_key => "-----BEGIN RSA PUBLIC KEY-----\n....\n...=\n-----END RSA PUBLIC KEY-----\n")
+```
+
+When you call `register_issuer` it either registers a new issuer with these specific values, or if an issuer already exists with the given 
+identifier it will update it's properties.
+
+Depending on the algorithm used for signing the assertion (HMAC SHA or RSA), you pass either `:hmac_secret` or `:public_key` to `Rack::OAuth2::Server.register_issuer` 
+(or both if you will use both with a single issuer). The value of `:public_key` can be either a PEM or DER encoded public key (as supported by `OpenSSL::PKey::RSA.new`).
+
+Rack::OAuth2::Server validates that the issuer (`iss`), principal (`prn`), audience (`aud`) and expiration (`exp`) claims are present. It also validates that the expiration 
+claim has not passed (with a 10 minute padding added to account for server clock skew).
+
 
 ## OAuth Web Admin
 
@@ -352,7 +387,7 @@ $ oauth2-server setup --db my_db
 Next, in your application, make sure to ONLY AUTHORIZE ADMINISTRATORS to access the Web admin, by granting them access
 to the `oauth-admin` scope. For example:
 
-```
+```ruby
 def grant
   # Only admins allowed to authorize the scope oauth-admin
   if oauth.scope.include?("oauth-admin") && !current_user.admin?
@@ -368,14 +403,14 @@ Make sure you do that, or you'll allow anyone access to the OAuth Web admin.
 After this, remember to include the server admin module in your initializer (environemnt.rb or application.rb), because
 this is an optional feature:
 
-```
+```ruby
 require "rack/oauth2/server/admin"
 ```
 
 Next, mount the OAuth Web admin as part of your application, and feed it the client ID/secret. For example, for Rails
 2.3.x add this to `config/environment.rb`:
 
-```
+```ruby
 Rails::Initializer.run do |config|
   . . .
   config.after_initialize do
@@ -389,7 +424,7 @@ end
 
 For Rails 3.0.x, add this to you `config/application.rb`:
 
-```
+```ruby
   module MyApp
     class Application < Rails::Application
       config.after_initialize do
@@ -403,11 +438,13 @@ For Rails 3.0.x, add this to you `config/application.rb`:
 
 And add the follownig to `config/routes.rb`:
 
+```ruby
 mount Rack::OAuth2::Server::Admin=>"/oauth/admin"
+```
 
 For Sinatra, Padrino and other Rack-based applications, you'll want to mount like so (e.g. in `config.ru`):
 
-```
+```ruby
 Rack::Builder.new do
   map("/oauth/admin") { run Rack::OAuth2::Server::Admin }
   map("/") { run MyApp }
@@ -499,6 +536,18 @@ end up sending the access token to any server you `curl`. Useful for development
 production access tokens.
 
 
+Example using the `assertion` grant_type:
+
+```
+$ curl -i  http://localhost:3000/oauth/access_token \
+    -F client_id=4dca20453e4859cb000007 \
+    -F client_secret=981fa734e110496fcf667cbf52fbaf03 \
+    -F grant_type=assertion \
+    -F assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer \
+    -F assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vd3d3LnNvbWVjb21wYW55LmNvbSIsImF1ZCI6Imh0dHA6Ly93d3cubXljb21wYW55LmNvbSIsInBybiI6IjEyMzQ1Njc4OTAifQ.bDrcogybtJ9n5d2a971Q72ye7GN64u7WXmr2OLxSeyc
+```
+
+
 ## Methods You'll Want To Use From Your App
 
 You can use the Server module to create, fetch and otherwise work with access tokens and grants. Available methods
@@ -516,7 +565,9 @@ include:
   client's ID and secret). Idempotent, so perfect for running during setup and migration.
 - `get_auth_request` -- Resolves authorization request handle into an `AuthRequest` object. Could be useful during the
   authorization flow.
-
+- `register_issuer` -- Registers a new assertion issuer. Can also be used to change
+  existing issuers. Idempotent, so perfect for running during setup and migration.
+- `get_issuer` -- Resolves an issuer identifier into an Issuer object.
 
 ## Mandatory ASCII Diagram
 
@@ -592,6 +643,11 @@ client).
 An `Rack::OAuth2::Server::AccessToken` is created by copying values from an `AuthRequest` or `AccessGrant`, and remains
 in effect until revoked. (OAuth 2.0 access tokens can also expire, but we don't support expiration at the moment)
 
+### Issuer
+
+An issuer is a identity provider which issues assertions that may be used to
+obtain an access token.
+
 
 ## Credits
 

data/VERSION

@@ -1 +1 @@
-2.5.1
+2.6.0

data/bin/oauth2-server

@@ -63,6 +63,24 @@ when "register"
   puts "ID\t#{client.id}"
   puts "Secret\t#{client.secret}"
 
+when "register_issuer"
+  fail "No database. Use the --db option to tell us which database to use" unless Server.options.database
+  begin
+    print "Identifier (typically a URL):\t"
+    identifier = $stdin.gets
+    print "HMAC secret:\t"
+    hmac_secret = $stdin.gets
+    print "RSA public key:\t\t"
+    public_key = $stdin.gets
+    issuer = Server.register_issuer(:identifier => identifier, :hmac_secret => hmac_secret, :public_key => public_key)
+  rescue
+    puts "\nFailed to register issuer: #{$!}"
+    exit -1
+  end
+  puts "Registered Issuer #{issuer.identifier}"
+  puts "HMAC secret\t#{issuer.hmac_secret}"
+  puts "RSA public key\t#{issuer.public_key}"
+
 when "setup"
 
   fail "No database. Use the --db option to tell us which database to use" unless Server.options.database
@@ -204,6 +222,7 @@ Commands:
   migrate         Run this when migrating from 1.x to 2.x
   practice        Runs a dummy OAuth 2.0 server, use this to test your OAuth 2.0 client
   register        Register a new client application
+  register_issuer Register a new assertion issuer
   setup           Create new admin account and help you setup the OAuth Web console
 
 Options:

data/lib/rack/oauth2/models.rb

@@ -54,4 +54,4 @@ require "rack/oauth2/models/client"
 require "rack/oauth2/models/auth_request"
 require "rack/oauth2/models/access_grant"
 require "rack/oauth2/models/access_token"
-
+require "rack/oauth2/models/issuer"

data/lib/rack/oauth2/models/issuer.rb

@@ -0,0 +1,58 @@
+module Rack
+  module OAuth2
+    class Server
+      # A third party that issues assertions
+      # http://tools.ietf.org/html/draft-ietf-oauth-assertions-01#section-5.1
+      class Issuer
+        class << self
+
+          # returns the Issuer object for the given identifier
+          def from_identifier(identifier)
+            Server.new_instance self, collection.find_one({:_id=>identifier})
+          end
+
+          # Create a new Issuer.
+          def create(args)
+            fields = {}
+            [:hmac_secret, :public_key, :notes].each do |key|
+              fields[key] = args[key] if args.has_key?(key)
+            end
+            fields[:created_at] = Time.now.to_i
+            fields[:updated_at] = Time.now.to_i
+            fields[:_id] = args[:identifier]
+            collection.insert(fields, :safe=>true)
+            Server.new_instance self, fields
+          end
+
+
+          def collection
+            prefix = Server.options[:collection_prefix]
+            Server.database["#{prefix}.issuers"]
+          end
+        end
+
+        # The unique identifier of this Issuer. String or URI
+        attr_reader :_id
+        alias :identifier :_id
+        # shared secret used for verifying HMAC signatures
+        attr_reader :hmac_secret
+        # public key used for verifying RSA signatures
+        attr_reader :public_key
+        # notes about this Issuer
+        attr_reader :notes
+
+
+        def update(args)
+          fields = [:hmac_secret, :public_key, :notes].inject({}) {|h,k| v = args[k]; h[k] = v if v; h}
+          self.class.collection.update({:_id => identifier }, {:$set => fields})
+          self.class.from_identifier(identifier)
+        end
+
+        Server.create_indexes do
+          # Used to revoke all pending access grants when revoking client.
+          collection.create_index [[:identifier, Mongo::ASCENDING]]
+        end
+      end
+    end
+  end
+end

data/lib/rack/oauth2/server.rb

@@ -3,6 +3,7 @@ require "rack/oauth2/models"
 require "rack/oauth2/server/errors"
 require "rack/oauth2/server/utils"
 require "rack/oauth2/server/helper"
+require "iconv"
 
 
 module Rack
@@ -119,8 +120,42 @@ module Rack
           AccessToken.from_identity(identity)
         end
 
+        # Registers and returns a new Issuer. Can also be used to update
+        # existing Issuer, by passing the identifier of an existing Issuer record.
+        # That way, your setup script can create a new client application and run
+        # repeatedly without fail.
+        #
+        # @param [Hash] args Arguments for registering Issuer
+        # @option args [String] :identifier Issuer identifier. Use this to update
+        # an existing Issuer
+        # @option args [String] :hmac_secret The HMAC secret for this Issuer
+        # @option args [String] :public_key The RSA public key (in PEM format) for this Issuer
+        # @option args [Array] :notes Free form text, for internal use.
+        #
+        # @example Registering new Issuer
+        #   Server.register_issuer :hmac_secret=>"foo", :notes=>"Company A"
+        # @example Migration using configuration file
+        #   config = YAML.load_file(Rails.root + "config/oauth.yml")
+        #   Server.register_issuer config["id"],
+        #   :hmac_secret=>"bar", :notes=>"Company A"
+        def register_issuer(args)
+          if args[:identifier] && (issuer = get_issuer(args[:identifier]))
+            issuer.update(args)
+          else
+            Issuer.create(args)
+          end
+        end
+
+        # Returns an Issuer from it's identifier.
+        #
+        # @param [String] identifier the Issuer's identifier
+        # @return [Issuer]
+        def get_issuer(identifier)
+          Issuer.from_identifier(identifier)
+        end
       end
 
+
       # Options are:
       # - :access_token_path -- Path for requesting access token. By convention
       #   defaults to /oauth/access_token.
@@ -381,6 +416,17 @@ module Rack
             identity = options.authenticator.call(*args)
             raise InvalidGrantError, "Username/password do not match" unless identity
             access_token = AccessToken.get_token_for(identity, client, requested_scope, options.expires_in)
+          when "assertion"
+            # 4.1.3. Assertion
+            requested_scope = request.POST["scope"] ? Utils.normalize_scope(request.POST["scope"]) : client.scope
+            assertion_type, assertion = request.POST.values_at("assertion_type", "assertion")
+            raise InvalidGrantError, "Missing assertion_type/assertion" unless assertion_type && assertion
+            # TODO: Add other supported assertion types (i.e. SAML) here
+            raise InvalidGrantError, "Unsupported assertion_type" if assertion_type != "urn:ietf:params:oauth:grant-type:jwt-bearer"
+            if assertion_type == "urn:ietf:params:oauth:grant-type:jwt-bearer"
+              identity = process_jwt_assertion(assertion)
+              access_token = AccessToken.get_token_for(identity, client, requested_scope, options.expires_in)
+            end
           else
             raise UnsupportedGrantType
           end
@@ -436,6 +482,48 @@ module Rack
         return [401, { "WWW-Authenticate"=>challenge }, [error && error.message || ""]]
       end
 
+      # Processes a JWT assertion
+      def process_jwt_assertion(assertion)
+        begin
+          require 'jwt'
+          require 'json'
+          require 'openssl'
+          require 'time'
+          # JWT.decode only returns the claims. Gotta get the header ourselves
+          header = JSON.parse(JWT.base64url_decode(assertion.split('.')[0]))
+          algorithm = header['alg']
+          payload = JWT.decode(assertion, nil, false)
+
+          raise InvalidGrantError, "missing issuer claim" if !payload.has_key?('iss')
+
+          issuer_identifier = payload['iss']
+          issuer = Issuer.from_identifier(issuer_identifier)
+          raise InvalidGrantError, 'Invalid issuer' if issuer.nil?
+          if algorithm =~ /^HS/
+            validated_payload = JWT.decode(assertion, issuer.hmac_secret, true)
+          elsif algorithm =~ /^RS/
+            validated_payload = JWT.decode(assertion, OpenSSL::PKey::RSA.new(issuer.public_key), true)
+          end
+
+          raise InvalidGrantError, "missing principal claim" if !validated_payload.has_key?('prn')
+          raise InvalidGrantError, "missing audience claim" if !validated_payload.has_key?('aud')
+          raise InvalidGrantError, "missing expiration claim" if !validated_payload.has_key?('exp')
+
+          expires = validated_payload['exp'].to_i
+          # add a 10 minute fudge factor for clock skew between servers
+          skewed_expires_time = expires + (10 * 60)
+          now = Time.now.utc.to_i
+          raise InvalidGrantError, "expired claims" if skewed_expires_time <= now
+          principal = validated_payload['prn']
+          principal
+        rescue JWT::DecodeError => de
+          raise InvalidGrantError, de.message
+        rescue JSON::ParserError => pe
+          raise InvalidGrantError, "Invalid segment encoding"
+        end
+      end
+
+
       # Wraps Rack::Request to expose Basic and OAuth authentication
       # credentials.
       class OAuthRequest < Rack::Request

data/rack-oauth2-server.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "bson_ext"
   spec.add_dependency "sinatra", "~>1.1"
   spec.add_dependency "json"
+  spec.add_dependency "jwt", "~>0.1.4"
 end

data/test/oauth/access_grant_test.rb

@@ -1,4 +1,6 @@
 require "test/setup"
+require "jwt"
+require "openssl"
 
 
 # 4.  Obtaining an Access Token
@@ -93,6 +95,14 @@ class AccessGrantTest < Test::Unit::TestCase
     post "/oauth/access_token", params
   end
 
+  def request_with_assertion(assertion_type, assertion)
+    basic_authorize client.id, client.secret
+    params = { :grant_type=>"assertion", :scope=>"read write" }
+    params[:assertion_type] = assertion_type if assertion_type
+    params[:assertion] = assertion if assertion
+    post "/oauth/access_token", params
+  end
+
 
   # 4.  Obtaining an Access Token
   
@@ -255,6 +265,125 @@ class AccessGrantTest < Test::Unit::TestCase
     teardown { config.authenticator = @old }
   end
 
+  # 4.1.3. Assertion
+
+  context "assertion" do
+    context "no assertion_type" do
+      setup { request_with_assertion nil, "myassertion" }
+      should_return_error :invalid_grant
+    end
+
+    context "no assertion" do
+      setup { request_with_assertion "urn:some:assertion:type", nil }
+      should_return_error :invalid_grant
+    end
+
+    context "unsupported assertion_type" do
+      setup { request_with_assertion "urn:some:assertion:type", "myassertion" }
+      should_return_error :invalid_grant
+    end
+
+    context "JWT" do
+      setup {
+        @hour_from_now = Time.now.utc.to_i + (60 * 60)
+      }
+      context "malformed assertion" do
+        setup { request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", "myassertion" }
+        should_return_error :invalid_grant
+      end
+
+      context "missing principal claim" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "aud" => "http://www.mycompany.com", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, @hmac_issuer.hmac_secret, "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "missing audience claim" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "prn" => "1234567890", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, @hmac_issuer.hmac_secret, "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "missing expiration claim" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "aud" => "http://www.mycompany.com", "prn" => "1234567890"}
+          jwt_assertion = JWT.encode(@claims, "shhh", "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "missing issuer claim" do
+        setup {
+          @claims = {"aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, "shhh", "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "unknown issuer" do
+        setup {
+          @claims = {"iss" => "unknown", "aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, "shhh", "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "valid HMAC assertion" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, @hmac_issuer.hmac_secret, "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_respond_with_access_token "read write"
+      end
+
+      context "valid RSA assertion" do
+        setup {
+          @private_key = OpenSSL::PKey::RSA.generate(512)
+          @rsa_issuer = Server.register_issuer(:identifier => "http://www.rsaissuer.com", :public_key => @private_key.public_key.to_pem, :notes => "Test RSA Issuer")
+          @claims = {"iss" => @rsa_issuer.identifier, "aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => @hour_from_now}
+          jwt_assertion = JWT.encode(@claims, @private_key, "RS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_respond_with_access_token "read write"
+      end
+
+      context "expired claim set" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => Time.now.utc.to_i - (11 * 60)}
+          jwt_assertion = JWT.encode(@claims, @hmac_issuer.hmac_secret, "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_return_error :invalid_grant
+      end
+
+      context "expiration claim within the fudge factor time" do
+        setup {
+          @hmac_issuer = Server.register_issuer(:identifier => "http://www.hmacissuer.com", :hmac_secret => "foo", :notes => "Test HMAC Issuer")
+          @claims = {"iss" => @hmac_issuer.identifier, "aud" => "http://www.mycompany.com", "prn" => "1234567890", "exp" => Time.now.utc.to_i - (9 * 60)}
+          jwt_assertion = JWT.encode(@claims, @hmac_issuer.hmac_secret, "HS256")
+          request_with_assertion "urn:ietf:params:oauth:grant-type:jwt-bearer", jwt_assertion
+        }
+        should_respond_with_access_token "read write"
+      end
+
+    end
+  end
+
 
   # 4.2.  Access Token Response