Tips on exporting and importing security settings
InterSystems Data Platforms products allow you to export and import security settings in two different ways.
This article talks about those options:
- On the command line, using ^SECURITY
- Programmatically, using the Export and Import methods of classes in the Security package
Exporting settings on the command line (^SECURITY)
You can export everything or individual sections of the security settings.
Exporting everything with ^SECURITY
With ^SECURITY, you can export or import all the security settings for an instance very simply. In the Terminal, go to the %SYS namespace and start ^SECURITY:
USER>zn "%SYS" %SYS>do ^SECURITY
In ^SECURITY, choose option 12, System parameter setup.
In the System parameter setup menu, choose option 5, Export All Security settings.
^SECURITY then prompts you as follows:
Export ALL security records? Yes => [Answer yes or y -- this not case-sensitive]
The routine then reminds you that, when importing settings later, all the certificate directories and certificate files must be present before the import.
^SECURITY then prompts for file information:
Export to file name SecurityExport.xml => Parameters? "WNS" =>
Simply press Enter to accept the defaults.
If you have previously exported settings, you will see a message such as:
SecurityExport.xml already exists, do you want to overwrite it? Yes => [Answer yes or y -- this not case-sensitive]
^SECURITY then prompts to confirm that you want to export the settings; again, answer yes or y. As it exports the settings, ^SECURITY provides a brief report of what it is doing.
And that's it.
Exporting a subset of the settings with ^SECURITY
Instead of exporting everything, you can use ^SECURITY export certain elements separately. There are two different ways to export individual elements:
- In their own menus
- As an individual item under the Export All Security settings choice
In their own menus, you can export:
- Users (optionally including their SQL privileges)
- Roles (optionally including their SQL privileges)
- LDAP configurations
- SSL/TLS configurations
- KMIP servers
- Audit log entries
Under the Export All Security settings choice, you can either export everything (by answering Yes when it asks Export ALL security records?) or choose to export information for only certain areas (by answering No). The choices and their areas are:
- Application records (all application types except Doc DB applications)
- DocDB records (Doc DB applications)
- Event records (which audit events are enabled)
- KMIP server records
- LDAP Configuration records
- OpenAM Identity Service records
- Phone Provider records
- Resource records
- Role records (does not include SQL privileges)
- Service records
- SQL Privileges records
- System records (system-level settings only)
- SSL configuration records
- User records (does not include SQL privileges)
- X509 User records
- X509 Credential records
For example, here is how to export users, including their SQL privileges, through the Users menu:
In the Terminal, go to the %SYS namespace and start ^SECURITY:
USER>zn "%SYS" %SYS>do ^SECURITY
Within ^SECURITY, choose option 1, User setup.
Within the User setup menu, choose option 6, Export users.
At the Export which users? * => prompt, you can then choose to export a single named user, a comma-separated list of users, or all users (*, the default).
At the Export users containing these roles? * => prompt, you can also choose which to export a subset of users who have certain roles. (The routine exports any user who holds any specified role.)
At the Export SQL Privileges directly granted to these users? No => prompt, you can choose to include the SQL privileges for all exported users. (This option is also available for roles; when exporting all security settings, SQL privileges are included.)
There are then prompts for the file name, defaults, and confirmation as with exporting all settings.
All the per-area exports are roughly the same. For example, when exporting roles, you can also specify to include SQL privileges.
Exporting settings programmatically (from classes in the Security package)
The Security package in the %SYS namespace has a number of classes that allow you to export and import their settings. These include:
- Security.Applications - All or a comma-separated list of applications, and all or a certain type of application.
- Security.Domains - All or a comma-separated list of domains.
- Security.Events - All or a list of audit events from comma-separated lists of sources, types, and events.
- Security.KMIPServer - All the properties for a KMIP server.
- Security.Resources - All or a comma-separated list of resources, or a subset of resources by their public permissions.
- Security.Roles - All or a comma-separated list of roles, or a subset of roles that have privileges associated with selected resources; optionally, each listed role's SQL privileges.
- Security.SQLAdminPrivilegeSet - All administrative privileges that allow users or roles to control tables (typically granted on the SQL Privileges tab of the page for editing a user or role):
- %CREATE_METHOD, %DROP_METHOD, %CREATE_FUNCTION, %DROP_FUNCTION, %CREATE_PROCEDURE, %DROP_PROCEDURE, %CREATE_QUERY, %DROP_QUERY, %CREATE_TABLE, %ALTER_TABLE, %DROP_TABLE, %CREATE_VIEW, %ALTER_VIEW, %DROP_VIEW, %CREATE_TRIGGER, %DROP_TRIGGER
- %DB_OBJECT_DEFINITION, which grants all 16 of the above privileges.
- %NOCHECK, %NOINDEX, %NOLOCK, %NOTRIGGER privileges for INSERT, UPDATE, and DELETE operations.
- Security.SQLPrivileges - All the SQL permissions granted for non-system tables.
- Security.SSLConfigs - All or a comma-separated list of SSL/TLS configurations.
- Security.Services - All or a comma-separated list of security services.
- Export - An instance's system-level security settings.
- ExportAll - All security settings for an instance.
- Security.Users - All or a comma-separated list of users, or a subset of users that have privileges associated with selected resources; optionally, each listed user's SQL privileges.
These are all documented in the class reference.
The process of importing all security settings is complimentary to exporting them.
IMPORTANT: InterSystems products do not support exporting and importing settings across versions.
Importing settings with ^SECURITY
Within ^SECURITY, if you can export something in its own menus, then you can import it there, too.
You can also choose option 12 for System parameter setup and then option 6 for Import All Security settings.
A couple of important points:
- The only notable point is that, at the prompt where you choose the file that you're importing from, then if you are importing users from a different file, you enter that file and its path, which can be relative or absolute. (And, if you're just importing a subset, the default file has another name, such as UsersExport.xml.)
- Prompts in individual menus (such as for users) may invoke code that offers to import all the security settings -- for every area; it also lets you choose to import settings from all the areas listed in the Export All Security settings option. The settings for the imported areas are added to the existing settings; they don't replace the existing settings.
Importing settings programmatically
All the classes listed above have Import methods that match their Export methods.