ruby-jss 1.2.4a4 → 1.3.3

data/lib/jamf/api/abstract_classes/prestage_skip_setup_items.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/abstract_classes/resource.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/abstract_classes/singleton_resource.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/attribute_classes/ip_address.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/attribute_classes/timestamp.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/connection.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -48,7 +48,7 @@ module Jamf
     RSRC_BASE = 'uapi'.freeze
 
     # The API version must be this or higher
-    MIN_API_VERSION = Gem::Version.new('1.0')
+    MIN_JAMF_VERSION = Gem::Version.new('10.15.0')
 
     HTTPS_SCHEME = 'https'.freeze
 
@@ -111,6 +111,7 @@ module Jamf
       @login_time
       @keep_alive
       @token_refresh
+      @pw_fallback
     ].freeze
 
     # Attributes
@@ -140,6 +141,10 @@ module Jamf
     # @return [String, nil]
     attr_reader :base_url
 
+    # @return [Boolean] if token refresh/keepaliave fails, try to get a new one
+    # with the passwd used with .connect. Defaults to true
+    attr_reader :pw_fallback
+
     # @return [Boolean]
     attr_reader :connected
     alias connected? connected
@@ -227,14 +232,13 @@ module Jamf
     # ### Tokens
     # Instead of a user and password, you may specify a valid 'token:', either:
     #
-    # A Jamf::Connection::Token object, which  can be extracted from an active
+    # A Jamf::Connection::Token object, which can be extracted from an active
     # Jamf::Connection via its #token method
     #
     # or
     #
     # A token string e.g. "eyJhdXR...6EKoo" from any source can also be used.
     #
-    #
     # Any values available via Jamf.config will be used if they are not provided
     # in the parameters.
     #
@@ -251,6 +255,19 @@ module Jamf
     #
     # @param token: [Jamf::Connection::Token, String] An existing, valid token.
     #   When used, there's no need to provide user: or pw:.
+    #   NOTE if using pw_fallback:true (the default) while providing a token
+    #   you will also need to provide the password for the token user in the pw:
+    #   parameter, or be prompted for it. If you don't have the pw for the
+    #   token user, be sure to set pw_fallback to false.
+    #
+    # @param token_refresh: [Integer] Refresh the token this many seconds before
+    #   it expires. Must be >= DFT_TOKEN_REFRESH
+    #
+    # @pararm pw_fallback: [Boolean] Default is true. Use the password provided
+    #   to refresh the token if regular refresh doesn't work (e.g. token is expired).
+    #   NOTE: This causes the password to be kept in memory. If you don't want
+    #   this, explicitly set pw_fallback to false, however long-running processes
+    #   may lose connection if token refresh fails for any reason.
     #
     # @param open_timeout: [Integer] The number of seconds for initial contact
     #   with the host.
@@ -268,7 +285,8 @@ module Jamf
       # This sets all the instance vars to nil, and flushes/creates the caches
       disconnect
 
-      # This sets @token, and adds host, port, user to params from a Token object
+      # If there's a Token object in :token, this sets @token,
+      # and adds host, port, user from that token
       parse_token params
 
       # Get host, port, user and pw from a URL, add to params if needed
@@ -277,6 +295,8 @@ module Jamf
       # apply defaults from config, client, and then this class.
       apply_connection_defaults params
 
+      # Once we're here, all params have been parsed & defaulted into the
+      # params hash, so
       # make sure we have the minimum needed params for a connection
       verify_basic_params params
 
@@ -285,15 +305,20 @@ module Jamf
 
       # if no @token already, get one from from
       # either a token string or a pw
-      @token ||=
+      unless @token
         if params[:token].is_a? String
-          tk = token_from :token_string, params[:token]
+          @token = token_from :token_string, params[:token]
           # get the user from the token
-          @user = tk.user
-          tk
+          @user = @toke.user
+          # if @pw_fallback, the pw must be acquired, since it isn't in
+          # the token
+          @pw = acquire_password(params[:pw]) if @pw_fallback
         else
-          token_from :pw, acquire_password(params[:pw])
+          pw = acquire_password(params[:pw])
+          @token = token_from :pw, pw
+          @pw = pw if @pw_fallback
         end
+      end
 
       # Now get some values from our token
       @base_url = @token.base_url
@@ -303,43 +328,49 @@ module Jamf
       @rest_cnx = create_connection
 
       # make sure versions are good
-      validate_api_version
+      validate_jamf_version
 
       @connected = true
 
       # start keepalive if needed
-      @keep_alive = params[:keep_alive].nil? ? false : params[:keep_alive]
       start_keep_alive if @keep_alive
 
       # return our string output
       to_s
     end # connect
 
+    # reset all values to nil or empty
     def disconnect
-      # reset everything except the timeouts
-      stop_keep_alive
-
       @connected = false
       @name = NOT_CONNECTED
       @login_time = nil
+
+      stop_keep_alive
+
       @host = nil
       @port = nil
       @user = nil
-      @token = nil
+      @timeout = nil
+      @open_timeout = nil
       @base_url = nil
+      @token = nil
       @rest_cnx = nil
       @ssl_options = {}
       @keep_alive = nil
+      @token_refresh = nil
+      @pw_fallback = nil
+      @pw = nil
 
       flushcache
     end
 
-    # Same as disconnect, but invalidates the token
+    # Same as disconnect, but invalidates the token on the server first
     def logout
       @token.destroy
       disconnect
     end
 
+    # Get a resource
     def get(rsrc)
       validate_connected
       resp = @rest_cnx.get rsrc
@@ -423,7 +454,9 @@ module Jamf
 
     # Are we keeping the connection alive?
     def keep_alive?
-      @keep_alive_thread&.alive? || false
+      return false unless @keep_alive_thread
+
+      @keep_alive_thread.alive?
     end
 
     # @return [Jamf::Timestamp, nil]
@@ -461,8 +494,12 @@ module Jamf
       @token_refresh = secs
     end
 
-    def api_version
-      @token.api_version
+    def jamf_version
+      @token.jamf_version
+    end
+
+    def jamf_build
+      @token.jamf_build
     end
 
     # Flush the collection and/or ea cache for the given class,
@@ -503,11 +540,11 @@ module Jamf
     end
 
     # raise exception if API version is too low.
-    def validate_api_version
-      vers = api_version
-      return if Gem::Version.new(vers) >= MIN_API_VERSION
+    def validate_jamf_version
+      vers = jamf_version
+      return if Gem::Version.new(vers) >= MIN_JAMF_VERSION
 
-      raise Jamf::InvalidConnectionError, "API version '#{vers}' too low, must be >= '#{MIN_API_VERSION}'"
+      raise Jamf::InvalidConnectionError, "API version '#{vers}' too low, must be >= '#{MIN_JAMF_VERSION}'"
     end
 
     #####  Parse Params
@@ -537,7 +574,7 @@ module Jamf
       raise "Cannot use token: it expires in less than #{TOKEN_REUSE_MIN_LIFE} seconds" if token.secs_remaining < TOKEN_REUSE_MIN_LIFE
     end
 
-    # Get host, port, user and pw from a URL, unless they are already in the params
+    # Get host, port, user and pw from a URL, overriding any already in the params
     #
     # @return [String, nil] the pw if present
     #
@@ -547,27 +584,29 @@ module Jamf
       url = URI.parse url.to_s
       raise ArgumentError, 'Invalid url, scheme must be https' unless url.scheme == HTTPS_SCHEME
 
-      params[:host] ||= url.host
-      params[:port] ||= url.port
-      params[:user] ||= url.user if url.user
-      params[:pw] ||= url.password if url.password
+      params[:host] = url.host
+      params[:port] = url.port
+      params[:user] = url.user if url.user
+      params[:pw] = url.password if url.password
     end
 
-    # Apply defaults from the Jamf.config,
-    # then from the Jamf::Client,
+    # Apply defaults to the unset params for the #connect method
+    # First apply them from from the Jamf.config,
+    # then from the Jamf::Client (read from the jamf binary config),
     # then from the Jamf module defaults
-    # to the unset params for the #connect method
     #
     # @param params[Hash] The params for #connect
     #
     # @return [Hash] The params with defaults applied
     #
     def apply_connection_defaults(params)
-      # if no port given, either directly or via URL, and the host
-      # is a jamfcloud host, always set the port to 443
-      # This should happen before the config is applied, so
-      # on-prem users can still get to jamfcoud without specifying the port
-      params[:port] = JAMFCLOUD_PORT if params[:port].nil? && params[:host].to_s.end_with?(JAMFCLOUD_DOMAIN)
+      # must have a host, but accept legacy :server as well as :host
+      params[:host] ||= params[:server]
+
+      # if we have no port set by this point, set to cloud port
+      # if host is a cloud host. But leave port nil for other hosts
+      # (will be set via client defaults or module defaults)
+      params[:port] ||= JAMFCLOUD_PORT if params[:host].to_s.end_with?(JAMFCLOUD_DOMAIN)
 
       apply_defaults_from_config(params)
 
@@ -621,11 +660,12 @@ module Jamf
     # @return [Hash] The params with defaults applied
     #
     def apply_module_defaults(params)
-      # if we have no port set by this point, assume on-prem
+      # if we have no port set by this point, assume on-prem.
       params[:port] ||= ON_PREM_SSL_PORT
       params[:timeout] ||= DFT_TIMEOUT
       params[:open_timeout] ||= DFT_OPEN_TIMEOUT
       params[:ssl_version] ||= DFT_SSL_VERSION
+      params[:token_refresh] ||= DFT_TOKEN_REFRESH
       # if we have a TTY, pw defaults to :prompt
       params[:pw] ||= :prompt if STDIN.tty?
     end
@@ -641,36 +681,38 @@ module Jamf
       # and is already parsed
       return if @token
 
-      # must have a host, but accept legacy :server as well as :host
-      params[:host] ||= params[:server]
+      # must have a host
       raise Jamf::MissingDataError, 'No Jamf :host specified, or in configuration.' unless params[:host]
 
       # no need for user or pass if using a token string
       return if params[:token].is_a? String
 
+      # must have user and pw
       raise Jamf::MissingDataError, 'No Jamf :user specified, or in configuration.' unless params[:user]
       raise Jamf::MissingDataError, "No :pw specified for user '#{params[:user]}'" unless params[:pw]
     end
 
+    # Turn the connection parameters into instance vars
     def parse_connect_params(params)
       @host = params[:host]
       @port = params[:port]
-      @port ||= @host.end_with?(JAMFCLOUD_DOMAIN) ? JAMFCLOUD_PORT : ON_PREM_SSL_PORT
       @user = params[:user]
 
-      @token_refresh = params[:token_refresh].to_i || DFT_TOKEN_REFRESH
-      # token refresh must be at least DFT_TOKEN_REFRESH
-      @token_refresh = DFT_TOKEN_REFRESH if @token_refresh < DFT_TOKEN_REFRESH
+      @keep_alive = params[:keep_alive].nil? ? false : params[:keep_alive]
+      @pw_fallback = params[:pw_fallback].nil? ? true : params[:pw_fallback]
+      @token_refresh = params[:token_refresh].to_i
 
-      @timeout = params[:timeout] || DFT_TIMEOUT
-      @open_timeout = params[:open_timeout] || DFT_TIMEOUT
+      @timeout = params[:timeout]
+      @open_timeout = params[:open_timeout]
       @base_url = URI.parse "https://#{@host}:#{@port}/#{RSRC_BASE}"
+
       # ssl opts for faraday
       # TODO: implement all of faraday's options
       @ssl_options = {
         verify: params[:verify_cert],
         version: params[:ssl_version]
       }
+
       @name = "#{@user}@#{@host}:#{@port}" if @name == NOT_CONNECTED
     end
 
@@ -701,16 +743,18 @@ module Jamf
     # @return [String] The password for the connection
     #
     def acquire_password(param_pw)
-      if param_pw == :prompt
-        Jamf.prompt_for_password "Enter the password for Jamf user #{@user}@#{@host}:"
-      elsif param_pw.is_a?(Symbol) && param_pw.to_s.start_with?('stdin')
-        param_pw.to_s =~ /^stdin(\d+)$/
-        line = Regexp.last_match(1)
-        line ||= 1
-        Jamf.stdin line
-      else
-        param_pw
-      end # if
+      pw =
+        if param_pw == :prompt
+          Jamf.prompt_for_password "Enter the password for Jamf user #{@user}@#{@host}:"
+        elsif param_pw.is_a?(Symbol) && param_pw.to_s.start_with?('stdin')
+          param_pw.to_s =~ /^stdin(\d+)$/
+          line = Regexp.last_match(1)
+          line ||= 1
+          Jamf.stdin line
+        else
+          param_pw
+        end # if
+      pw
     end # acquire pw
 
     # create the faraday connection object
@@ -747,11 +791,11 @@ module Jamf
             begin
               next if @token.secs_remaining > @token_refresh
 
-              @token.refresh
+              @token.refresh @pw
               # make sure faraday uses the new token
               @rest_cnx.headers[:authorization] = @token.auth_token
             rescue
-              # TODO: Some kind of error reporting??
+              # TODO: Some kind of error reporting
               next
             end
           end # loop
@@ -764,7 +808,9 @@ module Jamf
     # @return [void]
     #
     def stop_keep_alive
-      @keep_alive_thread&.kill
+      return unless @keep_alive_thread
+
+      @keep_alive_thread.kill if @keep_alive_thread.alive?
       @keep_alive_thread = nil
     end
 
@@ -811,7 +857,7 @@ module Jamf
   end
 
   def self.disconnect
-    @active_connection&.disconnect
+    @active_connection.disconnect if @active_connection
   end
 
 end # module Jamf

data/lib/jamf/api/connection/api_error.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/connection/api_error_styleguide.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/connection/token.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -30,6 +30,8 @@ module Jamf
     # A token used for a JSS connection
     class Token
 
+      JAMF_VERSION_RSRC = 'v1/jamf-pro-version'.freeze
+
       AUTH_RSRC = 'auth'.freeze
 
       NEW_TOKEN_RSRC = "#{AUTH_RSRC}/tokens".freeze
@@ -56,9 +58,22 @@ module Jamf
       # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/uapi
       attr_reader :base_url
 
-      # when was this token created?
+      # @return [Jamf::Timestamp] when was this token created?
       attr_reader :login_time
 
+      # What happened the last time we tried to refresh?
+      #   :expired_refreshed - token was expired, a new token was created with the pw
+      #   :expired_pw_failed - token was expired, pw failed to make a new token
+      #   :expired_no_pw - token was expired, but no pw was given to make a new one
+      #   :refreshed - the token refresh worked with no need for the pw
+      #   :refresh_failed - the token refresh failed, and no pw was given to make a new one
+      #   :refreshed_with_pw - the token refresh failed, pw worked to make a new token
+      #   :refresh_failed_no_pw - the token refresh failed, pw also failed to make a new token
+      #   nil - no refresh has been attempted for this token.
+      #
+      # @return [Symbol, nil] :refreshed, :pw, :expired,:failed, or nil if never refreshed
+      attr_reader :last_refresh_result
+
       def initialize(**params)
         @valid = false
         @user = params[:user]
@@ -90,7 +105,7 @@ module Jamf
           raise Jamf::AuthenticationError, 'Incorrect name or password'
         else
           # TODO: better error reporting here
-          raise 'An error occurred while authenticating'
+          raise Jamf::AuthenticationError, 'An error occurred while authenticating'
         end
       end # init_from_pw
 
@@ -118,8 +133,13 @@ module Jamf
       end
 
       # @return [String]
-      def api_version
-        token_connection(Jamf::Connection::SLASH, token: @auth_token).get.body[:version]
+      def jamf_version
+        raw_jamf_version.split('-').first
+      end
+
+      # @return [String]
+      def jamf_build
+        raw_jamf_version.split('-').last
       end
 
       # @return [Boolean]
@@ -165,18 +185,39 @@ module Jamf
         @account = Jamf::APIAccount.new resp.body
       end
 
-      # Use this token to get a fresh one
-      # TODO: better error reporting
-      def refresh
-        raise 'Token has expired' if expired?
+      # Use this token to get a fresh one. If a pw is provided
+      # try to use it to get a new token if a proper refresh fails.
+      #
+      # @param pw [String] Optional password to use if token refresh fails.
+      #   Must be the correct passwd or the token's user (obviously)
+      #
+      # @return [Jamf::Timestamp] the new expiration time
+      #
+      def refresh(pw = nil)
+        # gotta have a pw if expired
+        if expired?
+          # try the passwd
+          return refresh_with_passwd(pw, :expired_refreshed, :expired_pw_failed) if pw
+
+          # no passwd? no chance!
+          @last_refresh_result = :expired_no_pw
+          raise Jamf::InvalidTokenError, 'Token has expired'
+        end
 
+        # Now try a normal refresh of our non-expired token
         keep_alive_token_resp = token_connection(KEEP_ALIVE_RSRC, token: @auth_token).post
+        if keep_alive_token_resp.success?
+          parse_token_from_response keep_alive_token_resp
+          @last_refresh_result = :refreshed
+          return expires
+        end
 
-        raise 'An error occurred while authenticating' unless keep_alive_token_resp.success?
+        # if we're here, the normal refresh failed, so try the pw
+        return refresh_with_passwd(pw, :refreshed_with_pw, :refresh_failed_no_pw) if pw
 
-        parse_token_from_response keep_alive_token_resp
-        # parse_token_from_response keep_alive_rsrc.post('')
-        expires
+        # if we're here, no pw? no chance!
+        @last_refresh_result = :refresh_failed
+        raise 'An error occurred while refreshing the token' unless pw
       end
       alias keep_alive refresh
 
@@ -190,6 +231,32 @@ module Jamf
       #################################
       private
 
+      # refresh a token using a password, return a result
+      # @param pw[String] the password to use
+      # @return [JamfTimestamp] the new expiration
+      def refresh_with_passwd(pw, success, failure)
+        init_from_pw(pw)
+        @last_refresh_result = success
+        expires
+      rescue => e
+        @last_refresh_result = failure
+        raise e, "#{e}. Status: :#{failure}"
+      end
+
+      # @return [String]
+      def raw_jamf_version
+        # TODO: Remove this once we require Jamf Pro 10.19 and up
+        # the rsrc for getting the version used to be nothing (the
+        # base url itself returnedit) but now its JAMF_VERSION_RSRC
+        resp = token_connection(Jamf::BLANK, token: @auth_token).get # .body # [:version]
+        return resp.body[:version] if resp.success?
+
+        resp = token_connection(JAMF_VERSION_RSRC, token: @auth_token).get
+        return resp.body[:version] if resp.success?
+
+        raise Jamf::InvalidConnectionError, 'Unable to read Jamf version from the API'
+      end
+
       # a generic, one-time Faraday connection for token
       # acquision & manipulation
       #