openid-token-proxy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 036360c10b330eabfbacd91009ab6ffd948caaaf
+  data.tar.gz: 5cc9438acbb74f17d8f4870ffd5899da09a542ae
+SHA512:
+  metadata.gz: 82b2be465db4d1e0787dda423e88b434aaa9e4af60c7472d6ae9537fe3aea769275f0f0a8796470925f340b4c8d42f56dfb7fd3b54260cbea8946f6612fcc3fe
+  data.tar.gz: 6e82dd27d7e61e87a75d08663a3d4fb6052cc4f97b2b6774fe2a2359f006b15f3a0f4908dfdac3727e7533794911182922f20e7c944a0aa2876fdc1081dbc218

data/.gitignore

@@ -0,0 +1,5 @@
+coverage/
+Gemfile.lock
+pkg/
+spec/dummy/log/
+tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.0.0
+  - 2.1.0
+script: bundle exec rake spec

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+### v0.1.0 - May 6, 2015
+
+- Initial release.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# For the actual dependencies please see openid-token-proxy.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,41 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance'
+  end
+end

data/LICENSE.md

@@ -0,0 +1,22 @@
+Licensed under the **MIT** license
+
+> Copyright (c) 2015 Hyper Interaktiv AS
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# OpenID token proxy
+
+[![Gem Version](https://img.shields.io/gem/v/openid-token-proxy.svg?style=flat)](https://rubygems.org/gems/openid-token-proxy)
+[![Build Status](https://img.shields.io/travis/hyperoslo/openid-token-proxy.svg?style=flat)](https://travis-ci.org/hyperoslo/openid-token-proxy)
+[![Dependency Status](https://img.shields.io/gemnasium/hyperoslo/openid-token-proxy.svg?style=flat)](https://gemnasium.com/hyperoslo/openid-token-proxy)
+[![Code Climate](https://img.shields.io/codeclimate/github/hyperoslo/openid-token-proxy.svg?style=flat)](https://codeclimate.com/github/hyperoslo/openid-token-proxy)
+[![Coverage Status](https://img.shields.io/coveralls/hyperoslo/openid-token-proxy.svg?style=flat)](https://coveralls.io/r/hyperoslo/openid-token-proxy)
+
+Retrieves and refreshes OpenID tokens on behalf of a user when dealing with complex
+authentication schemes, such as client-side certificates.
+
+**Note: Under development, not for production usage just yet**
+
+**Supported Ruby versions: 2.0.0 or higher**
+
+Licensed under the **MIT** license, see LICENSE for more information.
+
+
+## Background
+
+When using [OpenID](http://openid.net/specs/openid-connect-core-1_0.html) in
+native applications, the most common approach is to open the identity provider's
+authorization page in a web view, let the user authenticate and have the application
+hold on to access, identity and refresh tokens.
+
+![Regular OpenID flow](docs/regular-openid-flow.png?raw=1)
+
+However, the above flow may be unusable if the identity provider provides complex
+authentication schemes, such as client-side certificates.
+
+On iOS, client-side certificates stored in the system keychain [cannot be obtained due to application sandboxing](http://stackoverflow.com/questions/7648487/how-to-list-certificates-from-the-iphone-keychain-inside-my-app).
+
+On Android, one can obtain system certificates but these [can not be used within a web view](http://stackoverflow.com/questions/15588851/android-webview-with-client-certificate).
+
+![OpenID token proxy flow](docs/openid-token-proxy-flow.png?raw=1)
+
+When using OpenID token proxy, the application opens a web browser - which has
+access to client-side certificates regardless of storage location - and lets the
+user authenticate. The identity provider redirects to the OpenID token proxy,
+which in turn passes along any obtained tokens to the application.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'openid-token-proxy'
+```
+
+Or install it yourself:
+
+    $ gem install openid-token-proxy
+
+
+## Usage
+
+### Configuration
+
+```ruby
+OpenIDTokenProxy.configure do |config|
+  config.client_id = 'xxx'
+  config.client_secret = 'xxx'
+  config.issuer = 'https://login.windows.net/common'
+  config.redirect_uri = 'https://example.com/auth/callback'
+  config.resource = 'https://graph.windows.net'
+
+  # Indicates which domain users will presumably be signing in with
+  config.domain_hint = 'example.com'
+
+  # Whether to force authentication in case a session is already established
+  config.prompt = 'login'
+
+  # If these endpoints or public keys are not configured explicitly, they will be
+  # discovered automatically by contacting the issuer (see above)
+  config.authorization_endpoint = 'https://login.windows.net/common/oauth2/authorize'
+  config.token_endpoint = 'https://login.windows.net/common/oauth2/token'
+  config.userinfo_endpoint = 'https://login.windows.net/common/openid/userinfo'
+  config.public_keys = [
+    OpenSSL::PKey::RSA.new("-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9...")
+  ]
+
+  # Alternatively, you can override the authorization URI in its entirety:
+  config.authorization_uri = 'https://id.hyper.no/authorize?prompt=login'
+end
+```
+
+Alternatively, these environment variables will be picked up automatically:
+
+- `OPENID_AUTHORIZATION_ENDPOINT`
+- `OPENID_AUTHORIZATION_URI`
+- `OPENID_CLIENT_ID`
+- `OPENID_CLIENT_SECRET`
+- `OPENID_DOMAIN_HINT`
+- `OPENID_ISSUER`
+- `OPENID_PROMPT`
+- `OPENID_REDIRECT_URI`
+- `OPENID_RESOURCE`
+- `OPENID_TOKEN_ENDPOINT`
+- `OPENID_USERINFO_ENDPOINT`
+
+
+### Token acquirement
+
+OpenID token proxy's main task is to obtain tokens on behalf of users. To allow it
+to do so, start by mounting the engine in your Rails application:
+
+```ruby
+Rails.application.routes.draw do
+  mount OpenIDTokenProxy::Engine, at: '/auth'
+end
+```
+
+Next, register the engine's callback - `https://example.com/auth/callback` - as
+the redirect URL of your OpenID application on the issuer so that any authorization
+requests are routed back to your application.
+
+The proxy itself also needs to be configured with a redirect URL in order for it
+to know what to do with any newly obtained tokens. To boot back into a native
+applicaton one could use custom URL schemes or intents:
+
+```ruby
+OpenIDTokenProxy.configure do |config|
+  config.token_acquirement_hook = proc { |token|
+    "my-app://?token=#{token}&refresh_token=#{token.refresh_token}"
+  }
+end
+```
+
+
+### Token authentication
+
+Additionally, OpenID token proxy ships with an authentication module simplifying
+token validation for use in APIs:
+
+```ruby
+class AccountsController < ApplicationController
+  include OpenIDTokenProxy::Token::Authentication
+
+  require_valid_token
+
+  ...
+end
+```
+
+Access tokens may be provided with one of the following:
+
+- `X-Token` header.
+- `Authorization: Bearer <token>` header.
+- Query string parameter `token`.
+
+
+#### Identity / claims
+
+A valid token is exposed to a controller as `current_token` and identity information
+can be extracted by providing a claim name through hash-syntax:
+
+```ruby
+current_token['email']
+```
+
+Identity providers may support additional claims beyond the [standard OpenID ones](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).
+
+
+### Token refreshing
+
+Most identity providers issue access tokens [with short lifespans](http://openid.net/specs/openid-connect-core-1_0.html#TokenLifetime).
+To prevent users from having to authenticate often, refresh tokens are used to
+obtain new access tokens without user intervention.
+
+OpenID token proxy's token refresh module does just that:
+
+```ruby
+class AccountsController < ApplicationController
+  include OpenIDTokenProxy::Token::Authentication
+  include OpenIDTokenProxy::Token::Refresh
+
+  require_valid_token
+
+  ...
+end
+```
+
+Refresh tokens may be provided with one of the following:
+
+- `X-Refresh-Token` header.
+- Query string parameter `refresh_token`.
+
+Whenever an access token has expired and a refresh token is given, the module will
+attempt to obtain a new token transparently.
+
+The following headers will be present on the API response if, **and only if**, a new
+token was obtained:
+
+- `X-Token` header containing the new access token to be used in future requests.
+- `X-Refresh-Token` header containing the new refresh token.
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a pull request
+
+
+## Credits
+
+Hyper made this. We're a digital communications agency with a passion for good code,
+and if you're using this library we probably [want to hire you](http://hyper.no/jobs).

data/Rakefile

@@ -0,0 +1,16 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+task test: :spec
+task default: :spec

data/app/controllers/openid_token_proxy/application_controller.rb

@@ -0,0 +1,4 @@
+module OpenIDTokenProxy
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/openid_token_proxy/callback_controller.rb

@@ -0,0 +1,22 @@
+module OpenIDTokenProxy
+  class CallbackController < ApplicationController
+    def handle
+      unless code = params[:code]
+        render text: "Required parameter 'code' missing.", status: :bad_request
+        return
+      end
+
+      begin
+        token = OpenIDTokenProxy.client.retrieve_token!(auth_code: code)
+      rescue OpenIDTokenProxy::Client::AuthCodeError => error
+        render text: "Could not exchange authorization code: #{error.message}.",
+               status: :bad_request
+        return
+      end
+
+      config = OpenIDTokenProxy.config
+      uri = instance_exec token, &config.token_acquirement_hook
+      redirect_to uri || main_app.root_url unless performed?
+    end
+  end
+end

data/config/initializers/inflections.rb

@@ -0,0 +1,3 @@
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym 'OpenID'
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+OpenIDTokenProxy::Engine.routes.draw do
+  get :callback, to: 'callback#handle'
+end

data/lib/openid-token-proxy.rb

@@ -0,0 +1 @@
+require 'openid_token_proxy'

data/lib/openid_token_proxy/client.rb

@@ -0,0 +1,48 @@
+module OpenIDTokenProxy
+  class Client
+    attr_accessor :config
+
+    def initialize(config = OpenIDTokenProxy.config)
+      @config = config
+    end
+
+    def authorization_uri
+      config.authorization_uri || new_client.authorization_uri(
+        domain_hint: config.domain_hint,
+        prompt: config.prompt,
+        resource: config.resource
+      )
+    end
+
+    # Raised when auth code could not be exchanged
+    class AuthCodeError < Error; end
+
+    # Raised when refresh token could not be exchanged
+    class RefreshTokenError < Error; end
+
+    # Retrieves a token for given authorization code or refresh token
+    def retrieve_token!(params)
+      client = new_client
+      client.authorization_code = params[:auth_code] if params[:auth_code]
+      client.refresh_token = params[:refresh_token] if params[:refresh_token]
+      response = client.access_token!(:query_string)
+      token = Token.decode!(response.access_token)
+      token.refresh_token = response.refresh_token
+      token
+    rescue Rack::OAuth2::Client::Error => e
+      raise AuthCodeError.new(e.message) if params[:auth_code]
+      raise RefreshTokenError.new(e.message) if params[:refresh_token]
+    end
+
+    def new_client
+      OpenIDConnect::Client.new(
+        identifier:             config.client_id,
+        secret:                 config.client_secret,
+        authorization_endpoint: config.authorization_endpoint,
+        token_endpoint:         config.token_endpoint,
+        userinfo_endpoint:      config.userinfo_endpoint,
+        redirect_uri:           config.redirect_uri
+      )
+    end
+  end
+end

data/lib/openid_token_proxy/config.rb

@@ -0,0 +1,56 @@
+require 'openid_connect'
+
+module OpenIDTokenProxy
+  class Config
+    attr_accessor :client_id, :client_secret, :issuer
+    attr_accessor :domain_hint, :prompt, :redirect_uri, :resource
+    attr_accessor :authorization_uri
+    attr_accessor :authorization_endpoint, :token_endpoint, :userinfo_endpoint
+    attr_accessor :token_acquirement_hook
+    attr_accessor :public_keys
+
+    def initialize
+      @client_id = ENV['OPENID_CLIENT_ID']
+      @client_secret = ENV['OPENID_CLIENT_SECRET']
+      @issuer = ENV['OPENID_ISSUER']
+
+      @domain_hint = ENV['OPENID_DOMAIN_HINT']
+      @prompt = ENV['OPENID_PROMPT']
+      @redirect_uri = ENV['OPENID_REDIRECT_URI']
+      @resource = ENV['OPENID_RESOURCE']
+
+      @authorization_uri = ENV['OPENID_AUTHORIZATION_URI']
+
+      @authorization_endpoint = ENV['OPENID_AUTHORIZATION_ENDPOINT']
+      @token_endpoint = ENV['OPENID_TOKEN_ENDPOINT']
+      @userinfo_endpoint = ENV['OPENID_USERINFO_ENDPOINT']
+
+      @token_acquirement_hook = proc { }
+
+      yield self if block_given?
+    end
+
+    def provider_config
+      # TODO: Add support for refreshing provider configuration
+      @provider_config ||= begin
+        OpenIDConnect::Discovery::Provider::Config.discover! issuer
+      end
+    end
+
+    def authorization_endpoint
+      @authorization_endpoint || provider_config.authorization_endpoint
+    end
+
+    def token_endpoint
+      @token_endpoint || provider_config.token_endpoint
+    end
+
+    def userinfo_endpoint
+      @userinfo_endpoint || provider_config.userinfo_endpoint
+    end
+
+    def public_keys
+      @public_keys ||= provider_config.public_keys
+    end
+  end
+end

data/lib/openid_token_proxy/engine.rb

@@ -0,0 +1,5 @@
+module OpenIDTokenProxy
+  class Engine < ::Rails::Engine
+    isolate_namespace OpenIDTokenProxy
+  end
+end

data/lib/openid_token_proxy/error.rb

@@ -0,0 +1,7 @@
+module OpenIDTokenProxy
+  class Error < StandardError
+    def to_json
+      { error: message }
+    end
+  end
+end

data/lib/openid_token_proxy/token/authentication.rb

@@ -0,0 +1,54 @@
+require 'active_support/concern'
+
+module OpenIDTokenProxy
+  class Token
+    module Authentication
+      extend ActiveSupport::Concern
+
+      included do
+        rescue_from OpenIDTokenProxy::Error, with: :require_authorization
+
+        helper_method :current_token, :raw_token
+      end
+
+      module ClassMethods
+        def require_valid_token(*args)
+          before_action :require_valid_token, *args
+        end
+      end
+
+      def set_authentication_url!
+        uri = OpenIDTokenProxy.client.authorization_uri
+        response.headers['X-Authentication-URL'] = uri
+      end
+
+      def require_authorization(exception)
+        set_authentication_url!
+        render json: exception.to_json, status: :unauthorized
+      end
+
+      def require_valid_token
+        config = OpenIDTokenProxy.config
+        current_token.validate! audience: config.resource,
+                                client_id: config.client_id
+      end
+
+      def current_token
+        @current_token ||= OpenIDTokenProxy::Token.decode!(raw_token)
+      end
+
+      def raw_token
+        token = params[:token]
+        return token if token
+
+        authorization = request.headers['Authorization']
+        if authorization
+          token = authorization[/Bearer (.+)/, 1]
+          return token if token
+        end
+
+        request.headers['X-Token']
+      end
+    end
+  end
+end

data/lib/openid_token_proxy/token/expired.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token has expired
+    class Expired < Error
+      def initialize
+        super 'Token has expired.'
+      end
+    end
+
+  end
+end

data/lib/openid_token_proxy/token/invalid_application.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token's application did not match
+    class InvalidApplication < Error
+      def initialize
+        super 'Token is not intended for this application.'
+      end
+    end
+
+  end
+end

data/lib/openid_token_proxy/token/invalid_audience.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token's audience did not match
+    class InvalidAudience < Error
+      def initialize
+        super 'Token was issued for an unexpected audience/resource.'
+      end
+    end
+
+  end
+end

data/lib/openid_token_proxy/token/invalid_issuer.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token's issuer did not match
+    class InvalidIssuer < Error
+      def initialize
+        super 'Token was issued by an unexpected issuer.'
+      end
+    end
+
+  end
+end

data/lib/openid_token_proxy/token/malformed.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token could not be decoded
+    class Malformed < Error
+      def initialize(message)
+        super "Token is malformed: #{message}."
+      end
+    end
+
+  end
+end

data/lib/openid_token_proxy/token/refresh.rb

@@ -0,0 +1,30 @@
+require 'active_support/concern'
+
+module OpenIDTokenProxy
+  class Token
+    module Refresh
+      extend ActiveSupport::Concern
+
+      included do
+        include OpenIDTokenProxy::Token::Authentication
+
+        helper_method :raw_refresh_token
+
+        def require_valid_token
+          super
+        rescue OpenIDTokenProxy::Token::Expired
+          raise unless raw_refresh_token.present?
+          @current_token = OpenIDTokenProxy.client.retrieve_token!(
+            refresh_token: raw_refresh_token
+          )
+          response.headers['X-Token'] = current_token.access_token
+          response.headers['X-Refresh-Token'] = current_token.refresh_token
+        end
+      end
+
+      def raw_refresh_token
+        params[:refresh_token] || request.headers['X-Refresh-Token']
+      end
+    end
+  end
+end

data/lib/openid_token_proxy/token/required.rb

@@ -0,0 +1,12 @@
+module OpenIDTokenProxy
+  class Token
+
+    # Raised when a token was not provided
+    class Required < Error
+      def initialize
+        super 'Token must be provided.'
+      end
+    end
+
+  end
+end