Getting started

To get started with hansken.py, first make sure you have a working version of Python. Try python3 --version or python --version in a terminal or console window. Python 3.5 or higher is required for use with hansken.py

Most installations of Python come with a tool called pip, the Python package manager. As hansken.py is a Python package, make sure you have pip3 or pip available as well. Pip can then be used to install hansken.py. Assuming you have a local file named something hansken-2019.6.1-py3-none-any.whl (see installation), install hansken.py with the following command:

$ pip3 install hansken-2019.6.1-py3-none-any.whl
... (lots of output from pip)

Make sure your new installation works by querying it for its version:

$ hansken --version
2019.06.01

Should the command hansken not be available after installation, it might be that it has not been added to your system’s ‘path’. hansken.py can also be invoked through the Python binary as such:

$ python3 -m hansken --version
2019.06.01

Either of these commands should print out a version number matching the version number in the file name (the astute reader will have noticed this is a date).

When all of this works, your installation is good to go. There is however an additional step called the ‘quickstart’, which can save a lot of time in the future. The quickstart can be invoked as a sub-command of the hansken command:

$ hansken quickstart

This command will prompt you to provide and choose between some configuration values. After collecting a bunch of stuff, it will print a set of lines that can be saved to a file and used as configuration arguments later on. See command line for more information on hansken quickstart.

… And then

Use something like a virtualenv to avoid installing hansken.py system-wide (should you lack super user / administrator rights or prefer to work in a local environment).

Argument files (either generated by hansken quickstart or user-created can be made and saved for any environment. If you find yourself switching between multiple environments (like production and development or different production environments, save argument files for these environments to recognizable files. Note that these files can also be shared between people, as long as those people keep an eye on configuration values for things like log files, which can contain paths that might not work on another machine.

With or without a virtual environment, hansken.py’s power lies in you creating your own scripts. Typically, the most convenient way to get started with this is by downloading a script from the Hansken Expert User Interface (look for the button with the Python logo). A script downloaded from there will come with a command line arguments to control configuration and utilize hansken.tool.run to take care of the nitty gritty details of connecting and authenticating to the Hansken REST API. Alternatively, a script can always be created from scratch, using hansken.tool.run or one of the connection setup functions get started. Using hansken.tool.run is typically the easiest way to get started (optionally with additional command line arguments using hansken.tool.create_argument_parser). Use the connection setup functions when relinquishing control to hansken.tool.run is inconvenient or manual control is preferred for any other reason.

Terminology

Throughout both the documentation and source code for hansken.py, you might encounter terms that do not immediately ring a bell. See the list below for an explanation of a number of terms:

Endpoint

Location where a service can be reached (Hansken REST service, OpenAM identity service, …)

IDP

Identity provider, a service tasked with authentication.

Key

Byte sequence used in some way or another to access data or metadata. For hansken.py, keys will mostly be fetched automatically from the keystore.

Keystore

A Hansken service used to store keys.

SSO

Single sign-on, a term used for an authentication method that requires you to provide login credentials just once. For hansken.py, this involves Kerberos.

Trace

One artifact extracted from a piece of evidence

Note

Missing a term in this list? Let us know!