ruby-jss 1.2.4a4 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 745114754cc7073bbf494e8eb54f48962c9cafff99da985108c90b5bc7ccc62c
-  data.tar.gz: 6455a7c53abc89c47a03b1bd9538bc0bd3375eab1776ca9c5a15425595ed2ed3
+  metadata.gz: 46f6f03d9aa4d1ddbbabc446004921fd6efa14fb36dcd30ae30dd968bae11357
+  data.tar.gz: 70d78adc1afe510511e5b678d1e852c1e9f518e9afd1e4109938696ddf3cd1f2
 SHA512:
-  metadata.gz: 10cd851d966cc1e966dec194b27a4f282bba25b80177886dc03d44429206c8bc8bb223f141c9da27547f096a439937c6db3ae0d7e6498d2d6570b5bca164f716
-  data.tar.gz: a194cd0e76b6264afc1deef0b2567169a83c7fba9aaad796f050171783df202d1fd3ccf04f5eb11606ea387badce68920822c698aab819bfb46a2fd2549a919f
+  metadata.gz: f631eade4108e9cd51022f417e775347bf1bd4467ab7567c5872d168d34f51908f80d164824571ead6e61ee8c4b8a9b5883db7537da0de66e7f6bc4298d2d4bc
+  data.tar.gz: d9d30e07a70cffa64f11facc41d4720f28a5ab081bf40af9bc3845fb7ed4e809e453ec1b4bad213e671a27191d3a5898c8b3861a6a98c102e80d9223a51df3de

data/CHANGES.md

@@ -4,6 +4,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.2.6] - 2020-04-01
+
+### Fixed
+
+- Classic API (JSS module)
+  - Sitable objects now recognize the string "None" as meaning no site is assigned. Thanks @cybertunnel for this fix!
+  - Scopable::Scope now deals with some bugs in the API regarding Jamf & LDAP users & user groups in targets, limitations, & exclusions. Please see the documentation/comments for the class in the file or the online documentation. Thanks @cybertunnel again!
+  - Criteriable::Criteria can now be empty - containing no criterion objects. When criteriable objects are created (such as Advanced Searches) the default JSS::Criteriable::Criteria object has no criteria.  To remove all criteria, use `criteria.clear`, `criteria = nil`, or `criteria = JSS::Criteriable::Criteria.new` and then save. Once again, thanks to @cybertunnel for finding this.
+
+- Jamf Pro API (Jamf module)
+  - More fixes for various JamfPro API (Jamf module) methods that accept a passed-in Jamf::Connection instance.
+
+
+## \[1.2.5] - 2020-03-30
+
+### Fixed
+
+- Classic API (JSS module)
+  - The Classic API now requires JSS::User objects to be passed back to the API with the `ldap_server` specified by id, name-only won't work.
+
+- Jamf Pro API (Jamf module)
+  - Fixes for various JamfPro API (Jamf module) methods that accept a passed-in Jamf::Connection instance.
+
+## \[1.2.4] - 2020-03-16
+
+### Added
+
+- **'Beta' Jamf Pro API support in ruby-jss!**
+
+The Jamf Pro API, formerly known as the 'Universal' API, aims to be a far more robust, modern, and standardized way to programmatically access a Jamf Pro server.  While its been in development for a while, it is finally starting to settle in to some standards, to the point that its worth releasing some early ruby-jss code to access it.
+
+Because the JP-API is so fundamentally different from the Classic API, it's being implemented as a totally separate ruby module 'Jamf', and many of the underlying standards of ruby-jss's JSS module are being re-thought and modernized, much like the JP-API itself. Classic API access using the JSS module is unchanged, and will continue to get fixes and other updates as needed. However many things in the Jamf module will behave differently from the JSS module, at least in detail if not concept.
+
+For requirements and details of using the Jamf module to access the Jamf Pro API, see [lib/jamf/README-JP-API.md](lib/jamf/README-JP-API.md).
+
+**IMPORTANT:** As with the JP-API, The Jamf module is an early work-in-progress, and things might change drastically at any point. Please mention 'ruby-jss' in MacAdmins Slack channels #jamf-api or #ruby, or email ruby-jss@pixar.com, or open an issue on github if you have questions or want to contribute.
+
+### Changed
+
+- The `last_mdm_contact` class and instance method from the MDM mixin module (as used in Computer and MobileDevice classes) now returns the time of the most recent _completed_ or _failed_ mdm command. This is more accurate than just the completed commands, since a failed command still implies contact between the client and Jamf Pro.
+
+- JSS::MobileDevice instances now have three predicate methods: `tv?` (aliased as `apple_tv?`), `ipad?` and `iphone?`
+
 ## \[1.2.3] - 2019-10-31
 ### Added
 - the ManagementHistory mixin module used by the Computer and MobileDevice classes, now has a `last_mdm_contact` class and instance method, which returns a Time object for the timestamp of the most recent completed MDM command. This is useful for MobileDevices, which don't have anything like the `last_checkin` value for comptuers, indicating real communication between the device and Jamf Pro.

data/README.md

@@ -45,6 +45,8 @@ Hopefully others will find it useful, and add more to it as well.
 
 [Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
 
+NOTE: ruby-jss 1.2.4 will introduce beta-level support for the Jamf Pro API in a ruby module called 'Jamf', See  README-JP-API.md in /lib/jamf, or in the 'Files' section of the YARD docs file for details.
+
 ## SYNOPSIS
 
 Here are some simple examples of using ruby-jss

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

@@ -220,7 +220,7 @@ module Jamf
       val_is_str = value.is_a? String
 
       idents.each do |ident|
-        match = all(cnx: cnx).select do |m|
+        match = all(refresh: refresh, cnx: cnx).select do |m|
           val_is_str ? m[ident].to_s.casecmp?(value) : m[ident] == value
         end.first
         return match[:id] if match
@@ -241,13 +241,20 @@ module Jamf
     end
 
     # Make a new thing to be added to the API
-    def self.create(params, cnx: Jamf.cnx)
-      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless self.creatable?
-
+    def self.create(**params)
       validate_not_abstract
+      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless creatable?
+
+      cnx = params.delete :cnx
+      cnx ||= Jamf.cnx
+
       params.delete :id # no such animal when .creating
 
-      validate_create_params(params, cnx)
+      params.keys.each do |param|
+        raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
+
+        params[param] = validate_attr param, params[param], cnx: cnx
+      end
 
       params[:creating_from_create] = true
       new params, cnx: cnx
@@ -277,16 +284,17 @@ module Jamf
     #
     def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
       validate_not_abstract
+
       id =
         if ident_value == :random
           all_ids.sample
         elsif ident_value
-          valid_id ident_value
+          valid_id ident_value, cnx: cnx
         elsif ident_hash.empty?
           nil
         else
           ident, lookup_value = ident_hash.first
-          valid_id ident => lookup_value
+          valid_id ident => lookup_value, cnx: cnx
         end
 
       raise Jamf::NoSuchItemError, "No matching #{self}" unless id
@@ -362,17 +370,6 @@ module Jamf
     end # create_list_methods
     private_class_method :create_list_methods
 
-    # validate that our .create data is OK
-    #
-    def self.validate_create_params(params, cnx)
-      params.keys.each do |param|
-        raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
-
-        params[param] = validate_attr param, params[param], cnx: cnx
-      end
-    end
-    private_class_method :validate_create_params
-
     # Given an indentier attr. key, and a value,
     # return the id where that ident has that value, or nil
     #

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

@@ -482,7 +482,7 @@ module Jamf
     # have an alias without the 'is' so :isManaged will have
     # getters isManaged? and managed?
     #
-    PREDICATE_RE = /^is([A-Z]\w*)$/.freeze
+    PREDICATE_RE = /^is([A-Z]\w+)$/.freeze
 
     # Public Class Methods
     #####################################
@@ -575,10 +575,11 @@ module Jamf
       else
         define_method(attr_name) { instance_variable_get("@#{attr_name}") }
 
-        # all booleans get a predicate alias
-        alias_method("#{attr_name}?", attr_name) if attr_def[:class] == :boolean
       end
 
+      # all booleans get predicate aliases
+      define_predicates(attr_name) if attr_def[:class] == :boolean
+
       return unless attr_def[:aliases]
 
       # aliases
@@ -586,6 +587,15 @@ module Jamf
     end # create getters
     private_class_method :create_getters
 
+    # create the default aliases for booleans
+    ##############################
+    def self.define_predicates(attr_name)
+      alias_method("#{attr_name}?", attr_name)
+      return unless attr_name.to_s =~ PREDICATE_RE
+
+      alias_method("#{Regexp.last_match(1).downcase}?", attr_name)
+    end
+
     # create setter(s) for an attribute, and any aliases needed
     ##############################
     def self.create_setters(attr_name, attr_def)

data/lib/jamf/api/connection.rb

@@ -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
@@ -461,8 +492,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 +538,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 +572,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 +582,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 +658,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 +679,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 +741,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 +789,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