Backing up and restoring Zato Single Sign-On data
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
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:
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 the backup 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;
DROP TABLE IF EXISTS zato_sso_password_reset;
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 - open the file and find a section called [secret_keys].
The section will have either one key called key1 or two keys, called key1 and sso_key1, depending on when your environment was created - older ones will only have key1 but newer ones have sso_key1 too.
If sso_key1 exists, Zato will use it to encrypt SSO data in the database, preferring it over key1. But if there is only key1 then this is what Zato uses.
Depending on which is available, make a copy of it. In a later step, it will be used as sso_key1 in a new environment. I.e. its new name will be always sso_key1, no matter if in the source environment it was key1 or sso_key1.
Or:
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:
Exit code 0 should be returned on output, indicating a successful operation.
Using sso_key1 in the new server
The secret key copied from the original server (sso_key1 if it existed, key1 otherwise) can be used in the new server in several ways:
- It can be added to the new server's secrets.conf:
- It can be provided as a command line argument to "zato start":
- It can be exported to an environment variable and then used from command line (a variation of the second option):
If you use environment variables, ensure their names do not start with ZATO, case insensitively, they are reserved for system use.
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.