Follow

Detailed description of the Master Import XML file format

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)
email 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

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk