This article presents a procedure for backing up all of Zato Single Sign-On (SSO) data and restoring it later on.

A single Zato server with SQLite is used for simplicity reasons but the same principles hold regardless of the size of one’s environment or the SQL database used.

Overview

Zato Single-Sign On overview

There are two data sources that SSO uses:

  • Run-time information, such as users, groups, and all the other objects , are stored in an SQL database in tables prefixed with **zato_sso_**, e.g. zato_sso_user or zato_sso_group.

  • Encryption keys are kept in a file called secrets.conf - the same file is shared by all servers in a cluster

Thus, to make a backup:

  • Connect to an existing server via SSH

  • Dump the SQL contents of SSO tables and related objects such as indexes

  • Make a copy of secrets.conf

  • Save everything in a safe place

Conversely, to restore a backup:

  • Load the backup from the safe place

  • Connect to a new Zato server via SSH

  • Move the contents of the SQL dump to the database

  • Replace the server’s secrets.conf with the one copied over earlier during backup

Backing up SQL data

Assuming that a Zato server is in a directory called /home/zato/sso1/server, here is how to back up an SQLite database:

$ cd /home/zato/sso1/server
$ sqlite3 zato.db ".dump zato_sso_%" > zato-sso-backup.sql

This will create a file called zato-sso-backup.sql the contents of which is the schema and rows of all the SSO objects.

To make it easier to restore it later, open the file and add the following commands right after “BEGIN TRANSACTION;”

DROP TABLE IF EXISTS zato_sso_group;
DROP TABLE IF EXISTS zato_sso_user;
DROP TABLE IF EXISTS zato_sso_user_group;
DROP TABLE IF EXISTS zato_sso_session;
DROP TABLE IF EXISTS zato_sso_attr;
DROP TABLE IF EXISTS zato_sso_linked_auth;

The idea with the DROP statements is that when you are restoring SSO from a backup, these tables, albeit empty, will already exist, so we can just drop them to silence out any SQLite warnings.

Backing up secrets.conf

Again, if the server is in /home/zato/sso1/server, the full path to secrets.conf is /home/zato/sso1/server/config/repo/secrets.conf - simply copy the whole file to a location of choice.

Just to confirm it, the contents should be akin to this:

[secret_keys]
key1=P8ViJZs8hM...

[zato]
well_known_data=gAAAAABe0LcDT...
server_conf.kvdb.password=gAAAAA...
server_conf.main.token=gAAAAABe0LcDPy...
server_conf.misc.jwt_secret=gAAAAABe0Lc...
server_conf.odb.password=gAAAAABe0LcD2MqLa...

Creating a new server

We work under assumption that a new server will be created in a directory named /home/zato/sso2/server.

Note that it should be a completely new instance in a new cluster. Do not start the server yet.

Restoring SQL data

Move the zato-sso-backup.sql file to /home/zato/sso2/server and run the commands below:

$ cd /home/zato/sso2/server
$ sqlite3 zato.db < zato-sso-backup.sql
$ echo $?
$ 0

Exit code 0 should be returned on output, indicating a successful operation.

Restoring secrets.conf

The file backed up previously needs to be saved to /home/zato/sso2/server/config/repo/secrets.conf, as below:

$ cd /home/zato/sso2/server/config/repo
$ mv ./secrets.conf ./secrets.conf.bak # Just in case
$ cp /path/to/backup/secrets.conf .

Confirming it all

Now, the server can be started and we can confirm that the SSO data can be accessed by logging it to the system as one of its users, as below - output was reformatted for clarity:

$ zato sso login /home/zato/sso2/server my.user
User logged in {
  'username': 'my.user',
  'user_id': 'zusr6htg...',
  'ust': 'gAAAAABe0M_Pf8cdBa6bimnjfVUt5CF...',
  'creation_time': '2020-05-29T09:03:11.459337',
  'expiration_time': '2020-05-29T10:03:11.459337',
  'has_w_about_to_exp': False
}
$ 

That concludes the process - the SSO data is now restored and the server can be fully used, just like the original one.