duo_api 1.4.0 → 1.5.0

data/lib/duo_api/api_client.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'erb'
+require 'json'
+require 'openssl'
+require 'net/https'
+require 'time'
+require 'uri'
+
+##
+# A Ruby implementation of the Duo API
+#
+class DuoApi
+  attr_accessor :ca_file
+  attr_reader :default_params
+
+  VERSION = Gem.loaded_specs['duo_api'] ? Gem.loaded_specs['duo_api'].version : '0.0.0'
+
+  # Constants for handling rate limit backoff
+  MAX_BACKOFF_WAIT_SECS = 32
+  INITIAL_BACKOFF_WAIT_SECS = 1
+  BACKOFF_FACTOR = 2
+
+  def initialize(ikey, skey, host, proxy = nil, ca_file: nil, default_params: {})
+    @ikey = ikey
+    @skey = skey
+    @host = host
+    @proxy_str = proxy
+    if proxy.nil?
+      @proxy = []
+    else
+      proxy_uri = URI.parse proxy
+      @proxy = [
+        proxy_uri.host,
+        proxy_uri.port,
+        proxy_uri.user,
+        proxy_uri.password
+      ]
+    end
+    @ca_file = ca_file ||
+               File.join(File.dirname(__FILE__), '..', '..', 'ca_certs.pem')
+    @default_params = default_params.transform_keys(&:to_sym)
+  end
+
+  def default_params=(default_params)
+    @default_params = default_params.transform_keys(&:to_sym)
+  end
+
+  # Basic authenticated request returning raw Net::HTTPResponse object
+  def request(method, path, params = {}, additional_headers = nil)
+    # Merge default params with provided params
+    params = @default_params.merge(params.transform_keys(&:to_sym))
+
+    # Determine if params should be in a JSON request body
+    params_go_in_body = %w[POST PUT PATCH].include?(method)
+    if params_go_in_body
+      body = canon_json(params)
+      params = {}
+    else
+      body = ''
+    end
+
+    # Construct the request URI
+    uri = request_uri(path, params)
+
+    # Sign the request
+    current_date, signed = sign(method, uri.host, path, params, body, additional_headers)
+
+    # Create the HTTP request object
+    request = Net::HTTP.const_get(method.capitalize).new(uri.to_s)
+    request.basic_auth(@ikey, signed)
+    request['Date'] = current_date
+    request['User-Agent'] = "duo_api_ruby/#{VERSION}"
+
+    # Set Content-Type and request body for JSON requests
+    if params_go_in_body
+      request['Content-Type'] = 'application/json'
+      request.body = body
+    end
+
+    # Start the HTTP session
+    Net::HTTP.start(
+      uri.host, uri.port, *@proxy,
+      use_ssl: true, ca_file: @ca_file,
+      verify_mode: OpenSSL::SSL::VERIFY_PEER
+    ) do |http|
+      wait_secs = INITIAL_BACKOFF_WAIT_SECS
+      loop do
+        resp = http.request(request)
+
+        # Check if the response is rate-limited and handle backoff
+        return resp if !resp.is_a?(Net::HTTPTooManyRequests) || (wait_secs > MAX_BACKOFF_WAIT_SECS)
+
+        random_offset = rand
+        sleep(wait_secs + random_offset)
+        wait_secs *= BACKOFF_FACTOR
+      end
+    end
+  end
+
+  private
+
+  # Encode a key-value pair for a URL
+  def encode_key_val(key, val)
+    key = ERB::Util.url_encode(key.to_s)
+    value = ERB::Util.url_encode(val.to_s)
+    "#{key}=#{value}"
+  end
+
+  # Build a canonical parameter string
+  def canon_params(params_hash = nil)
+    return '' if params_hash.nil?
+
+    params_hash.transform_keys(&:to_s).sort.map do |k, v|
+      # When value an array, repeat key for each unique value in sorted array
+      if v.is_a?(Array)
+        if v.count.positive?
+          v.sort.uniq.map{ |vn| encode_key_val(k, vn) }.join('&')
+        else
+          encode_key_val(k, '')
+        end
+      else
+        encode_key_val(k, v)
+      end
+    end.join('&')
+  end
+
+  # Generate a canonical JSON body
+  def canon_json(params_hash = nil)
+    return '' if params_hash.nil?
+
+    JSON.generate(params_hash.sort.to_h)
+  end
+
+  # Canonicalize additional headers for signing
+  def canon_x_duo_headers(additional_headers)
+    additional_headers ||= {}
+
+    unless additional_headers.none?{ |k, v| k.nil? || v.nil? }
+      raise(HeaderError, 'Not allowed "nil" as a header name or value')
+    end
+
+    canon_list = []
+    added_headers = []
+    additional_headers.keys.sort.each do |header_name|
+      header_name_lowered = header_name.downcase
+      header_value = additional_headers[header_name]
+      validate_additional_header(header_name_lowered, header_value, added_headers)
+      canon_list.append(header_name_lowered, header_value)
+      added_headers.append(header_name_lowered)
+    end
+
+    canon = canon_list.join("\x00")
+    OpenSSL::Digest::SHA512.hexdigest(canon)
+  end
+
+  # Validate additional headers to ensure they meet requirements
+  def validate_additional_header(header_name, value, added_headers)
+    header_name.downcase!
+    raise(HeaderError, 'Not allowed "Null" character in header name') if header_name.include?("\x00")
+    raise(HeaderError, 'Not allowed "Null" character in header value') if value.include?("\x00")
+    raise(HeaderError, 'Additional headers must start with \'X-Duo-\'') unless header_name.start_with?('x-duo-')
+    raise(HeaderError, "Duplicate header passed, header=#{header_name}") if added_headers.include?(header_name)
+  end
+
+  # Construct the request URI
+  def request_uri(path, params = nil)
+    u = "https://#{@host}#{path}"
+    u += "?#{canon_params(params)}" unless params.nil?
+    URI.parse(u)
+  end
+
+  # Create a canonical string for signing requests
+  def canonicalize(method, host, path, params, body = '', additional_headers = nil, options: {})
+    # options[:date] being passed manually is specifically for tests
+    date = options[:date] || Time.now.rfc2822
+    canon = [
+      date,
+      method.upcase,
+      host.downcase,
+      path,
+      canon_params(params),
+      OpenSSL::Digest::SHA512.hexdigest(body),
+      canon_x_duo_headers(additional_headers)
+    ]
+    [date, canon.join("\n")]
+  end
+
+  # Sign the request with HMAC-SHA512
+  def sign(method, host, path, params, body = '', additional_headers = nil, options: {})
+    # options[:date] being passed manually is specifically for tests
+    date, canon = canonicalize(method, host, path, params, body, additional_headers, options: options)
+    [date, OpenSSL::HMAC.hexdigest('sha512', @skey, canon)]
+  end
+
+  # Custom Error Classes
+  class HeaderError < StandardError; end
+  class RateLimitError < StandardError; end
+  class ResponseCodeError < StandardError; end
+  class ContentTypeError < StandardError; end
+  class PaginationError < StandardError; end
+  class ChildAccountError < StandardError; end
+end

data/lib/duo_api/api_helpers.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative 'api_client'
+
+# Extend DuoApi class with some HTTP method helpers
+class DuoApi
+  # Perform a GET request and parse the response as JSON
+  def get(path, params = {}, additional_headers = nil)
+    resp = request('GET', path, params, additional_headers)
+    raise_http_errors(resp)
+    raise_content_type_errors(resp[:'content-type'], 'application/json')
+
+    parse_json_to_sym_hash(resp.body)
+  end
+
+  # Perform a GET request and retrieve all paginated JSON data
+  def get_all(path, params = {}, additional_headers = nil, data_array_path: nil, metadata_path: nil)
+    # Set default paths for returned data array and metadata if not provided
+    data_array_path = if data_array_path.is_a?(Array) && (data_array_path.count >= 1)
+                        data_array_path.map(&:to_sym)
+                      else
+                        [:response]
+                      end
+    metadata_path = if metadata_path.is_a?(Array) && (metadata_path.count >= 1)
+                      metadata_path.map(&:to_sym)
+                    else
+                      [:metadata]
+                    end
+
+    # Ensure params keys are symbols and ignore offset parameters
+    params.transform_keys!(&:to_sym)
+    %i[offset next_offset].each do |p|
+      if params[p]
+        warn "Ignoring supplied #{p} parameter for get_all method"
+        params.delete(p)
+      end
+    end
+    # Default :limit to 1000 unless specified to minimize requests
+    params[:limit] ||= 1000
+
+    all_data = []
+    prev_results_count = 0
+    next_offset = 0
+    prev_offset = 0
+    resp_body_hash = {}
+    loop do
+      resp = request('GET', path, params, additional_headers)
+      raise_http_errors(resp)
+      raise_content_type_errors(resp[:'content-type'], 'application/json')
+
+      resp_body_hash = parse_json_to_sym_hash(resp.body)
+      resp_data_array = resp_body_hash.dig(*data_array_path)
+      unless resp_data_array.is_a?(Array)
+        raise(PaginationError,
+              "Object at data_array_path #{JSON.generate(data_array_path)} is not an Array")
+      end
+      all_data.concat(resp_data_array)
+
+      resp_metadata = resp_body_hash.dig(*metadata_path)
+      if resp_metadata.is_a?(Hash) && resp_metadata[:next_offset]
+        next_offset = resp_metadata[:next_offset]
+        next_offset = next_offset.to_i if string_int?(next_offset)
+
+        if next_offset.is_a?(Array) || next_offset.is_a?(String)
+          next_offset = next_offset.join(',') if next_offset.is_a?(Array)
+          raise(PaginationError, 'Paginated response offset error') if next_offset == prev_offset
+
+          params[:next_offset] = next_offset
+        else
+          raise(PaginationError, 'Paginated response offset error') if next_offset <= prev_offset
+
+          params[:offset] = next_offset
+        end
+      else
+        next_offset = nil
+        params.delete(:offset)
+        params.delete(:next_offset)
+      end
+
+      break if !next_offset ||
+               (all_data.count <= prev_results_count)
+
+      prev_results_count = all_data.count
+      prev_offset = next_offset
+    end
+
+    # Replace the data array in the last returned resp_body_hash with the all_data array
+    data_array_parent_hash = if data_array_path.count > 1
+                               resp_body_hash.dig(*data_array_path[0..-2])
+                             else
+                               resp_body_hash
+                             end
+    data_array_key = data_array_path.last
+    data_array_parent_hash[data_array_key] = all_data
+
+    resp_body_hash
+  end
+
+  # Perform a GET request to retrieve image data and return raw data
+  def get_image(path, params = {}, additional_headers = nil)
+    resp = request('GET', path, params, additional_headers)
+    raise_http_errors(resp)
+    raise_content_type_errors(resp[:'content-type'], %r{^image/})
+
+    resp.body
+  end
+
+  # Perform a POST request and parse the response as JSON
+  def post(path, params = {}, additional_headers = nil)
+    resp = request('POST', path, params, additional_headers)
+    raise_http_errors(resp)
+    raise_content_type_errors(resp[:'content-type'], 'application/json')
+
+    parse_json_to_sym_hash(resp.body)
+  end
+
+  # Perform a PUT request and parse the response as JSON
+  def put(path, params = {}, additional_headers = nil)
+    resp = request('PUT', path, params, additional_headers)
+    raise_http_errors(resp)
+    raise_content_type_errors(resp[:'content-type'], 'application/json')
+
+    parse_json_to_sym_hash(resp.body)
+  end
+
+  # Perform a DELETE request and parse the response as JSON
+  def delete(path, params = {}, additional_headers = nil)
+    resp = request('DELETE', path, params, additional_headers)
+    raise_http_errors(resp)
+    raise_content_type_errors(resp[:'content-type'], 'application/json')
+
+    parse_json_to_sym_hash(resp.body)
+  end
+
+  private
+
+  # Raise errors for non-successful HTTP responses
+  def raise_http_errors(resp)
+    return if resp.is_a?(Net::HTTPSuccess)
+    raise(RateLimitError, 'Rate limit retry max wait exceeded') if resp.is_a?(Net::HTTPTooManyRequests)
+
+    raise(ResponseCodeError, "HTTP #{resp.code}: #{resp.body}")
+  end
+
+  # Validate the content type of the response against the expected type
+  def raise_content_type_errors(received, allowed)
+    valid = false
+    if allowed.is_a?(Regexp)
+      valid = true if received =~ allowed
+    elsif received == allowed
+      valid = true
+    end
+    raise(ContentTypeError, "Invalid Content-Type #{received}, should match #{allowed.inspect}") unless valid
+  end
+
+  # Check if a value is a Base64 encoded string
+  def base64?(value)
+    value.is_a?(String) and Base64.strict_encode64(Base64.decode64(value)) == value
+  end
+
+  # Check if a string represents an integer
+  def string_int?(value)
+    value.is_a?(String) and value.to_i.to_s == value
+  end
+
+  # Parse JSON string to Hash with symbol keys
+  def parse_json_to_sym_hash(json)
+    JSON.parse(json, symbolize_names: true)
+  end
+
+  # JSON serialize Array
+  def json_serialized_array(value)
+    value.is_a?(Array) ? JSON.generate(value) : value
+  end
+
+  # CSV serialize Array
+  def csv_serialized_array(value)
+    value.is_a?(Array) ? value.join(',') : value
+  end
+
+  # Format boolean as 'true' or 'false'
+  def stringified_boolean(value)
+    %w[true 1].include?(value.to_s.downcase) ? 'true' : 'false'
+  end
+
+  # Format boolean as '1' or '0'
+  def stringified_binary_boolean(value)
+    %w[true 1].include?(value.to_s.downcase) ? '1' : '0'
+  end
+
+  # Format boolean as 'True' or 'False'
+  def stringified_python_boolean(value)
+    %w[true 1].include?(value.to_s.downcase) ? 'True' : 'False'
+  end
+end

data/lib/duo_api/auth.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'api_client'
+require_relative 'api_helpers'
+
+class DuoApi
+  ##
+  # Duo Auth API (https://duo.com/docs/authapi)
+  #
+  class Auth < DuoApi
+    def ping
+      get('/auth/v2/ping')[:response]
+    end
+
+    def check
+      get('/auth/v2/check')[:response]
+    end
+
+    def logo
+      get_image('/auth/v2/logo')
+    end
+
+    def enroll(**optional_params)
+      # optional_params: username, valid_secs
+      post('/auth/v2/enroll', optional_params)[:response]
+    end
+
+    def enroll_status(user_id:, activation_code:)
+      params = { user_id: user_id, activation_code: activation_code }
+      post('/auth/v2/enroll_status', params)[:response]
+    end
+
+    def preauth(**optional_params)
+      # optional_params: user_id, username, client_supports_verified_push, ipaddr, hostname,
+      #                  trusted_device_token
+      #
+      # Note: user_id or username must be provided
+      optional_params.tap do |p|
+        if p[:client_supports_verified_push]
+          p[:client_supports_verified_push] =
+            stringified_binary_boolean(p[:client_supports_verified_push])
+        end
+      end
+      post('/auth/v2/preauth', optional_params)[:response]
+    end
+
+    def auth(factor:, **optional_params)
+      # optional_params: user_id, username, ipaddr, hostname, async
+      #
+      # Note: user_id or username must be provided
+      optional_params.tap do |p|
+        p[:async] = stringified_binary_boolean(p[:async]) if p[:async]
+      end
+      params = optional_params.merge({ factor: factor })
+      post('/auth/v2/auth', params)[:response]
+    end
+
+    def auth_status(txid:)
+      params = { txid: txid }
+      get('/auth/v2/auth_status', params)[:response]
+    end
+  end
+end

data/lib/duo_api/device.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'api_client'
+require_relative 'api_helpers'
+
+class DuoApi
+  ##
+  # Duo Device API (https://duo.com/docs/deviceapi)
+  #
+  class Device < DuoApi
+    attr_accessor :mkey
+
+    def initialize(ikey, skey, host, proxy = nil, mkey:, ca_file: nil, default_params: {})
+      super(ikey, skey, host, proxy, ca_file: ca_file, default_params: default_params)
+
+      @mkey = mkey
+    end
+
+    def create_device_cache(**optional_params)
+      # optional_params: active
+      optional_params.tap do |p|
+        p[:active] = stringified_python_boolean(p[:active]) if p[:active]
+      end
+      post("/device/v1/management_systems/#{@mkey}/device_cache", optional_params)[:response]
+    end
+
+    def add_device_cache_devices(cache_key:, devices:)
+      params = { devices: devices }
+      post("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}/devices", params)[:response]
+    end
+
+    def get_device_cache_devices(cache_key:, **optional_params)
+      # optional_params: device_ids
+      data_array_path = %i[response devices_retrieved]
+      metadata_path = %i[response]
+      get_all("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}/devices", optional_params,
+              data_array_path: data_array_path, metadata_path: metadata_path).dig(*data_array_path)
+    end
+
+    def delete_device_cache_devices(cache_key:, devices:)
+      params = { devices: devices }
+      delete("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}/devices", params)[:response]
+    end
+
+    def activate_device_cache(cache_key:)
+      post("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}/activate")[:response]
+    end
+
+    def delete_device_cache(cache_key:)
+      delete("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}")[:response]
+    end
+
+    def get_device_caches(status:)
+      params = { status: status }
+      get("/device/v1/management_systems/#{@mkey}/device_cache", params)[:response]
+    end
+
+    def get_device_cache(cache_key:)
+      get("/device/v1/management_systems/#{@mkey}/device_cache/#{cache_key}")[:response]
+    end
+  end
+end

data/lib/duo_api.rb

@@ -1,165 +1,9 @@
-require 'erb'
-require 'json'
-require 'openssl'
-require 'net/https'
-require 'time'
-require 'uri'
+# frozen_string_literal: true
 
-##
-# A Ruby implementation of the Duo API
-#
-class DuoApi
-  attr_accessor :ca_file
+require_relative 'duo_api/api_client'
+require_relative 'duo_api/api_helpers'
 
-  if Gem.loaded_specs['duo_api']
-    VERSION = Gem.loaded_specs['duo_api'].version
-  else
-    VERSION = '0.0.0'
-  end
-
-  # Constants for handling rate limit backoff
-  MAX_BACKOFF_WAIT_SECS = 32
-  INITIAL_BACKOFF_WAIT_SECS = 1
-  BACKOFF_FACTOR = 2
-  RATE_LIMITED_RESP_CODE = '429'
-
-  def initialize(ikey, skey, host, proxy = nil, ca_file: nil)
-    @ikey = ikey
-    @skey = skey
-    @host = host
-    if proxy.nil?
-      @proxy = []
-    else
-      proxy_uri = URI.parse proxy
-      @proxy = [
-        proxy_uri.host,
-        proxy_uri.port,
-        proxy_uri.user,
-        proxy_uri.password
-      ]
-    end
-    @ca_file = ca_file ||
-      File.join(File.dirname(__FILE__), '..', 'ca_certs.pem')
-  end
-
-  def request(method, path, params = {}, additional_headers = nil)
-    params_go_in_body = %w[POST PUT PATCH].include?(method)
-    if params_go_in_body
-      body = canon_json(params)
-      params = {}
-    else
-      body = ''
-    end
-
-    uri = request_uri(path, params)
-    current_date, signed = sign(method, uri.host, path, params, body, additional_headers)
-
-    request = Net::HTTP.const_get(method.capitalize).new uri.to_s
-    request.basic_auth(@ikey, signed)
-    request['Date'] = current_date
-    request['User-Agent'] = "duo_api_ruby/#{VERSION}"
-    if params_go_in_body
-      request['Content-Type'] = 'application/json'
-      request.body = body
-    end
-
-    Net::HTTP.start(
-      uri.host, uri.port, *@proxy,
-      use_ssl: true, ca_file: @ca_file,
-      verify_mode: OpenSSL::SSL::VERIFY_PEER
-    ) do |http|
-      wait_secs = INITIAL_BACKOFF_WAIT_SECS
-      while true do
-        resp = http.request(request)
-        if resp.code != RATE_LIMITED_RESP_CODE or wait_secs > MAX_BACKOFF_WAIT_SECS
-          return resp
-        end
-        random_offset = rand()
-        sleep(wait_secs + random_offset)
-        wait_secs *= BACKOFF_FACTOR
-      end
-    end
-  end
-
-  private
-
-  def encode_key_val(k, v)
-    # encode the key and the value for a url
-    key = ERB::Util.url_encode(k.to_s)
-    value = ERB::Util.url_encode(v.to_s)
-    key + '=' + value
-  end
-
-  def canon_params(params_hash = nil)
-    return '' if params_hash.nil?
-    params_hash.sort.map do |k, v|
-      # when it is an array, we want to add that as another param
-      # eg. next_offset = ['1547486297000', '5bea1c1e-612c-4f1d-b310-75fd31385b15']
-      if v.is_a?(Array)
-        encode_key_val(k, v[0]) + '&' + encode_key_val(k, v[1])
-      else
-        encode_key_val(k, v)
-      end
-    end.join('&')
-  end
-
-  def canon_json(params_hash = nil)
-    return '' if params_hash.nil?
-    JSON.generate(Hash[params_hash.sort])
-  end
-
-  def canon_x_duo_headers(additional_headers)
-    additional_headers ||= {}
-
-    if not additional_headers.select{|k,v| k.nil? or v.nil?}.empty?
-      raise 'Not allowed "nil" as a header name or value'
-    end
-
-    canon_list = []
-    added_headers = []
-    additional_headers.keys.sort.each do |header_name|
-      header_name_lowered = header_name.downcase
-      header_value = additional_headers[header_name]
-      validate_additional_header(header_name_lowered, header_value, added_headers)
-      canon_list.append(header_name_lowered, header_value)
-      added_headers.append(header_name_lowered)
-    end
-
-    canon = canon_list.join("\x00")
-    OpenSSL::Digest::SHA512.hexdigest(canon)
-  end
-
-  def validate_additional_header(header_name, value, added_headers)
-    raise 'Not allowed "Null" character in header name' if header_name.include?("\x00")
-    raise 'Not allowed "Null" character in header value' if value.include?("\x00")
-    raise 'Additional headers must start with \'X-Duo-\'' unless header_name.downcase.start_with?('x-duo-')
-    raise "Duplicate header passed, header=#{header_name}" if added_headers.include?(header_name.downcase)
-  end
-
-  def request_uri(path, params = nil)
-    u = 'https://' + @host + path
-    u += '?' + canon_params(params) unless params.nil?
-    URI.parse(u)
-  end
-
-  def canonicalize(method, host, path, params, body = '', additional_headers = nil, options: {})
-    # options[:date] being passed manually is specifically for tests
-    date = options[:date] || Time.now.rfc2822()
-    canon = [
-      date,
-      method.upcase,
-      host.downcase,
-      path,
-      canon_params(params),
-      OpenSSL::Digest::SHA512.hexdigest(body),
-      canon_x_duo_headers(additional_headers)
-    ]
-    [date, canon.join("\n")]
-  end
-
-  def sign(method, host, path, params, body = '', additional_headers = nil, options: {})
-    # options[:date] being passed manually is specifically for tests
-    date, canon = canonicalize(method, host, path, params, body, additional_headers, options: options)
-    [date, OpenSSL::HMAC.hexdigest('sha512', @skey, canon)]
-  end
-end
+require_relative 'duo_api/admin'
+require_relative 'duo_api/accounts'
+require_relative 'duo_api/auth'
+require_relative 'duo_api/device'