Add support for passing Salesforce OAuth access_token (#53)

Author: Jared Pearson

README.rdoc

@@ -8,15 +8,17 @@ Add the following to your Gemfile
 
 === Authentication
 
-The client will authenticate before performing other API calls, but you can manually authenticate as well
+In order to use this client, an access token retrieved from Salesforce OAuth must be specified. See
+the [authetication documentation on developer.pardot.com](https://developer.pardot.com/kb/authentication/) for more information.
 
   require "ruby-pardot"
 
-  client = Pardot::Client.new email, password, user_key
+  version = 3 # or 4
+  access_token = '<access_token>' # Retrieve an access token from Salesforce using OAuth
+  business_unit_id = '<business_unit_id>' # Specify the Business Unit ID of the account to access
+  client = Pardot::Client.new nil, nil, nil, version, access_token, business_unit_id
 
-  # will raise a Pardot::ResponseError if login fails
-  # will raise a Pardot::NetError if the http call fails
-  client.authenticate
+Usage of the username, password, and API key authentication is deprecated and will be removed in an upcoming release.
 
 === Object Types
 

lib/pardot/authentication.rb

@@ -1,17 +1,26 @@
 module Pardot
   module Authentication
-    
+
+    # @deprecated Use of username and password authentication is deprecated.
     def authenticate
+      raise "Authentication not available when using Salesforce access token. See https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_oauth_and_connected_apps.htm for more information." if using_salesforce_access_token?
+      warn "[DEPRECATION] Use of username and password authentication is deprecated in favor of Salesforce OAuth. See https://developer.pardot.com/kb/authentication/ for more information."
       resp = post "login", nil, nil, nil, :email => @email, :password => @password, :user_key => @user_key
       update_version(resp["version"]) if resp && resp["version"]
       @api_key = resp && resp["api_key"]
     end
 
     def authenticated?
-      @api_key != nil
+      @api_key != nil || @salesforce_access_token != nil
+    end
+
+    def using_salesforce_access_token?
+      @salesforce_access_token != nil
     end
 
     def reauthenticate
+      raise "Reauthentication not available when using Salesforce access token. See https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/oauth_refresh_token_flow.htm for more information." if using_salesforce_access_token?
+      warn "[DEPRECATION] Use Salesforce OAuth to refresh the Salesforce access token. See https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/oauth_refresh_token_flow.htm for more information."
       @api_key = nil
       authenticate
     end

lib/pardot/client.rb

@@ -21,13 +21,23 @@ class Client
     include Objects::Visits
     include Objects::VisitorActivities
 
-    attr_accessor :email, :password, :user_key, :api_key, :version, :format
+    attr_accessor :email, :password, :user_key, :api_key, :version, :salesforce_access_token, :business_unit_id, :format
+
+    # @deprecated Arguments email, password and user_key are deprecated. Use salesforce_access_token with Salesforce OAuth. 
+    def initialize email = nil, password = nil, user_key = nil, version = 3, salesforce_access_token = nil, business_unit_id = nil
+      if !(email.nil? || password.nil? || user_key.nil?) then
+        warn "[DEPRECATION] Use of username and password authentication is deprecated in favor of Salesforce OAuth. See https://developer.pardot.com/kb/authentication/ for more information."
+      end
+
+      raise "business_unit_id required when using Salesforce access_token" if !salesforce_access_token.nil? && business_unit_id.nil?
+      raise "Invalid business_unit_id value. Expected ID to start with '0Uv' and be length of 18 characters." if !business_unit_id.nil? && (!business_unit_id.start_with?('0Uv') || business_unit_id.length != 18)
 
-    def initialize email, password, user_key, version = 3
       @email = email
       @password = password
       @user_key = user_key
       @version = version
+      @salesforce_access_token = salesforce_access_token
+      @business_unit_id = business_unit_id
 
       @format = "simple"
     end

lib/pardot/error.rb

@@ -2,6 +2,7 @@ module Pardot
   class Error < StandardError; end
   class NetError < Error; end
   class ExpiredApiKeyError < Error; end
+  class AccessTokenExpiredError < Error; end
 
   class ResponseError < Error
     def initialize(res)

lib/pardot/http.rb

@@ -29,6 +29,7 @@ def post object, path, params = {}, num_retries = 0, bodyParams = {}
 
     protected
 
+    # @deprecated With Salesforce OAuth, this method will never be invoked. 
     def handle_expired_api_key method, object, path, params, num_retries, e
       raise e unless num_retries == 0
 
@@ -46,7 +47,14 @@ def smooth_params object, params
 
     def create_auth_header object
       return if object == "login"
-      { :Authorization => "Pardot api_key=#{@api_key}, user_key=#{@user_key}" }
+      if using_salesforce_access_token? then
+        { 
+          :Authorization => "Bearer #{@salesforce_access_token}",
+          'Pardot-Business-Unit-Id' => @business_unit_id
+        }
+      else
+        { :Authorization => "Pardot api_key=#{@api_key}, user_key=#{@user_key}" }
+      end
     end
 
     def check_response http_response
@@ -56,6 +64,9 @@ def check_response http_response
       error ||= "Unknown Failure: #{rsp.inspect}" if rsp && rsp["stat"] == "fail"
       content = error['__content__'] if error.is_a?(Hash)
 
+      if [error, content].include?("access_token is invalid") && using_salesforce_access_token?
+        raise AccessTokenExpiredError.new "Access token is invalid. Use Salesforce OAuth to refresh the existing Salesforce access token or to retrieve a new token. See https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/oauth_refresh_token_flow.htm for more information."
+      end  
       if [error, content].include?("Invalid API key or user key") && @api_key
         raise ExpiredApiKeyError.new @api_key
       end

lib/pardot/version.rb

@@ -1,3 +1,3 @@
 module Pardot
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

spec/pardot/authentication_spec.rb

@@ -5,6 +5,32 @@
   def create_client
     @client = Pardot::Client.new "[email protected]", "foo", "bar"
   end
+
+  def create_client_using_salesforce_access_token
+    @client = Pardot::Client.new nil, nil, nil, 3, "access_token_value", '0Uv000000000001CAA'
+  end
+
+  describe "authenticate with Salesforce access_token" do
+    before do
+      @client = create_client_using_salesforce_access_token
+    end
+
+    it "raises error when calling authenticate" do
+      expect{ @client.authenticate }.to raise_error.with_message(/Authentication not available when using Salesforce access token/)
+    end
+
+    it "raises error when calling reauthenticate" do
+      expect{ @client.reauthenticate }.to raise_error.with_message(/Reauthentication not available when using Salesforce access token/)
+    end
+
+    it "returns true for authenticated" do
+      expect(@client.authenticated?).to eq(true)
+    end
+
+    it "returns true for using_salesforce_access_token" do
+      expect(@client.using_salesforce_access_token?).to eq(true)
+    end
+  end
 
   describe "authenticate" do
 
@@ -45,6 +71,13 @@ def verifyBody
       verifyBody
     end
 
+    it "returns false for using_salesforce_access_token" do
+      expect(@client.using_salesforce_access_token?).to eq(false)
+
+      authenticate
+      expect(@client.using_salesforce_access_token?).to eq(false)
+      verifyBody
+    end
   end
 
   describe "authenticateV4" do

spec/pardot/client_spec.rb

@@ -5,6 +5,33 @@
   def create_client
     @client = Pardot::Client.new "[email protected]", "foo", "bar"
   end
+
+  describe "client with Salesforce access_token" do
+
+    it "should set properties" do
+      @client = Pardot::Client.new nil, nil, nil, 3, 'access_token_value', '0Uv000000000001CAA'
+      expect(@client.email).to eq(nil)
+      expect(@client.password).to eq(nil)
+      expect(@client.user_key).to eq(nil)
+      expect(@client.api_key).to eq(nil)
+      expect(@client.version).to eq(3)
+      expect(@client.salesforce_access_token).to eq('access_token_value')
+      expect(@client.business_unit_id).to eq('0Uv000000000001CAA')
+      expect(@client.format).to eq("simple")
+    end
+
+    it "raises error with nil business_unit_id" do
+      expect{ Pardot::Client.new nil, nil, nil, 3, "access_token_value", nil }.to raise_error.with_message(/business_unit_id required when using Salesforce access_token/)
+    end
+
+    it "raises error with invalid business_unit_id due to length" do
+      expect{ Pardot::Client.new nil, nil, nil, 3, "access_token_value", '0Uv1234567890' }.to raise_error.with_message(/Invalid business_unit_id value. Expected ID to start with '0Uv' and be length of 18 characters./)
+    end
+
+    it "raises error with invalid business_unit_id due to invalid prefix" do
+      expect{ Pardot::Client.new nil, nil, nil, 3, "access_token_value", '001000000000001AAA' }.to raise_error.with_message(/Invalid business_unit_id value. Expected ID to start with '0Uv' and be length of 18 characters./)
+    end
+  end
 
   describe "client" do
     after do

spec/pardot/http_spec.rb

@@ -19,7 +19,7 @@ def get object = "foo", path = "/bar", params = {}
 
     it "should notice errors and raise them as Pardot::ResponseError" do
       fake_get "/api/foo/version/3/bar?format=simple",
-               %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
+               %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
 
 
       expect(lambda { get }).to raise_error(Pardot::ResponseError)
@@ -33,7 +33,7 @@ def get object = "foo", path = "/bar", params = {}
 
     it "should call handle_expired_api_key when the api key expires" do
       fake_get "/api/foo/version/3/bar?format=simple",
-               %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
+               %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
 
       expect(@client).to receive(:handle_expired_api_key)
       get
@@ -49,7 +49,7 @@ def post object = "foo", path = "/bar", params = {}
 
     it "should notice errors and raise them as Pardot::ResponseError" do
       fake_post "/api/foo/version/3/bar?format=simple",
-                %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
+                %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
 
       expect(lambda { post }).to raise_error(Pardot::ResponseError)
     end
@@ -62,7 +62,7 @@ def post object = "foo", path = "/bar", params = {}
 
     it "should call handle_expired_api_key when the api key expires" do
       fake_post "/api/foo/version/3/bar?format=simple",
-                %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
+                %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
 
       expect(@client).to receive(:handle_expired_api_key)
       post
@@ -79,7 +79,7 @@ def get object = "foo", path = "/bar", params = {}
 
     it "should notice errors and raise them as Pardot::ResponseError" do
       fake_get "/api/foo/version/4/bar?format=simple",
-               %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
+               %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
 
       expect(lambda { get }).to raise_error(Pardot::ResponseError)
     end
@@ -92,7 +92,7 @@ def get object = "foo", path = "/bar", params = {}
 
     it "should call handle_expired_api_key when the api key expires" do
       fake_get "/api/foo/version/4/bar?format=simple",
-               %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
+               %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
 
       expect(@client).to receive(:handle_expired_api_key)
       get
@@ -109,7 +109,7 @@ def post object = "foo", path = "/bar", params = {}
 
     it "should notice errors and raise them as Pardot::ResponseError" do
       fake_post "/api/foo/version/4/bar?format=simple",
-                %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
+                %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Login failed</err>\n</rsp>\n)
 
       expect(lambda { post }).to raise_error(Pardot::ResponseError)
     end
@@ -122,7 +122,7 @@ def post object = "foo", path = "/bar", params = {}
 
     it "should call handle_expired_api_key when the api key expires" do
       fake_post "/api/foo/version/4/bar?format=simple",
-                %(?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
+                %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="fail" version="1.0">\n   <err code="15">Invalid API key or user key</err>\n</rsp>\n)
 
       expect(@client).to receive(:handle_expired_api_key)
       post

spec/pardot/objects/custom_fields_spec.rb

@@ -1,58 +1,54 @@
 require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
 
 describe Pardot::Objects::CustomFields do
-  
-  before do
-    @client = create_client
-  end
-  
-  describe "query" do
-    
-    def sample_results
-      %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="ok" version="1.0">
-        <result>
-          <total_results>1</total_results>
-            <customField>
-              <created_at>2019-11-26 13:40:37</created_at>
-              <crm_id null="true" />
-              <field_id>CustomObject1574793618883</field_id>
-              <id>8932</id>
-              <is_record_multiple_responses>false</is_record_multiple_responses>
-              <is_use_values>false</is_use_values>
-              <name>Ω≈ç√∫˜µ≤≥÷</name>
-              <type>Text</type>
-              <type_id>1</type_id>
-              <updated_at>2019-11-26 13:40:37</updated_at>
-          </customField>
-        </result>
-      </rsp>)
-    end
+  create_auth_managers.each do |auth_manager|
+    context auth_manager.test_name_suffix do
+      let(:client) { auth_manager.create_client }
 
-    before do
-      @client = create_client
+      describe "query" do
+        
+        def sample_results
+          %(<?xml version="1.0" encoding="UTF-8"?>\n<rsp stat="ok" version="1.0">
+            <result>
+              <total_results>1</total_results>
+                <customField>
+                  <created_at>2019-11-26 13:40:37</created_at>
+                  <crm_id null="true" />
+                  <field_id>CustomObject1574793618883</field_id>
+                  <id>8932</id>
+                  <is_record_multiple_responses>false</is_record_multiple_responses>
+                  <is_use_values>false</is_use_values>
+                  <name>Ω≈ç√∫˜µ≤≥÷</name>
+                  <type>Text</type>
+                  <type_id>1</type_id>
+                  <updated_at>2019-11-26 13:40:37</updated_at>
+              </customField>
+            </result>
+          </rsp>)
+        end
+        
+        it "should take in some arguments" do
+          fake_get "/api/customField/version/3/do/query?id_greater_than=200&format=simple", sample_results
+          
+          expect(client.custom_fields.query(:id_greater_than => 200)).to eq({"total_results" => 1, 
+            "customField"=>
+              {
+                "id"=>"8932",
+                "name"=>"Ω≈ç√∫˜µ≤≥÷",
+                "field_id"=>"CustomObject1574793618883",
+                "type"=>"Text",
+                "type_id"=>"1",
+                "crm_id"=>{"null"=>"true"},
+                "is_record_multiple_responses"=>"false",
+                "is_use_values"=>"false",
+                "created_at"=>"2019-11-26 13:40:37",
+                "updated_at"=>"2019-11-26 13:40:37"
+              }
+            })
+            assert_authorization_header auth_manager
+        end
+        
+      end
     end
-    
-    it "should take in some arguments" do
-      fake_get "/api/customField/version/3/do/query?id_greater_than=200&format=simple", sample_results
-      
-      expect(@client.custom_fields.query(:id_greater_than => 200)).to eq({"total_results" => 1, 
-        "customField"=>
-          {
-            "id"=>"8932",
-            "name"=>"Ω≈ç√∫˜µ≤≥÷",
-            "field_id"=>"CustomObject1574793618883",
-            "type"=>"Text",
-            "type_id"=>"1",
-            "crm_id"=>{"null"=>"true"},
-            "is_record_multiple_responses"=>"false",
-            "is_use_values"=>"false",
-            "created_at"=>"2019-11-26 13:40:37",
-            "updated_at"=>"2019-11-26 13:40:37"
-          }
-        })
-      assert_authorization_header
-    end
-    
   end
-  
 end