Module: Windoo::Connection::Connect

Included in:
Windoo::Connection
Defined in:
lib/windoo/connection/connect.rb

Overview

This module defines constants and methods used for processing the connection parameters, acquiring passwords and tokens, and creating the underlying Faraday connection objects to the Title Editor API. It also defines the disconnection methods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(includer) ⇒ Object 



21
22
23
 
# File 'lib/windoo/connection/connect.rb', line 21

def self.included(includer)
  Windoo.verbose_include(includer, self)
end

Instance Method Details

#connect(url = nil, **params) ⇒ String Also known as: login

Connect to the both the Classic and Jamf Pro APIs

IMPORTANT: http (non-SSL, unencrypted) connections are not allowed.

The first parameter may be a URL (must be https) from which the host & port will be used, and if present, the user and password E.g.

connect 'https://myuser:[email protected]:8443'

which is the same as:

connect host: 'host.domain.edu', port: 8443, user: 'myuser', pw: 'pass'

When using a URL, other parameters below may be specified, however host: and port: parameters will be ignored, since they came from the URL, as will user: and :pw, if they are present in the URL. If the URL doesn’t contain user and pw, they can be provided via the parameters, or left to default values.

### Passwords

The pw: parameter also accepts the symbols :prompt, and :stdin

If :prompt, the user is promted on the commandline to enter the password for the :user.

If pw: is omitted, and running from an interactive terminal, the user is prompted as with :prompt

### Tokens Instead of a user and password, you may specify a valid ‘token:’, which is either:

A Windoo::Connection::Token object, which can be extracted from an active Windoo::Connection via its #token method

or

A valid token string e.g. “eyJhdXR…6EKoo” from any source can also be used.

When using an existing token or token string, the username used to create the token will be read from the server. However, if you don’t also provide the users password using the pw: parameter, then the pw_fallback option will always be false.

### Default values

Any values available via Windoo.config will be used if they are not provided in the parameters. See Windoo::Configuration. If there are no config values then a built-in default is used if available.

Parameters:

  • url (String) (defaults to: nil) —

    The URL to use for the connection. Must be ‘https’. The host, port, and (if provided), user & password will be extracted. Any of those params explicitly provided will be ignored if present in the url

  • params (Hash) —

    the keyed parameters for connection.

Options Hash (**params):

  • :host (String) —

    the hostname of the Title Editor server, required if not defined in Windoo.config

  • :user (String) —

    a JSS user who has API privs, required if not defined in Jamf::CONFIG

  • :pw (String, Symbol) —

    The user’s password, or :prompt If :prompt, the user is promted on the commandline to enter the password

  • :port (Integer) —

    the port number to connect with, defaults to 443

  • :ssl_version (String, Symbol) —

    The SSL version to use. Default is TLSv1_2

  • :verify_cert (Boolean) —

    should SSL certificates be verified. Defaults to true.

  • :open_timeout (Integer) —

    the number of seconds to wait for an initial response, defaults to 60

  • :timeout (Integer) —

    the number of seconds before an API call times out, defaults to 60

  • :keep_alive (Boolean) —

    Should the token for the connection for be automatically refreshed before it expires? Default is true

  • :pw_fallback (Boolean) —

    If keep_alive, should the passwd be cached in memory and used to create a new token, if there are problems with the normal token refresh process?

  • :token (String) —

    A valid token string. If provided, no need to provide user:. pw: must only be provided if pw_fallback is set to true, and must be the correct pw for the user who generated the token string.

Returns:

  • (String) —

    connection description, the output of #to_s

Raises:

  • (ArgumentError) 


120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/windoo/connection/connect.rb', line 120

def connect(url = nil, **params)
  raise ArgumentError, 'No url or connection parameters provided' if url.nil? && params.empty?

  # reset all values, flush caches
  disconnect

  # Get host, port, user and pw from a URL, or
  # build a base_url from those provided in the params
  # when finished, params will include
  # base_url, user, host, port, and possibly pw
  parse_url url, params

  # Default to prompting for the pw
  params[:pw] ||= :prompt

  prompt_for_password(params) if params[:pw] == :prompt

  # apply defaults from config, client, and then windoo itself.
  apply_default_params 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

  # Now we can build out base url
  build_base_url params

  # it there's no @token yet, get one from a token string or a password
  create_token params

  # Now set our attribs

  @timeout = params[:timeout]
  @open_timeout = params[:open_timeout]

  @name ||= "#{params[:user]}@#{params[:host]}:#{params[:port]}"

  # the faraday connection object
  @cnx = create_connection

  @connect_time = Time.now
  @connected = true

  to_s
end

#disconnect ⇒ void Also known as: logout

This method returns an undefined value.

With a REST connection, there isn’t any real “connection” to disconnect from So to disconnect, we just unset all our credentials.



183
184
185
186
187
188
189
190
 
# File 'lib/windoo/connection/connect.rb', line 183

def disconnect
  @token&.disconnect
  @token = nil
  @cnx = nil

  @connected = false
  :disconnected
end

#validate_connected ⇒ Object

raise exception if not connected, and make sure we’re using the current token

Raises:



169
170
171
172
173
174
175
 
# File 'lib/windoo/connection/connect.rb', line 169

def validate_connected
  using_dft = 'Windoo.cnx' if self == Windoo.cnx
  return if connected?

  raise Windoo::NotConnectedError,
        "Connection '#{name}' Not Connected. Use #{using_dft}.connect first."
end