cerner-oauth1a 1.0.1 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 11d5187c40396ed12957bfbf5bb06a95b6473276
-  data.tar.gz: 721aff2530e06b363d38570fa1f4c3de2f456ebc
+SHA256:
+  metadata.gz: 93df035b09b74b1936a6b14305ffa17f80f079deeacd2af9ec1d3f9e8797cd35
+  data.tar.gz: b5b00bf3cae57f9948c117c77aa0a6a0723f8af81d085323788f24508af05309
 SHA512:
-  metadata.gz: b2339a067f8ff9360a0c6e70b4656c2cd44e6f74f044eae55feb19670f2aba37bd74fb95af0df30ba6307e66a7b177a5950c056c147948d907db074ab14f628f
-  data.tar.gz: 15a89f6cc5c896428e9346df144d3a659c8e6577a0ffb971a5349c6e3131d2249e4b70f87d71632bd3a0de35ced170f53731f029002502b5ec3a9d87bd7bf16a
+  metadata.gz: 00b0f14065ff87925fb372f92b9365fdaaf00e26b737673b68bd2df4ace4cdb50e33ec5a26a32a695f8c9f5871280b9106f9c9edae5045182e9287cf7ad87f06
+  data.tar.gz: 46ce88a5cf635524e619f447c8a95f99d5c240b40213c74839c7c2d1fc261ec5e7f0b02485eee0ddb98525f744a46f09f52cca8c3686919a08a79f360dbfd2e7

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# v2.0.0
+Added APIs for authenticating Access Tokens, so that service providers can be implemented
+with this library.
+
+Behavior changes:
+* accessor_secret is no longer required to construct a Cerner::OAuth1a::AccessToken
+* token_secret is no longer required to construct a Cerner::OAuth1a::AccessToken
+* expires_at is no longer required to construct a Cerner::OAuth1a::AccessToken
+
 # v1.0.1
 Correct confusing functionality within AccessToken#expired?, so that it's
 no longer surprising and backwards.

data/NOTICE

@@ -1,4 +1,4 @@
-Copyright 2017 Cerner Innovation, Inc.
+Copyright 2018 Cerner Innovation, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/README.md

@@ -1,32 +1,32 @@
-# Cerner OAuth 1.0a Client Library
+# Cerner OAuth 1.0a Consumer and Service Provider Library
 
-This RubyGem is a client library for interacting with the Cerner OAuth 1.0a provider to
-participate in two-legged (B2B) authentication. The goal of this project is to provide a zero-dependency Ruby library that simply and compactly implements the client aspects of
-Cerner OAuth 1.0a variant of the OAuth 1.0a B2B workflow.
+[![Build Status](https://api.travis-ci.org/cerner/cerner-oauth1a.svg)](https://travis-ci.org/cerner/cerner-oauth1a)
+[![Gem Version](http://img.shields.io/gem/v/cerner-oauth1a.svg)](https://rubygems.org/gems/cerner-oauth1a)
+[![Code Climate](http://img.shields.io/codeclimate/github/cerner/cerner-oauth1a.svg)](https://codeclimate.com/github/cerner/cerner-oauth1a)
+[![Dependencies Status](http://img.shields.io/gemnasium/cerner/cerner-oauth1a.svg)](https://gemnasium.com/cerner/cerner-oauth1a)
 
-# Usage
-
-## Install
-This library can be installed using the `gem` command or added to a Gemfile for use with Bundler.
-
-### `gem` command
+A minimal dependency library for interacting with a Cerner OAuth 1.0a Access Token Service for
+invoking Cerner OAuth 1.0a protected services or implementing Cerner OAuth 1.0a authentication.
+Cerner's OAuth 1.0a Access Token Service provides a means for facilitating two-legged (B2B)
+authentication via a variant of OAuth 1.0a.
 
-    $ gem install cerner-oauth1a
-
-### Gemfile
+# Usage
 
-    gem 'cerner-oauth1a', '~> 1.0'
+There are two use cases for working with this library: Consumer and Service Provider. The Consumer
+Use Case is for invoking services protected by Cerner OAuth 1.0a. The Service Provider Use Case is
+for implementing a Ruby-based service.
 
-## Basic Use
+## Consumer Use Case
 
     require 'cerner/oauth1a'
     require 'net/http'
 
-    # Setup the AccessTokenAgent with an Access Token URL, Key and Secret
+    # Setup the AccessTokenAgent with an Access Token Service's URL, a Key and a Secret
     agent = Cerner::OAuth1a::AccessTokenAgent.new(
-              access_token_url: 'https://api.cernercare.com/oauth/access',
-              consumer_key: 'CONSUMER_KEY',
-              consumer_secret: 'CONSUMER_SECRET')
+      access_token_url: 'https://api.cernercare.com/oauth/access',
+      consumer_key: 'CONSUMER_KEY',
+      consumer_secret: 'CONSUMER_SECRET'
+    )
 
     # Retrieve an AccessToken instance
     access_token = agent.retrieve
@@ -39,7 +39,7 @@ This library can be installed using the `gem` command or added to a Gemfile for
     # Invoke the API's HTTP endpoint and use the AccessToken to generate an Authorization header
     response = http.request_get(uri.path, Authorization: access_token.authorization_header)
 
-## Access Token Reuse
+### Access Token Reuse
 Generally, you'll want to use an Access Token more than once. Access Tokens can be reused, but
 they do expire, so you'll need to acquire new tokens after one expires. All of the expiration
 information is contained in the AccessToken class and you can easily determine if a token is
@@ -54,16 +54,70 @@ implement that:
 
     response = http.request_get(uri.path, Authorization: access_token.authorization_header)
 
+## Service Provider Use Case
+
+    # Acquire Authorization header value from HTTP server's request
+    authz_header = request['Authorization']
+
+    # Parse the header value
+    access_token = AccessToken.from_authorization_header(authz_header)
+
+    # Authenticate the Access Token
+    # Note: An AccessTokenAgent, configured with a System Account that has been granted privileges
+    # to Acquire Tokens and Process Tokens.
+    begin
+      results = access_token.authenticate(agent)
+    rescue OAuthError => e
+      # respond with a 401
+    end
+
+    # Use Consumer Key (i.e. the System Account) to do further authorization, as appropriate
+    system_account_id = access_token.consumer_key
+
+    # Optionally, extract additional parameters sent with the token, such as Consumer.Principal
+    # (xoauth_principal)
+    consumer_principal = results[:"Consumer.Principal"]
+
 ## References
 * https://wiki.ucern.com/display/public/reference/Cerner%27s+OAuth+Specification
   * http://oauth.net/core/1.0a
   * http://oauth.pbwiki.com/ProblemReporting
 * https://wiki.ucern.com/display/public/reference/Accessing+Cerner%27s+Web+Services+Using+OAuth+1.0a
 
+# Installing
+This library can be installed using the `gem` command or added to a Gemfile for use with Bundler.
+
+## `gem` command
+
+    $ gem install cerner-oauth1a
+
+## Gemfile
+
+    gem 'cerner-oauth1a', '~> 2.0'
+
 # Building
 
-This project is built using Ruby 2.2+, Rake and Bundler. RSpec is used for unit tests and SimpleCov
-is utilized for test coverage.
+This project is built using Ruby 2.4+, Rake and Bundler. RSpec is used for unit tests and SimpleCov
+is utilized for test coverage. RuboCop is used to monitor the lint and style.
+
+## Setup
+
+To setup the development workspace, run the following after checkout:
+
+    gem install bundler
+    bundle install
+
+## Tests
+
+To run the RSpec tests, run the following:
+
+    bin/rspec
+
+## Lint
+
+To analyze the project's style and lint, run the following:
+
+    bin/rubocop
 
 # Availability
 
@@ -79,7 +133,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 # LICENSE
 
-Copyright 2017 Cerner Innovation, Inc.
+Copyright 2018 Cerner Innovation, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 

data/lib/cerner/oauth1a.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
 require 'cerner/oauth1a/access_token'
 require 'cerner/oauth1a/access_token_agent'
+require 'cerner/oauth1a/keys'
+require 'cerner/oauth1a/protocol'
 require 'cerner/oauth1a/version'

data/lib/cerner/oauth1a/access_token.rb

@@ -1,92 +1,216 @@
+# frozen_string_literal: true
+
+require 'cerner/oauth1a/oauth_error'
+require 'cerner/oauth1a/protocol'
+require 'uri'
+
 module Cerner
   module OAuth1a
 
-    # Public: An OAuth 1.0a Access Token.
+    # Public: A Cerner OAuth 1.0a Access Token and related request parameters for use in Consumer or
+    # Service Provider use cases.
     class AccessToken
+      # Public: Constructs an AccessToken using the value of an HTTP Authorization Header based on
+      # the OAuth HTTP Authorization Scheme (https://oauth.net/core/1.0a/#auth_header).
+      #
+      # value - A String containing the HTTP Authorization Header value.
+      #
+      # Returns an AccessToken.
+      #
+      # Raises a Cerner::OAuth1a::OAuthError with a populated oauth_problem if any of the parameters
+      # in the value are invalid.
+      def self.from_authorization_header(value)
+        params = Protocol.parse_authorization_header(value)
+
+        raise OAuthError.new('', nil, 'version_rejected') unless params[:oauth_version]&.eql?('1.0')
+
+        missing_params = []
+        consumer_key = params[:oauth_consumer_key]
+        missing_params << :oauth_consumer_key unless consumer_key&.empty?
+        nonce = params[:oauth_nonce]
+        missing_params << :oauth_nonce unless nonce&.empty?
+        timestamp = params[:oauth_timestamp]
+        missing_params << :oauth_timestamp unless timestamp&.empty?
+        token = params[:oauth_token]
+        missing_params << :oauth_token unless token&.empty?
+        signature_method = params[:oauth_signature_method]
+        missing_params << :oauth_signature_method unless signature_method&.empty?
+        signature = params[:oauth_signature]
+        missing_params << :oauth_signature unless signature&.empty?
+
+        raise OAuthError.new('', nil, 'parameter_absent', missing_params) unless missing_params.empty?
+
+        AccessToken.new(
+          consumer_key: consumer_key,
+          nonce: nonce,
+          timestamp: timestamp,
+          token: token,
+          signature_method: signature_method,
+          signature: signature
+        )
+      end
+
       # Returns the String Accessor Secret related to this token.
       attr_reader :accessor_secret
-      # Returns the String Consumer Key related to this token.
+      # Returns the String Consumer Key (oauth_consumer_key) related to this token.
       attr_reader :consumer_key
       # Returns the Time this token expires at.
       attr_reader :expires_at
-      # Returns the String nonce related to this token.
+      # Returns the String nonce (oauth_nonce) related to this token.
       attr_reader :nonce
-      # Returns the Time this token was created.
+      # Returns the Time this token was created (oauth_timestamp).
       attr_reader :timestamp
-      # Returns the String Token.
+      # Returns the String Token (oauth_token).
       attr_reader :token
       # Returns the String Token Secret related to this token.
       attr_reader :token_secret
+      # Returns the String Signature Method (oauth_signature_method) related to this token.
+      attr_reader :signature_method
+      # Returns the String Signature (oauth_signature) related to this token.
+      attr_reader :signature
 
       # Public: Constructs an instance.
       #
       # arguments - The keyword arguments of the method:
-      #             :accessor_secret - The String representing the accessor secret.
-      #             :consumer_key    - The String representing the consumer key.
-      #             :expires_at      - A Time representing the expiration moment or any object
-      #                                responding to to_i that represents the expiration moment
-      #                                as the number of seconds since the epoch.
-      #             :nonce           - The String representing the nonce.
-      #             :expires_at      - A Time representing the creation moment or any object
-      #                                responding to to_i that represents the creation moment
-      #                                as the number of seconds since the epoch.
-      #             :token           - The String representing the token.
-      #             :token_secret    - The String representing the token secret.
-      #
-      # Raises ArgumentError if any of the arguments is nil
-      def initialize(accessor_secret:, consumer_key:, expires_at:, nonce:, timestamp:, token:, token_secret:)
-        raise ArgumentError, 'accessor_secret is nil' unless accessor_secret
+      #             :accessor_secret  - The optional String representing the accessor secret.
+      #             :consumer_key     - The required String representing the consumer key.
+      #             :expires_at       - An optional Time representing the expiration moment or any
+      #                                 object responding to to_i that represents the expiration
+      #                                 moment as the number of seconds since the epoch.
+      #             :nonce            - The required String representing the nonce.
+      #             :timestamp        - A required Time representing the creation moment or any
+      #                                 object responding to to_i that represents the creation
+      #                                 moment as the number of seconds since the epoch.
+      #             :token            - The required String representing the token.
+      #             :token_secret     - The required String representing the token secret.
+      #             :signature_method - The optional String representing the signature method.
+      #                                 Defaults to PLAINTEXT.
+      #             :signature        - The optional String representing the signature.
+      #                                 Defaults to nil.
+      #
+      # Raises ArgumentError if consumer_key, nonce, timestamp, token or signature_method is nil.
+      def initialize(
+        accessor_secret: nil,
+        consumer_key:,
+        expires_at: nil,
+        nonce:,
+        signature: nil,
+        signature_method: 'PLAINTEXT',
+        timestamp:,
+        token:,
+        token_secret: nil
+      )
         raise ArgumentError, 'consumer_key is nil' unless consumer_key
-        raise ArgumentError, 'expires_at is nil' unless expires_at
         raise ArgumentError, 'nonce is nil' unless nonce
         raise ArgumentError, 'timestamp is nil' unless timestamp
         raise ArgumentError, 'token is nil' unless token
-        raise ArgumentError, 'token_secret is nil' unless token_secret
 
-        @accessor_secret = accessor_secret
+        @accessor_secret = accessor_secret || nil
+        @authorization_header = nil
         @consumer_key = consumer_key
-        @expires_at = convert_to_time(expires_at)
+        @expires_at = expires_at ? convert_to_time(expires_at) : nil
         @nonce = nonce
+        @signature = signature
+        @signature_method = signature_method || 'PLAINTEXT'
         @timestamp = convert_to_time(timestamp)
         @token = token
-        @token_secret = token_secret
-        @authorization_header = nil
+        @token_secret = token_secret || nil
       end
 
-      # Public: Generates a value suitable for use as an HTTP Authorization header.
+      # Public: Generates a value suitable for use as an HTTP Authorization header. If #signature is
+      # nil, then #accessor_secret and #token_secret will be used to build a signature via the
+      # PLAINTEXT method.
       #
       # Returns a String representation of the access token.
+      #
+      # Raises Cerner::OAuth1a::OAuthError if #signature_method is not PLAINTEXT or if a signature
+      # can't be determined.
       def authorization_header
         return @authorization_header if @authorization_header
 
+        unless @signature_method == 'PLAINTEXT'
+          raise OAuthError.new('signature_method must be PLAINTEXT', nil, 'signature_method_rejected')
+        end
+
+        if @signature
+          sig = @signature
+        elsif @accessor_secret && @token_secret
+          sig = "#{@accessor_secret}&#{@token_secret}"
+        else
+          raise OAuthError.new('accessor_secret or token_secret is nil', nil, 'parameter_absent')
+        end
+
         tuples = {
           oauth_version: '1.0',
-          oauth_signature_method: 'PLAINTEXT',
-          oauth_signature: "#{@accessor_secret}&#{@token_secret}",
+          oauth_signature_method: @signature_method,
+          oauth_signature: sig,
           oauth_consumer_key: @consumer_key,
           oauth_nonce: @nonce,
           oauth_timestamp: @timestamp.tv_sec,
           oauth_token: @token
         }
-        @authorization_header = "OAuth " + tuples.map { |k, v| "#{k}=\"#{URI.encode_www_form_component(v)}\"" }.join(', ')
+        @authorization_header = Protocol.generate_authorization_header(tuples)
       end
 
-      # Public: Check whether the access token has expired. By default (with no arguments),
-      # the method checks whether the token has expired based on the current time and a fudge
-      # factor of 300 seconds (5 minutes). Non-default argument values can be used to see whether the
-      # access token has expired at a different time and with a different fudge factor.
+      # Public: Authenticates the #token against the #consumer_key, #signature and side-channel
+      # secrets exchange via AccessTokenAgent#retrieve_keys.
+      #
+      # access_token_agent - An instance of Cerner::OAuth1a::AccessTokenAgent configured with
+      #                      appropriate credentials to retrieve secrets via
+      #                      Cerner::OAuth1a::AccessTokenAgent#retrieve_keys.
       #
-      # now       - A Time instance to check the expiration information against. Default is Time.now.
+      # Returns a Hash (symbolized keys) of any extra parameters in #token if authentication succeeds.
+      #
+      # Raises ArgumentError if access_token_agent is nil
+      # Raises Cerner::OAuth1a::OAuthError with an oauth_problem if authentication fails.
+      def authenticate(access_token_agent)
+        raise ArgumentError, 'access_token_agent is nil' unless access_token_agent
+
+        unless @signature_method == 'PLAINTEXT'
+          raise OAuthError.new('signature_method must be PLAINTEXT', nil, 'signature_method_rejected')
+        end
+
+        tuples = Protocol.parse_url_query_string(@token)
+
+        unless @consumer_key == tuples.delete(:ConsumerKey)
+          raise OAuthError.new('consumer keys do not match', nil, 'consumer_key_rejected')
+        end
+
+        verify_expiration(tuples.delete(:ExpiresOn))
+
+        keys = load_keys(access_token_agent, tuples.delete(:KeysVersion))
+
+        verify_token(keys)
+        # RSASHA1 param gets consumed in #verify_token, so remove it too
+        tuples.delete(:RSASHA1)
+
+        verify_signature(keys, tuples.delete(:HMACSecrets))
+
+        tuples
+      end
+
+      # Public: Check whether the access token has expired, if #expires_at is not nil. By default
+      # (with no arguments), the method checks whether the token has expired based on the current
+      # time and a fudge factor of 300 seconds (5 minutes). Non-default argument values can be used
+      # to see whether the access token has expired at a different time and with a different fudge
+      # factor.
+      #
+      # now       - A Time instance to check the expiration information against. Defaults to
+      #             Time.now.
       # fudge_sec - The number of seconds to remove from #expires_at to adjust the comparison.
       #
-      # Returns true if the access token as expired; false otherwise
+      # Returns true if the access token is expired or #expires_at is nil; false otherwise
       def expired?(now: Time.now, fudge_sec: 300)
+        # if @expires_at is nil, return true now
+        return true unless @expires_at
         now = convert_to_time(now)
-        now.tv_sec >= expires_at.tv_sec - fudge_sec
+        now.tv_sec >= @expires_at.tv_sec - fudge_sec
       end
 
       # Public: Compare this to other based on attributes.
       #
+      # other - The AccessToken to compare this to.
+      #
       # Return true if equal; false otherwise
       def ==(other)
         accessor_secret == other.accessor_secret &&
@@ -95,11 +219,15 @@ module Cerner
           nonce == other.nonce &&
           timestamp == other.timestamp &&
           token == other.token &&
-          token_secret == other.token_secret
+          token_secret == other.token_secret &&
+          signature_method == other.signature_method &&
+          signature == other.signature
       end
 
       # Public: Compare this to other based on the attributes. Equivalent to calling #==.
       #
+      # other - The AccessToken to compare this to.
+      #
       # Return true if equal; false otherwise
       def eql?(other)
         self == other
@@ -116,14 +244,19 @@ module Cerner
           nonce: @nonce,
           timestamp: @timestamp,
           token: @token,
-          token_secret: @token_secret
+          token_secret: @token_secret,
+          signature_method: @signature_method,
+          signature: @signature
         }
       end
 
       private
 
       # Internal: Used by #initialize and #expired? to convert data into a Time instance.
-      # Returns a Time instance in the UTC time zone
+      #
+      # time - Time or any object with a #to_i the returns an Integer.
+      #
+      # Returns a Time instance in the UTC time zone.
       def convert_to_time(time)
         raise ArgumentError, 'time is nil' unless time
         if time.is_a? Time
@@ -132,7 +265,57 @@ module Cerner
           Time.at(time.to_i).utc
         end
       end
-    end
 
+      # Internal: Used by #authenticate to verify the expiration time.
+      #
+      # expires_on - The ExpiresOn parameter of oauth_token
+      #
+      # Raises OAuthError if the parameter is invalid or expired
+      def verify_expiration(expires_on)
+        raise OAuthError.new('token missing ExpiresOn', nil, 'oauth_parameters_rejected') unless expires_on
+        expires_on = convert_to_time(expires_on)
+        now = convert_to_time(Time.now)
+        raise OAuthError.new('token has expired', nil, 'token_expired') if now.tv_sec >= expires_on.tv_sec
+      end
+
+      def load_keys(access_token_agent, keys_version)
+        raise OAuthError.new('token missing KeysVersion', nil, 'oauth_parameters_rejected') unless keys_version
+        access_token_agent.retrieve_keys(keys_version)
+      end
+
+      # Internal: Used by #authenticate to verify the oauth_token value.
+      #
+      # keys - The Keys instance that contains the key used to sign the oauth_token
+      #
+      # Raises OAuthError if the parameter is not authentic
+      def verify_token(keys)
+        unless keys.verify_rsasha1_signature(@token)
+          raise OAuthError.new('token is not authentic', nil, 'oauth_parameters_rejected')
+        end
+      end
+
+      # Internal: Used by #authenticate to verify the request signature.
+      #
+      # keys         - The Keys instance that contains the key used to encrypt the HMACSecrets
+      # hmac_secrets - The HMACSecrets parameter of oauth_token
+      #
+      # Raises OAuthError if there is no signature, the parameter is invalid or the signature does
+      # not match the secrets
+      def verify_signature(keys, hmac_secrets)
+        raise OAuthError.new('missing signature', nil, 'oauth_parameters_absent') unless @signature
+        raise OAuthError.new('missing HMACSecrets', nil, 'oauth_parameters_rejected') unless hmac_secrets
+
+        begin
+          secrets = keys.decrypt_hmac_secrets(hmac_secrets)
+        rescue ArgumentError, OpenSSL::PKey::RSAError => e
+          raise OAuthError.new("unable to decrypt HMACSecrets: #{e.message}", nil, 'oauth_parameters_rejected')
+        end
+
+        secrets_parts = Protocol.parse_url_query_string(secrets)
+        expected_signature = "#{secrets_parts[:ConsumerSecret]}&#{secrets_parts[:TokenSecret]}"
+
+        raise OAuthError.new('signature is not valid', nil, 'signature_invalid') unless @signature == expected_signature
+      end
+    end
   end
 end