3.3. steelscript.common.service¶
This module defines the Service class and associated authentication classes. The Service class is not instantiated directly, but is instead subclassed to implement handlers for particular REST namespaces.
For example, the NetShark is based on Service using the “netshark” namespace, and will provide the necessary methods to interface with the REST resources available within that namespace.
If a device or appliance implements multiple namespaces, each namespace will be exposed by a separate child class. The SteelCentral NetExpress product implements both the “netprofiler” and “netshark” namespaces. These will be exposed via NetShark and NetProfiler classes respectively, both based on the the Service class. A script that interacts with both namespaces must instantiate two separate objects.
3.3.1. Service Objects¶
-
class
steelscript.common.service.Service(service, host=None, port=None, auth=None, verify_ssl=False, versions=None)¶ This class is the main interface to interact with a device via REST and provides the following functionality:
- Connection management
- Resource requests and responses
- Authentication
- “common” resources
A connection is established as soon as the an instance of this object is created. Requests can be made via the Service.conn property.
-
__init__(service, host=None, port=None, auth=None, verify_ssl=False, versions=None)¶ Establish a connection to the named host.
host is the name or IP address of the device to connect to
- port is the TCP port to use for the connection. This may be either
- a single port or a list of ports. If left unset, the port will automatically be determined.
- auth defines the authentication method and credentials to use
- to access the device. See UserAuth and OAuth. If set to None, connection is not authenticated.
- verify_ssl when set to True will only allow verified SSL certificates
- on any connections, False will not verify certs (useful for self-signed certs on many test systems)
- versions is the API versions that the caller can use.
- if unspecified, this will use the latest version supported by both this implementation and service requested. This does not apply to the “common” resource requests.
-
authenticate(auth)¶ Authenticate with device using the defined authentication method. This sets up the appropriate authentication headers to access restricted resources.
auth must be an instance of either UserAuth or OAuth.
-
check_api_versions(api_versions)¶ Check that the server supports the given API versions.
-
logout()¶ End the authenticated session with the device.
-
ping()¶ Ping the service. On failure, this raises an exception
-
reauthenticate()¶ Retry the authentication method
3.3.2. Authentication¶
Most REST resource calls require authentication. Devices will support one or more authentication methods. The following methods may be supported:
Auth.OAUTH- OAuth 2.0 based authentication using an access code. The access code is used to retrieve an access token which is used in subsequent REST calls.Auth.COOKIE- session based authentication via HTTP Cookies. The initial authentication uses username and password. On success, an HTTP Cookie is set and used for subsequent REST calls.Auth.BASIC- simple username/password based HTTP Basic authentication.
When a Service object is created, the user may either pass an authentication
object to the constructor, or later passed to the Service.authenticate()
method.
3.3.2.1. UserAuth Objects¶
-
class
steelscript.common.service.UserAuth(username, password, method=None)¶ This class is used for both Basic and Cookie based authentication which rely on username and password.
-
__init__(username, password, method=None)¶ Define an authentication method using username and password. By default this will be used for both Basic as well as Cookie based authentication methods (whichever is supported by the target). Authentication can be restricted by setting the method to either Auth.BASIC or Auth.COOKIE.
-