cerner-oauth1a 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 78e443a0c2b7b55bc787c7892ddd671af08769e4
+  data.tar.gz: 6631bda81224b2102408deae304611d63eb3b52b
+SHA512:
+  metadata.gz: d5d68c6bfa9eae2007d5331ba60349a3c5e69c911f1d771bd0cae784136205e500cc727524f271854d5ef8d495b4aed5820cb4f3940aad00ef7528eed8612191
+  data.tar.gz: d8e086be1015712861286552827300d6bb72a1c8466b8d9f55962c797c44d5adcb9daaeaebd06dfe61a06ee89235b6f2f4a2f0276267d8116f4350007e711b77

data/README.md

@@ -0,0 +1,88 @@
+# Cerner OAuth 1.0a Client 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.
+
+# Usage
+
+## Install
+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', '~> 1.0'
+
+## Basic Use
+
+    require 'cerner/oauth1a'
+    require 'net/http'
+
+    # Setup the AccessTokenAgent with an Access Token URL, Key and Secret
+    agent = Cerner::OAuth1a::AccessTokenAgent.new(
+              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
+
+    # Setup the HTTP library to access the protected API you want to invoke
+    uri = URI('https://authz-demo-api.cerner.com/me')
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true if uri.scheme == 'https'
+
+    # 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
+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
+expired or about to by using the AccessToken#expired? method. Below is an example of you might
+implement that:
+
+    uri = URI('https://authz-demo-api.cerner.com/me')
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true if uri.scheme == 'https'
+
+    access_token = agent.retrieve if access_token.expired?
+
+    response = http.request_get(uri.path, Authorization: access_token.authorization_header)
+
+## 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
+
+# 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.
+
+# Availability
+
+This RubyGem will be available on https://rubygems.org/.
+
+# Communication
+
+All questions, bugs, enhancements and pull requests can be submitted here, on GitHub via Issues.
+
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+# LICENSE
+
+Copyright 2017 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
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

data/lib/cerner/oauth1a.rb

@@ -0,0 +1,3 @@
+require 'cerner/oauth1a/access_token'
+require 'cerner/oauth1a/access_token_agent'
+require 'cerner/oauth1a/version'

data/lib/cerner/oauth1a/access_token.rb

@@ -0,0 +1,138 @@
+module Cerner
+  module OAuth1a
+
+    # Public: An OAuth 1.0a Access Token.
+    class AccessToken
+      # Returns the String Accessor Secret related to this token.
+      attr_reader :accessor_secret
+      # Returns the String 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.
+      attr_reader :nonce
+      # Returns the Time this token was created.
+      attr_reader :timestamp
+      # Returns the String Token.
+      attr_reader :token
+      # Returns the String Token Secret related to this token.
+      attr_reader :token_secret
+
+      # 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
+        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
+        @consumer_key = consumer_key
+        @expires_at = convert_to_time(expires_at)
+        @nonce = nonce
+        @timestamp = convert_to_time(timestamp)
+        @token = token
+        @token_secret = token_secret
+        @authorization_header = nil
+      end
+
+      # Public: Generates a value suitable for use as an HTTP Authorization header.
+      #
+      # Returns a String representation of the access token.
+      def authorization_header
+        return @authorization_header if @authorization_header
+
+        tuples = {
+          oauth_version: '1.0',
+          oauth_signature_method: 'PLAINTEXT',
+          oauth_signature: "#{@accessor_secret}&#{@token_secret}",
+          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(', ')
+      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. 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. Default is Time.now.
+      # fudge_sec - The number of seconds to remove from 'now' to adjust the comparion.
+      #
+      # Returns true if the access token as expired; false otherwise
+      def expired?(now: Time.now, fudge_sec: 300)
+        now = convert_to_time(now)
+        (now.tv_sec - fudge_sec) >= expires_at.tv_sec
+      end
+
+      # Public: Compare this to other based on attributes.
+      #
+      # Return true if equal; false otherwise
+      def ==(other)
+        accessor_secret == other.accessor_secret &&
+          consumer_key == other.consumer_key &&
+          expires_at == other.expires_at &&
+          nonce == other.nonce &&
+          timestamp == other.timestamp &&
+          token == other.token &&
+          token_secret == other.token_secret
+      end
+
+      # Public: Compare this to other based on the attributes. Equivalent to calling #==.
+      #
+      # Return true if equal; false otherwise
+      def eql?(other)
+        self == other
+      end
+
+      # Public: Generates a Hash of the attributes.
+      #
+      # Returns a Hash with keys for each attribute.
+      def to_h
+        {
+          accessor_secret: @accessor_secret,
+          consumer_key: @consumer_key,
+          expires_at: @expires_at,
+          nonce: @nonce,
+          timestamp: @timestamp,
+          token: @token,
+          token_secret: @token_secret
+        }
+      end
+
+      private
+
+      # Internal: Used by #initialize and #expired? to convert data into a Time instance.
+      # 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
+          time.utc
+        else
+          Time.at(time.to_i).utc
+        end
+      end
+    end
+
+  end
+end

data/lib/cerner/oauth1a/access_token_agent.rb

@@ -0,0 +1,179 @@
+require 'cerner/oauth1a/access_token'
+require 'cerner/oauth1a/oauth_error'
+require 'cerner/oauth1a/version'
+require 'net/https'
+require 'securerandom'
+require 'uri'
+
+module Cerner
+  module OAuth1a
+
+    # Public: A User Agent for interacting with the Access Token service to acquire
+    # Access Tokens.
+    class AccessTokenAgent
+      MIME_WWW_FORM_URL_ENCODED = 'application/x-www-form-urlencoded'
+
+      # Returns the URI Access Token URL.
+      attr_reader :access_token_url
+      # Returns the String Consumer Key.
+      attr_reader :consumer_key
+      # Returns the String Consumer Secret.
+      attr_reader :consumer_secret
+
+      # Public: Constructs an instance of the agent.
+      #
+      # arguments - The keyword arguments of the method:
+      #             :access_token_url - The String or URI of the Access Token service endpoint.
+      #             :consumer_key     - The String of the Consumer Key of the account.
+      #             :consumer_secret  - The String of the Consumer Secret of the account.
+      #             :open_timeout     - An object responding to to_i. Used to set the timeout, in seconds,
+      #                                 for opening HTTP connections to the Access Token service (optional, default: 5).
+      #             :read_timeout     - An object responding to to_i. Used to set the timeout, in seconds,
+      #                                 for reading data from HTTP connections to the Access Token service (optional, default: 5).
+      #
+      # Raises ArgumentError if access_token_url, consumer_key or consumer_key is nil; if access_token_url is
+      #                      an invalid URI.
+      def initialize(access_token_url:, consumer_key:, consumer_secret:, open_timeout: 5, read_timeout: 5)
+        raise ArgumentError, 'consumer_key is nil' unless consumer_key
+        raise ArgumentError, 'consumer_secret is nil' unless consumer_secret
+
+        @consumer_key = consumer_key
+        @consumer_secret = consumer_secret
+
+        @access_token_url = convert_to_http_uri(access_token_url)
+
+        @open_timeout = (open_timeout ? open_timeout.to_i : 5)
+        @read_timeout = (read_timeout ? read_timeout.to_i : 5)
+      end
+
+      # Public: Retrives an AccessToken from the configured Access Token service endpoint (#access_token_url).
+      # This method will the #generate_accessor_secret, #generate_nonce and #generate_timestamp methods to
+      # interact with the service, which can be overridden via a sub-class, if desired.
+      #
+      # Returns a AccessToken upon success.
+      #
+      # Raises OAuthError unless the service returns a HTTP Status Code of 200.
+      # Raises StandardError sub-classes for any issues interacting with the service.
+      def retrieve
+        # construct a POST request
+        request = Net::HTTP::Post.new @access_token_url
+
+        # setup the data to construct the POST's message
+        accessor_secret = generate_accessor_secret
+        nonce = generate_nonce
+        timestamp = generate_timestamp
+        params = [
+                  [:oauth_consumer_key, @consumer_key],
+                  [:oauth_signature_method, 'PLAINTEXT'],
+                  [:oauth_version, '1.0'],
+                  [:oauth_timestamp, timestamp],
+                  [:oauth_nonce, nonce],
+                  [:oauth_signature, "#{@consumer_secret}&"],
+                  [:oauth_accessor_secret, accessor_secret]
+                 ]
+        # set the POST's body as a URL form-encoded string
+        request.set_form(params, MIME_WWW_FORM_URL_ENCODED, charset: 'UTF-8')
+
+        request['Accept'] = MIME_WWW_FORM_URL_ENCODED
+        # Set a custom User-Agent to help identify these invocation
+        request['User-Agent'] = "cerner-oauth1a #{VERSION} (Ruby #{RUBY_VERSION})"
+
+        http = Net::HTTP.new(@access_token_url.host, @access_token_url.port)
+        if @access_token_url.scheme == 'https'
+          # if the scheme is HTTPS, then enable SSL
+          http.use_ssl = true
+          # make sure to verify peers
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          # tweak the ciphers to eliminate unsafe options
+          http.ciphers = 'DEFAULT:!aNULL:!eNULL:!LOW:!SSLv2:!RC4'
+        end
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+
+        response = http.request request
+
+        case response
+        when Net::HTTPSuccess
+          # Part the HTTP response and convert it into a Symbol-keyed Hash
+          tuples = Hash[URI.decode_www_form(response.body).map { |pair| [pair[0].to_sym, pair[1]] }]
+          # Use the parsed response to construct the AccessToken
+          access_token = AccessToken.new(accessor_secret: accessor_secret,
+                                         consumer_key: @consumer_key,
+                                         expires_at: timestamp + tuples[:oauth_expires_in].to_i,
+                                         nonce: nonce,
+                                         timestamp: timestamp,
+                                         token: tuples[:oauth_token],
+                                         token_secret: tuples[:oauth_token_secret])
+          access_token
+        else
+          # Extract any OAuth Problems reported in the response
+          oauth_data = parse_www_authenticate(response['WWW-Authenticate'])
+          # Raise an error for a failure to acquire a token
+          raise OAuthError.new('unable to acquire token', response.code, oauth_data['oauth_problem'])
+        end
+      end
+
+      # Public: Generate an Accessor Secret for invocations of the Access Token service.
+      #
+      # Returns a String containing the secret.
+      def generate_accessor_secret
+        SecureRandom.uuid
+      end
+
+      # Public: Generate a Nonce for invocations of the Access Token service.
+      #
+      # Returns a String containing the nonce.
+      def generate_nonce
+        SecureRandom.hex
+      end
+
+      # Public: Generate a Timestamp for invocations of the Access Token service.
+      #
+      # Returns an Integer representing the number of seconds since the epoch.
+      def generate_timestamp
+        Time.now.to_i
+      end
+
+      private
+
+      # Internal: Parse a WWW-Authenticate HTTP header for any OAuth
+      # information, which is indicated by a value starting with 'OAuth '.
+      #
+      # value - The String containing the header value.
+      #
+      # Returns a Hash containing any name-value pairs found in the value.
+      def parse_www_authenticate(value)
+        return {} unless value
+        value = value.strip
+        return {} unless value.start_with?('OAuth ')
+
+        Hash[value.scan(/([^\s=]*)=\"([^\"]*)\"/)]
+      end
+
+      # Internal: Convert an Access Token URL into a URI with some verification checks
+      #
+      # access_token_url - A String URL or a URI instance
+      # Returns a URI::HTTP or URI::HTTPS
+      #
+      # Raises ArgumentError if access_token_url is nil, invalid or not an HTTP/HTTPS URI
+      def convert_to_http_uri(access_token_url)
+        raise ArgumentError, 'access_token_url is nil' unless access_token_url
+        if access_token_url.is_a? URI
+          uri = access_token_url
+        else
+          begin
+            uri = URI(access_token_url)
+          rescue URI::InvalidURIError => e
+            # raise argument error with cause
+            raise ArgumentError, 'access_token_url is invalid'
+          end
+        end
+        unless uri.is_a? URI::HTTP
+          raise ArgumentError, 'access_token_url must be an HTTP or HTTPS URI'
+        end
+        uri
+      end
+    end
+
+  end
+end

data/lib/cerner/oauth1a/oauth_error.rb

@@ -0,0 +1,26 @@
+module Cerner
+  module OAuth1a
+    # Public: An OAuth-specific error.
+    class OAuthError < StandardError
+      # Returns the HTTP Response Code, if any, associated with this error.
+      attr_reader :http_response_code
+      # Returns the OAuth Problem string, if any, associated with this error.
+      # See http://oauth.pbwiki.com/ProblemReporting for more information.
+      attr_reader :oauth_problem
+
+      # Public: Construct an instance with a message, optional HTTP response code
+      # and optional OAuth Problem string.
+      #
+      # message            - A descriptive message, passed to the super class.
+      # http_response_code - The HTTP response code associated with the error. Optional.
+      # oauth_problem      - The OAuth Problem string associated with the error. Optional.
+      def initialize(message, http_response_code=nil, oauth_problem=nil)
+        @http_response_code = http_response_code
+        @oauth_problem = oauth_problem
+        message += " HTTP #{@http_response_code}" if @http_response_code
+        message += " OAuth Problem #{@oauth_problem}" if @oauth_problem
+        super message
+      end
+    end
+  end
+end

data/lib/cerner/oauth1a/version.rb

@@ -0,0 +1,5 @@
+module Cerner
+  module OAuth1a
+    VERSION = '1.0.0'
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: cerner-oauth1a
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nathan Beyer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-05 00:00:00.000000000 Z
+dependencies: []
+description: A minimal dependency client library for two-legged OAuth1.0a service
+  providers, such as Cerner's OAuth 1.0aprovider.
+email:
+- nbeyer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/cerner/oauth1a.rb
+- lib/cerner/oauth1a/access_token.rb
+- lib/cerner/oauth1a/access_token_agent.rb
+- lib/cerner/oauth1a/oauth_error.rb
+- lib/cerner/oauth1a/version.rb
+homepage: http://github.com/cerner/cerner-oauth1a
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: B2B/two-legged OAuth 1.0a service client.
+test_files: []