Introduction
The AuthAnvil Password Server provides a way to migrate data into the system through a master import file. This is a well structured XML format that links Roles, Scopes, Permissions, Users, Vaults and Passwords in a logical manner for mass creation of your password database.
A Master Import file consists of four major sections:
- A list of Scopes
- A list of Roles
- A list of Users
- A list of Vaults with permissions and the actual passwords
Within each section are various key elements and attributes to define and link the content together.
The Header
All import files follow the following format for the primary header:
<?xml version="1.0"?>
<importRecord xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scorpionsoft.com/AAPS/AAPSImport.xsd">
Without this, the Master Import tool available in the AuthAnvil Password Server can not attempt to parse our all the elements for import.
Scopes
This element holds an array of <scope> elements that contain the following attributes:
| Attribute | Description |
| name | The name of the Scope (required) |
| desc | A general description of the Scope (required) |
| tempID | A temporary ID that is used to do internal linking of content between elements. (required) |
| realID | The final ID you want actually linked in the Password Server [see tip below] (required) |
<scopes>
<scope name="Demo Scope" desc="A simple demo scope" tempID="1" realID="3" />
</scopes>
A tip about tempID vs reaID
By default there is always two scopes within the Password Server that cannot be override. That is the "Default Scope" with the realID of 1 and the "Personal Scope", which has the realID of 2. So your realID has to start at 3 or higher, depending on if you are building an entirely new Password Server database or are updating an existing up. By default, you should always set realID to 0, since the system will assign the realID as it's created. If you define an ID, it will try to assign it, and it MUST already exist in the system.
If you are unsure, you should just set realID to 0.
The tempID is an internal identifier within the import file that allows linking between elements. When imported this placeholder will be used to keep everything in sync until the final realID can be applied.
If you are unsure you can ignore this, and always set items that refer to a Scope to the "Default Scope" of 1.
Roles
This element holds an array of <role> elements that contain the following attributes:
| Attribute | Description |
| name | A unique name of the Role (required) |
| desc | A general description of the Role (required) |
| tempID | A temporary ID that is used to do internal linking of content between elements. (required) |
| realID | The final ID you want actually linked in the Password Server [see tip below] (required) |
Within this element can optionally contain an element representing the scope or scopes that it belongs to.
<roles>
<role name="Default Role" desc="General role for all users" tempID="1" realID="1" >
<scope id="1" />
</role>
<role name="Level 1 Tech" desc="General technicians" tempID="2" realID="2" >
<scope id="1" />
<scope id="2" />
</role>
</roles>
Users
This element holds an array of <user> elements that contain the following attributes:
| Attribute | Description |
| name | The display name for the user (required) |
| The email address / UPN used to log into the Password Server (required) | |
| admin | Permission determining if this user is an administrator. Acceptable values are "true" or "false". (required) |
| own | Permission determining if this user is allowed to own Vaults. Acceptable values are "true" or "false". (required) |
| create | Permission determining if this user is allowed to create Vaults. Acceptable values are "true" or "false". (required) |
| private | Permission determining if this user is allowed to own Private vaults. Acceptable values are "true" or "false". (required) |
| twofa | Permission determining if this user requires multi-factor authentication. Acceptable values are "true" or "false". (required) |
| password | If twofa is set to "false", then a password attribute is required with a cleartext password to start with. (optional) |
| SASUrl | The full path to an AuthAnvil Two Factor Auth SAS URL. If twofa is set to "false", this should be blank. (optional) |
| siteID | The Site ID of the AuthAnvil Two Factor Auth server. If twofa is set to "false", this should be 0. (required) |
| tempID | A temporary ID that is used to do internal linking of content between elements. (required) |
| realID | The final ID you want actually linked in the Password Server [see tip below] (required) |
By default the original administrator who installed the AuthAnvil Password Server will already have an account. So the realID should start at 2.
<users>
<user name="Admin" email="admin@example.com" admin="true" own="true" create="true" private="true" twofa="false" SASUrl="" siteID="0" tempID="1" realID="2">
<roles>
<role id="1" />
<role id="2" />
</roles>
</user>
<user name="Alice" email="alice@example.com" admin="false" own="true" create="true" private="true" twofa="true" SASUrl="https://auth.example.com/AuthAnvil/SAS.asmx" siteID="1" tempID="2" realID="3">
<roles>
<role id="1" />
</roles>
</user>
</users>
Vaults
This element holds an array of <vault> elements that contain the following attributes:
| Attribute | Description |
| scope | The ID of the Scope this Vault belongs to. You should be setting this to the tempID from the associated Scopes. (required) |
| name | The display name for the Vault (required) |
| desc | A general description of the Vault (required) |
| tempID | A temporary ID that is used to do internal linking of content between elements. (required) |
| realID | The final ID you want actually linked in the Password Server [see tip below] (required) |
| expire | The length of time before a password expires for this Vault. (required) |
| min | The minimum length of a password for this Vault. (required) |
| max | The minimum length of a password for this Vault. (required) |
| lower | Are lower case characters required for passwords in this Vault? Acceptable values are "true" or "false". (optional) |
| num | Are numbers required for passwords in this Vault? Acceptable values are "true" and "false". (optional) |
| special | Are special characters required for passwords in this Vault? Acceptable values are "true" and "false". (optional) |
| limit | The number of unique passwords enforced and stored in the history |
| key | The number of days before the Vault's encryption keys are "re-keyed". |
| rekey | Are you going to force a rekey when the time in days of "key" expires? (optional) |
Within each <vault> element is a set of elements representing the permissions for Users, Roles... as well as the actual list of passwords that are being imported.
Users
When assigning permission on an individual user basis, the following attributes are used:
| Attribute | Description |
| id | The ID of the User we are applying permission to. You should be setting this to the tempID from the associated User. (required) |
| own | Permission determining if this user owns this Vault. Acceptable values are "true" or "false". (optional) |
| create | Permission determining if this user can create passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| mod | Permission determining if this user can modify passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| audit | Permission determining if this user can run Audit reports for passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| req | Permission determining if this user requires approval before revealing passwords in this Vault. Acceptable values are "true" or "false". [assumes mod if approved] (optional) |
| launch | Permission determining if this user can launch RDP connectors and/or launch SSO logins for the passwords in this Vault. Acceptable values are "true" or "false". (optional) |
NOTE: If a permission is NOT defined, by default it is assumed the User does NOT have that permission.
Roles
When assigning permission on roles, the following attributes are used:
| Attribute | Description |
| id | The ID of the User we are applying permission to. You should be setting this to the tempID from the associated User. (required) |
| own | Permission determining if this user owns this Vault. Acceptable values are "true" or "false". (optional) |
| create | Permission determining if this user can create passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| mod | Permission determining if this user can modify passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| audit | Permission determining if this user can run Audit reports for passwords in this Vault. Acceptable values are "true" or "false". (optional) |
| req | Permission determining if this user requires approval before revealing passwords in this Vault. Acceptable values are "true" or "false". [assumes mod if approved] (optional) |
| launch | Permission determining if this user can launch RDP connectors and/or launch SSO logins for the passwords in this Vault. Acceptable values are "true" or "false". (optional) |
NOTE: If a permission is NOT defined, by default it is assumed the Role does NOT have that permission.
Passwords
This element holds an array of <password> elements that contain the actual password data in the following attributes:
| Attribute | Description |
| name | The unique name for the password. (required) |
| desc | A general description for the password. (required) |
| type | A general identifier of the type of password [see table below] (required) |
| username | The username for the credential. (required) |
| domain | The domain for the credential, if present. (required) |
| machine | The machine name, URL or IP associated with this password (optional) |
| expiration | The number of days before this password expires. A value of 0 means it never expires. (required) |
| passValue | The actual cleartext password. (required) |
| ignorePolicy | Ignore the password policy set by the Vault. Acceptable values are "true" and "false" (optional) |
| expireAfterReveal | Mark the password for expiration after X minutes. Default is 0. (optional) |
| note | Additional notes associated with this password record (optional). note=”” on the password element |
Password Type Identifiers
| ID | Type |
| 0 | General Password |
| 1 | Standalone Windows Password |
| 2 | Active Directory Windows Password |
| 3 | Remote Windows Password |
| 4 | AuthAnvil Override Password |
| 5 | Linux Password |
| 16 | Web Password |
| 17 | SSH Password |
| 18 | Network Device Password |
| 21 | SNMP Password |
<vaults>
<vault scope="1" name="Sample Vault" desc="A sample Vault" tempID="1" realID="1" expire="42" min="8" max="40" lower="true" limit="6" key="24">
<users>
<user id="1" own="true" create="true" mod="true" audit="true" req="false" launch="true" />
</users>
<roles>
<role id="1" own="false" create="true" mod="true" audit="true" req="false" launch="true" />
<role id="2" req="true" />
</roles>
<passwords>
<password name="Domain Admin" desc="Main admin account" type="2" username="Administrator" domain="CONTOSO" machine="DC01" expiration="42" passValue="Y3r crazy 2 show a pwd in a sample XML" />
</passwords>
</vault>
</vaults>
Example Master Import file
<?xml version="1.0"?>
<importRecord xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scorpionsoft.com/AAPS/AAPSImport.xsd">
<scopes>
<scope name="Demo Scope" desc="A simple demo scope" tempID="1" realID="3" />
<scope name="Default Scope" desc="Default Scope" tempID="2" realID="1" />
</scopes>
<roles>
<role name="Default Role" desc="General role for all users" tempID="1" realID="1" >
<scope id="1" />
</role>
<role name="Level 1 Tech" desc="General technicians" tempID="2" realID="2" >
<scope id="1" />
<scope id="2" />
</role>
</roles>
<users>
<user name="Admin" email="admin@example.com" admin="true" own="true" create="true" private="true" twofa="false" siteID="0" tempID="1" realID="2">
<roles>
<role id="1" />
<role id="2" />
</roles>
</user>
<user name="Alice" email="alice@example.com" admin="false" own="true" create="true" private="true" twofa="true" siteID="0" tempID="2" realID="3">
<roles>
<role id="1" />
</roles>
</user>
</users>
<vaults>
<vault scope="1" name="Sample Vault" desc="A sample Vault" tempID="1" realID="1" expire="42" min="8" max="40" lower="true" limit="6" key="24">
<users>
<user id="1" own="true" create="true" mod="true" audit="true" req="false" launch="true" />
</users>
<roles>
<role id="1" own="false" create="true" mod="true" audit="true" req="false" launch="true" />
<role id="2" req="true" />
</roles>
<passwords>
<password name="Domain Admin" desc="Main admin account" type="2" username="Administrator" domain="CONTOSO" machine="DC01" expiration="42" passValue="Y3r crazy 2 show a pwd in a sample XML" />
</passwords>
</vault>
</vaults>
</importRecord>
Note: If you need to use special characters in your Scope or Password names please review this Article.
Note: If you would like to create an XML to import only Scopes, Vaults and Passwords with Existing Users and Roles. See Sample_2.xml
The format in Sample_2 will successfully create Scopes, Vaults and Password and associate to existing Users and Roles.
Questions?
If you have any questions or need some help, we would be happy to assist. Open a case at help.scorpionsoft.com or send an email to support@scorpionsoft.com