In this Topic Hide
The Import users option allows for one-time import of multiple users with configured roles and specific role rights. The import option is available to users with the following two rights:
The import file is in XML format. There is a validation (XSD) schema for the import XML that can be downloaded from the import blade to verify the validity of the XML before it is "rejected" as invalid by ATS Security.
The import data contains three main sections:
The Users section is mandatory in each import. The other two sections are optional which means that when importing users it is not necessary to provide roles and user-role assignments, so only user records will be created.
Conditions that must be satisfied for successful user import:
The uniqueness criteria from above is applied in two dimensions:
The values for Username, E-mail address and Role name are compared in "normalized" i.e. uppercase mode. This means that role names "Admin" and "admin" will be treated as the same role, so if these two values are provided as Name for "different" roles in the XML these items will be reported as duplicates.
The XSD validation is not able to do case-insensitive uniquiness check, so be aware that Admin and admin values for role name pass the uniqueness role name check in the XSD validation. But, later while processing this case will be reported as an error.
The presence of the User and Role in a UserRole combination means that the import of users feature can not be used for "bulk role assignment" i.e. only to assign roles for existing users.
For double values of Username and Name of a role, the following logic is applied:
The following values (1,2,3,4,5, 6,7 and 8) are accepted for the UserSource element of a User in the XML:
Windows = 1
Google = 2
Facebook = 3
OpenIdConnect = 4
Saml = 5
Local = 6
AzureAd = 7
GitHub = 8
The ImprotType determines the handling of already existing passwords enabling the imported users to continue using their "old" passwords from the originating system until they explicitly change or reset their password in ATS Security.
The following import types are accepted in the XML - for the ImportType element of a User:
Other = 1
Inspect = 2
CM4D = 3
Users imported with import type = 1 will be forced to change/set their password upon first login.
After successful upload of the XML document for import of users (valid according to the XSD validation schema) the XML is being processed. During the processing errors and warnings are recorded and at the end of the processing reported to the user with as much as possible details. Errors block the import process. No import can be done when even only one error is reported. Warnings contain records of the XML with some specific issues that can be ignored. The user doing the import can decide to "ignore warnings and continue with the import" or cancel the import and make corrections in the XML and then upload the corrected file.
While importing users the following types errors and warnings might appear:
The following cases or groups of errors can appear while import:
1. Username is double (case insensitive) in the XML.
Examples:
2. Role is double (case insensitive) in XML.
Examples:
Admin
admin
admiN
3. E-mail address is double for local (UserSource=6) users (case insensitive) in the XML
Examples:
4. E-mail for local user in the XML already exists in the database for another local user.
Examples:
[email protected] - [email protected]
5. Trying to assign a role to a user that is not present in the import data
Examples:
Admin - [email protected]
6. Trying to assign a role that is not present in the import data to a user
Examples:
Admin1 - [email protected]
Admin1 - [email protected]
In case both the user and the role from the UserRole assignment do not exist in the XML, first an error will be reported on the user. In case the user is fixed but the role remains unmodified upon next import of the same XML the case will generate error of type 6 from above.
The following cases or groups of warnings can appear while import:
1. Username already exists in the DB
Example:
username = [email protected]
2. Provided import type 2 (Inspect) or 3 (CM4D) and missing hash and/or salt value for a user
Example:
username = [email protected]
3. Custom user field provided for non-existing application
Example:
[email protected] - 15BA7B97-FCE1-4160-2523-08D50A33254E
4. Trying to assign right to role from non-existing application
Example:
Admin - 15BA7B97-FCE1-4160-2523-08D50A33254E
5. Trying to assign non-existing rights to role
Example:
Admin - RunRports
Admin - RunRports\86c225a3-468f-424f-8a9f-2cbcb2ea6111
To import users in ATS Security:
1. Load the Users - All users grid.
2. Click on the Import button.
3. The Import Users blade is loaded on the right with a file upload field.
4. Select the previously prepared (and optionally XSD validated) XML file for import.
5. After a successful XSD validation the processing of the XML file starts and an appropriate waiting message is displayed.
6. After the processing is completed the processing summary is displayed.
6a. In case of errors the imports can not be made so the complete process needs to be started from the beginning by importing new file.
6b. In case of warnings cancel the import and upload an improved import file OR ignore the rows with warnings and continue with the import but without those records.
6c. In case of no errors and no warnings a success summary is displayed with continue.
7. Click Submit button for a successfully processed XML with no errors and warnings (6c) OR ignore the warnings (check-box) and also click on the Submit button for an XML file with warnings only (6b).
8. The import takes place and in case of success the what has been imported summary is displayed to the user. The Import Users blade is closed and the Users - All users grid is refreshed to show the newly imported users.