omniauth-auth0 2.0.0 → 2.4.0

data/README.md

@@ -1,57 +1,70 @@
-[![Build Status](https://travis-ci.org/auth0/omniauth-auth0.svg)](https://travis-ci.org/auth0/omniauth-auth0)
-
 # OmniAuth Auth0
 
-This is the official [OmniAuth](https://github.com/intridea/omniauth) strategy for authenticating to [Auth0](https://auth0.com).
+An [OmniAuth](https://github.com/intridea/omniauth) strategy for authenticating with [Auth0](https://auth0.com). This strategy is based on the [OmniAuth OAuth2](https://github.com/omniauth/omniauth-oauth2) strategy.
 
-## Installing
+> :warning:  **Important security note:** This solution uses a 3rd party library with an unresolved [security issue(s)](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-9284). Please review the details of the vulnerability, including [Auth0](https://github.com/auth0/omniauth-auth0/issues/82 ) and other recommended [mitigations](https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284), before implementing the solution.
 
-Add to your `Gemfile`:
+[![CircleCI](https://img.shields.io/circleci/project/github/auth0/omniauth-auth0/master.svg)](https://circleci.com/gh/auth0/omniauth-auth0)
+[![codecov](https://codecov.io/gh/auth0/omniauth-auth0/branch/master/graph/badge.svg)](https://codecov.io/gh/auth0/omniauth-auth0)
+[![Gem Version](https://badge.fury.io/rb/omniauth-auth0.svg)](https://badge.fury.io/rb/omniauth-auth0)
+[![MIT licensed](https://img.shields.io/dub/l/vibe-d.svg?style=flat)](https://github.com/auth0/omniauth-auth0/blob/master/LICENSE)
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fomniauth-auth0.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fomniauth-auth0?ref=badge_shield)
 
-```ruby
-gem 'omniauth-auth0'
-```
+## Table of Contents
 
-Then `bundle install`.
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Contribution](#contribution)
+- [Support + Feedback](#support--feedback)
+- [Vulnerability Reporting](#vulnerability-reporting)
+- [What is Auth0](#what-is-auth0)
+- [License](#license)
 
-## Usage
+## Documentation
 
-### Rails
+- [Ruby on Rails Quickstart](https://auth0.com/docs/quickstart/webapp/rails)
+- [Sample projects](https://github.com/auth0-samples/auth0-rubyonrails-sample)
 
-```ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :auth0, ENV['AUTH0_CLIENT_ID'], ENV['AUTH0_CLIENT_SECRET'], ENV['AUTH0_DOMAIN']
-end
-```
+## Installation
 
-Then to redirect to your tenant's hosted login page:
+Add the following line to your `Gemfile`:
 
 ```ruby
-redirect_to '/auth/auth0'
+gem 'omniauth-auth0'
 ```
 
-### Sinatra
+If you're using this strategy with Rails, also add the following for CSRF protection:
 
 ```ruby
-use OmniAuth::Builder do
-  provider :auth0, ENV['AUTH0_CLIENT_ID'], ENV['AUTH0_CLIENT_SECRET'], ENV['AUTH0_DOMAIN']
-end
+gem 'omniauth-rails_csrf_protection'
 ```
 
-Then to redirect to your tenant's hosted login page:
+Then install:
 
-```ruby
-redirect to('/auth/auth0')
+```bash
+$ bundle install
 ```
 
-> You can customize your hosted login page in your [Auth0 Dashboard](https://manage.auth0.com/#/login_page)
+See our [contributing guide](CONTRIBUTING.md) for information on local installation for development.
+
+## Getting Started
+
+To start processing authentication requests, the following steps must be performed:
 
-### Auth parameters
+1. Initialize the strategy
+2. Configure the callback controller
+3. Add the required routes
+4. Trigger an authentication request
 
-To send additional parameters during login you can specify them when you register the provider
+All of these tasks and more are covered in our [Ruby on Rails Quickstart](https://auth0.com/docs/quickstart/webapp/rails).
+
+### Additional authentication parameters
+
+To send additional parameters during login, you can specify them when you register the provider:
 
 ```ruby
-provider 
+provider
   :auth0,
   ENV['AUTH0_CLIENT_ID'],
   ENV['AUTH0_CLIENT_SECRET'],
@@ -59,85 +72,101 @@ provider
   {
     authorize_params: {
       scope: 'openid read:users write:order',
-      audience: 'https://mydomain/api'
+      audience: 'https://mydomain/api',
+      max_age: 3600 # time in seconds authentication is valid
     }
   }
 ```
 
-that will tell it to send those parameters on every Auth request.
+... which will tell the strategy to send those parameters on every authentication request.
+
+### Authentication hash
 
-Or you can do it for a specific Auth request by adding them in the query parameter of the redirect url:
+The Auth0 strategy will provide the standard OmniAuth hash attributes:
+
+- `:provider` - the name of the strategy, in this case `auth0`
+- `:uid` - the user identifier
+- `:info` - the result of the call to `/userinfo` using OmniAuth standard attributes
+- `:credentials` - tokens requested and data
+- `:extra` - Additional info obtained from calling `/userinfo` in the `:raw_info` property
 
 ```ruby
-redirect_to '/auth/auth0?connection=google-oauth2'
+{
+  :provider => 'auth0',
+  :uid => 'auth0|USER_ID',
+  :info => {
+    :name => 'John Foo',
+    :email => 'johnfoo@example.org',
+    :nickname => 'john',
+    :image => 'https://example.org/john.jpg'
+  },
+  :credentials => {
+    :token => 'ACCESS_TOKEN',
+    :expires_at => 1485373937,
+    :expires => true,
+    :refresh_token => 'REFRESH_TOKEN',
+    :id_token => 'JWT_ID_TOKEN',
+    :token_type => 'bearer',
+  },
+  :extra => {
+    :raw_info => {
+      :email => 'johnfoo@example.org',
+      :email_verified => 'true',
+      :name => 'John Foo',
+      :picture => 'https://example.org/john.jpg',
+      :user_id => 'auth0|USER_ID',
+      :nickname => 'john',
+      :created_at => '2014-07-15T17:19:50.387Z'
+    }
+  }
+}
 ```
 
-### Auth Hash
+### Query Parameter Options
 
-Auth0 strategy will have the standard OmniAuth hash attributes:
+In some scenarios, you may need to pass specific query parameters to `/authorize`. The following parameters are available to enable this:
 
-- provider: the name of the strategy, in this case `auth0`
-- uid: the user identifier
-- info: the result of the call to /userinfo using OmniAuth standard attributes
-- credentials: Auth0 tokens, at least will have an access_token but can eventually have refresh_token and/or id_token
-- extra: Additional info obtained from calling /userinfo in the attribute `raw_info`
+- `connection`
+- `connection_scope`
+- `prompt`
+- `screen_hint` (only relevant to New Universal Login Experience)
 
-```ruby
-	{
-	  :provider => 'auth0',
-	  :uid => 'google-oauth2|this-is-the-google-id',
-	  :info => {
-	    :name => 'John Foo',
-	    :email => 'johnfoo@example.org',
-	    :nickname => 'john',
-	    :image => 'https://example.org/john.jpg'
-	  },
-	  :credentials => {
-	    :token => 'XdDadllcas2134rdfdsI',
-	    :expires_at => 1485373937,
-        :expires => true,
-        :refresh_token => 'aKNajdjfj123nBasd',
-	    :id_token => 'eyJhbGciOiJIUzI1NiIsImN0eSI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBGb28ifQ.lxAiy1rqve8ZHQEQVehUlP1sommPHVJDhgPgFPnDosg',
-	    :token_type => 'bearer',
-	  },
-	  :extra => {
-	    :raw_info => {
-	      :email => 'johnfoo@example.org',
-	      :email_verified => 'true',
-	      :name => 'John Foo',
-	      :picture => 'https://example.org/john.jpg',
-	      :user_id => 'google-oauth2|this-is-the-google-id',
-	      :nickname => 'john',
-	      :created_at: '2014-07-15T17:19:50.387Z'
-	    }
-	  }
-	}
-```
+Simply pass these query parameters to your OmniAuth redirect endpoint to enable their behavior.
 
-### ActionDispatch::Cookies::CookieOverflow issue
+## Contribution
 
-If you are getting this error it means that you are using Cookie sessions and since you are storing the whole profile it overflows the max-size of 4K.
+We appreciate feedback and contribution to this repo! Before you get started, please see the following:
 
-You can change to use In-Memory store for development as follows:
+- [Auth0's contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
+- [Auth0's Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
+- [This repo's contribution guide](CONTRIBUTING.md)
 
-	# /config/initializers/session_store.rb
-	CrazyApp::Application.config.session_store :cache_store
+## Support + Feedback
 
-	# /config/environments/development.rb
-	config.cache_store = :memory_store
+- Use [Community](https://community.auth0.com/) for usage, questions, specific cases.
+- Use [Issues](https://github.com/auth0/omniauth-auth0/issues) here for code-level support and bug reports.
+- Paid customers can use [Support](https://support.auth0.com/) to submit a trouble ticket for production-affecting issues.
 
-## Documentation
+## Vulnerability Reporting
 
-For more information about [auth0](http://auth0.com) contact our [documentation page](http://docs.auth0.com/).
+Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
 
-## Issue Reporting
+## What is Auth0?
 
-If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
+Auth0 helps you to easily:
 
-## Author
+- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
+- log in users with username/password databases, passwordless, or multi-factor authentication
+- link multiple user accounts together
+- generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
+- access demographics and analytics detailing how, when, and where users are logging in
+- enrich user profiles from other data sources using customizable JavaScript rules
 
-[Auth0](https://auth0.com)
+[Why Auth0?](https://auth0.com/why-auth0)
 
 ## License
 
-This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
+The OmniAuth Auth0 strategy is licensed under MIT - [LICENSE](LICENSE)
+
+
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fomniauth-auth0.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fomniauth-auth0?ref=badge_large)

data/Rakefile

@@ -10,7 +10,7 @@ begin
   RuboCop::RakeTask.new
 rescue LoadError
   task :rubocop do
-    $stderr.puts 'Rubocop is disabled'
+    warn 'Rubocop is disabled'
   end
 end
 
@@ -23,7 +23,7 @@ namespace :sinatra do
 end
 
 desc 'Run specs'
-task default: [:spec, :rubocop]
+task default: %i[spec rubocop]
 task test: :spec
 task :guard do
   system 'bundle exec guard'

data/codecov.yml

@@ -0,0 +1,22 @@
+coverage:
+  precision: 2
+  round: down
+  range: "60...100"
+  status:
+    project:
+      default:
+        enabled: true
+        target: auto
+        threshold: 5%
+        if_no_uploads: error
+    patch:
+      default:
+        enabled: true
+        target: 80%
+        threshold: 30%
+        if_no_uploads: error
+    changes:
+      default:
+        enabled: true
+        if_no_uploads: error
+comment: false 

data/lib/omniauth-auth0.rb

@@ -1,2 +1,2 @@
-require 'omniauth-auth0/version' # rubocop:disable Style/FileName
+require 'omniauth-auth0/version'
 require 'omniauth/strategies/auth0'

data/lib/omniauth-auth0/version.rb

@@ -1,5 +1,5 @@
 module OmniAuth
   module Auth0
-    VERSION = '2.0.0'.freeze
+    VERSION = '2.4.0'.freeze
   end
 end

data/lib/omniauth/auth0/errors.rb

@@ -0,0 +1,11 @@
+module OmniAuth
+  module Auth0
+    class TokenValidationError < StandardError
+      attr_reader :error_reason
+      def initialize(msg)
+        @error_reason = msg
+        super(msg)
+      end
+    end
+  end
+end

data/lib/omniauth/auth0/jwt_validator.rb

@@ -0,0 +1,228 @@
+require 'base64'
+require 'uri'
+require 'json'
+require 'omniauth'
+require 'omniauth/auth0/errors'
+
+module OmniAuth
+  module Auth0
+    # JWT Validator class
+    class JWTValidator
+      attr_accessor :issuer, :domain
+
+      # Initializer
+      # @param options object
+      #   options.domain - Application domain.
+      #   options.issuer - Application issuer (optional).
+      #   options.client_id - Application Client ID.
+      #   options.client_secret - Application Client Secret.
+
+      def initialize(options, authorize_params = {})
+        @domain = uri_string(options.domain)
+
+        # Use custom issuer if provided, otherwise use domain
+        @issuer = @domain
+        @issuer = uri_string(options.issuer) if options.respond_to?(:issuer)
+
+        @client_id = options.client_id
+        @client_secret = options.client_secret
+      end
+
+      def verify_signature(jwt)
+        head = token_head(jwt)
+
+        # Make sure the algorithm is supported and get the decode key.
+        if head[:alg] == 'RS256'
+          [rs256_decode_key(head[:kid]), head[:alg]]
+        elsif head[:alg] == 'HS256'
+          [@client_secret, head[:alg]]
+        else
+          raise OmniAuth::Auth0::TokenValidationError.new("Signature algorithm of #{head[:alg]} is not supported. Expected the ID token to be signed with RS256 or HS256")
+        end
+      end
+
+      # Verify a JWT.
+      # @param jwt string - JWT to verify.
+      # @param authorize_params hash - Authorization params to verify on the JWT
+      # @return hash - The verified token, if there were no exceptions.
+      def verify(jwt, authorize_params = {})
+        if !jwt
+          raise OmniAuth::Auth0::TokenValidationError.new('ID token is required but missing')
+        end
+
+        parts = jwt.split('.')
+        if parts.length != 3
+          raise OmniAuth::Auth0::TokenValidationError.new('ID token could not be decoded')
+        end
+
+        key, alg = verify_signature(jwt)
+        id_token, header = JWT.decode(jwt, key, false)
+        verify_claims(id_token, authorize_params)
+
+        return id_token
+      end
+
+      # Get the decoded head segment from a JWT.
+      # @return hash - The parsed head of the JWT passed, empty hash if not.
+      def token_head(jwt)
+        jwt_parts = jwt.split('.')
+        return {} if blank?(jwt_parts) || blank?(jwt_parts[0])
+
+        json_parse(Base64.decode64(jwt_parts[0]))
+      end
+
+      # Get the JWKS from the issuer and return a public key.
+      # @param x5c string - X.509 certificate chain from a JWKS.
+      # @return key - The X.509 certificate public key.
+      def jwks_public_cert(x5c)
+        x5c = Base64.decode64(x5c)
+
+        # https://docs.ruby-lang.org/en/2.4.0/OpenSSL/X509/Certificate.html
+        OpenSSL::X509::Certificate.new(x5c).public_key
+      end
+
+      # Return a specific key from a JWKS object.
+      # @param key string - Key to find in the JWKS.
+      # @param kid string - Key ID to identify the right JWK.
+      # @return nil|string
+      def jwks_key(key, kid)
+        return nil if blank?(jwks[:keys])
+
+        matching_jwk = jwks[:keys].find { |jwk| jwk[:kid] == kid }
+        matching_jwk[key] if matching_jwk
+      end
+
+      private
+      def rs256_decode_key(kid)
+        jwks_x5c = jwks_key(:x5c, kid)
+
+        if jwks_x5c.nil?
+          raise OmniAuth::Auth0::TokenValidationError.new("Could not find a public key for Key ID (kid) '#{kid}''")
+        end
+
+        jwks_public_cert(jwks_x5c.first)
+      end
+
+      # Get a JWKS from the domain
+      # @return void
+      def jwks
+        jwks_uri = URI(@domain + '.well-known/jwks.json')
+        @jwks ||= json_parse(Net::HTTP.get(jwks_uri))
+      end
+
+      # Rails Active Support blank method.
+      # @param obj object - Object to check for blankness.
+      # @return boolean
+      def blank?(obj)
+        obj.respond_to?(:empty?) ? obj.empty? : !obj
+      end
+
+      # Parse JSON with symbolized names.
+      # @param json string - JSON to parse.
+      # @return hash
+      def json_parse(json)
+        JSON.parse(json, symbolize_names: true)
+      end
+
+      # Parse a URI into the desired string format
+      # @param uri - the URI to parse
+      # @return string
+      def uri_string(uri)
+        temp_domain = URI(uri)
+        temp_domain = URI("https://#{uri}") unless temp_domain.scheme
+        "#{temp_domain}/"
+      end
+
+      def verify_claims(id_token, authorize_params)
+        leeway = authorize_params[:leeway] || 60
+        max_age = authorize_params[:max_age]
+        nonce = authorize_params[:nonce]
+
+        verify_iss(id_token)
+        verify_sub(id_token)
+        verify_aud(id_token)
+        verify_expiration(id_token, leeway)
+        verify_iat(id_token)
+        verify_nonce(id_token, nonce)
+        verify_azp(id_token)
+        verify_auth_time(id_token, leeway, max_age)
+      end
+
+      def verify_iss(id_token)
+        issuer = id_token['iss']
+        if !issuer
+          raise OmniAuth::Auth0::TokenValidationError.new("Issuer (iss) claim must be a string present in the ID token")
+        elsif @issuer != issuer
+          raise OmniAuth::Auth0::TokenValidationError.new("Issuer (iss) claim mismatch in the ID token, expected (#{@issuer}), found (#{id_token['iss']})")
+        end
+      end
+
+      def verify_sub(id_token)
+        subject = id_token['sub']
+        if !subject || !subject.is_a?(String) || subject.empty?
+          raise OmniAuth::Auth0::TokenValidationError.new('Subject (sub) claim must be a string present in the ID token')
+        end
+      end
+
+      def verify_aud(id_token)
+        audience = id_token['aud']
+        if !audience || !(audience.is_a?(String) || audience.is_a?(Array))
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim must be a string or array of strings present in the ID token")
+        elsif audience.is_a?(Array) && !audience.include?(@client_id)
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim mismatch in the ID token; expected #{@client_id} but was not one of #{audience.join(', ')}")
+        elsif audience.is_a?(String) && audience != @client_id
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim mismatch in the ID token; expected #{@client_id} but found #{audience}")
+        end
+      end
+
+      def verify_expiration(id_token, leeway)
+        expiration = id_token['exp']
+        if !expiration || !expiration.is_a?(Integer)
+          raise OmniAuth::Auth0::TokenValidationError.new("Expiration time (exp) claim must be a number present in the ID token")
+        elsif expiration <= Time.now.to_i - leeway
+          raise OmniAuth::Auth0::TokenValidationError.new("Expiration time (exp) claim error in the ID token; current time (#{Time.now}) is after expiration time (#{Time.at(expiration + leeway)})")
+        end
+      end
+
+      def verify_iat(id_token)
+        if !id_token['iat']
+          raise OmniAuth::Auth0::TokenValidationError.new("Issued At (iat) claim must be a number present in the ID token")
+        end
+      end
+
+      def verify_nonce(id_token, nonce)
+        if nonce
+          received_nonce = id_token['nonce']
+          if !received_nonce
+            raise OmniAuth::Auth0::TokenValidationError.new("Nonce (nonce) claim must be a string present in the ID token")
+          elsif nonce != received_nonce
+            raise OmniAuth::Auth0::TokenValidationError.new("Nonce (nonce) claim value mismatch in the ID token; expected (#{nonce}), found (#{received_nonce})")
+          end
+        end
+      end
+
+      def verify_azp(id_token)
+        audience = id_token['aud']
+        if audience.is_a?(Array) && audience.length > 1
+          azp = id_token['azp']
+          if !azp || !azp.is_a?(String)
+            raise OmniAuth::Auth0::TokenValidationError.new("Authorized Party (azp) claim must be a string present in the ID token when Audience (aud) claim has multiple values")
+          elsif azp != @client_id
+            raise OmniAuth::Auth0::TokenValidationError.new("Authorized Party (azp) claim mismatch in the ID token; expected (#{@client_id}), found (#{azp})")
+          end
+        end
+      end
+
+      def verify_auth_time(id_token, leeway, max_age)
+        if max_age
+          auth_time = id_token['auth_time']
+          if !auth_time || !auth_time.is_a?(Integer)
+            raise OmniAuth::Auth0::TokenValidationError.new("Authentication Time (auth_time) claim must be a number present in the ID token when Max Age (max_age) is specified")
+          elsif Time.now.to_i >  auth_time + max_age + leeway;
+            raise OmniAuth::Auth0::TokenValidationError.new("Authentication Time (auth_time) claim in the ID token indicates that too much time has passed since the last end-user authentication. Current time (#{Time.now}) is after last auth time (#{Time.at(auth_time + max_age + leeway)})")
+          end
+        end
+      end
+    end
+  end
+end