Import and export users/roles


You can provision a standalone node or a primary node with users and/or roles by importing a user file. Such a file can be created by exporting users from another Decision Insight deployment, or with an external process by following the User file format.

  • The special user account admin cannot be imported or exported. This is by design to prevent malicious users from changing the password of the admin user.
  • Built-in roles cannot be imported or exported.

Import users/roles

Security best practices
You must never upload untrusted files to your installation. Make sure to have every file scanned by an anti-malware software before it can be used in the product.

You can import users and/or roles from the user interface, via shell commands, JMX or via automatic provisioning.

The file must follow the User file format. and must end with the suffix .user.xml.

Import users/roles from the user interface

Step Action
1

On the main menu, click the Configuration    icon. On the left menu, click Roles. 
OR click the Security & Monitoring   icon. On the left menu, click Users  (process is the same on both screens).
2

Click the Import button.
3

Specify the date and time at which to perform the import and click the Import button. 
4 Select the file containing users and/or roles with which you want to provision the node and click OK.
5

If everything has been correctly imported, you are redirected to the previous screen and the new users/roles are displayed.
6

If a problem arises, the popup stays open and displays an error message. Close the popup and correct the issues in your file, then re-import.


Import users/roles via automatic provisioning

To import users/roles via automatic provisioning, simply copy the import file into the  <installation directory>/ var/data/carbon-provisioning/autoimport/incoming  directory of your standalone node or your primary node.

The node regularly scans this directory and automatically imports all files whose name end with .user.xml .

  • If the file can be imported, users are imported and the file is moved to the Done subdirectory (the file name is prefixed with the import date).
  • If an error occurs during the import, the file is moved to the error subdirectory (the file name is prefixed with the import date). An error message is logged. 
    Possible errors are:
    • An entry is missing a mandatory attribute/element.
    • An entry specifies both a password and a hash for a user.
    • Multiple entries have an identical user name.

A temporary file (named after the file but with the .tmp extension) is created at the beginning of an import process and deleted just after the import has completed.

When an import file is processed, all passwords in clear-text in the file are replaced with their hashed form ( using PBKDF2 (Wikipedia) , HMAC, 4096 iterations and a 24 bytes salt).

For more information, see Automatic process .

Import users/roles from the shell

To import users and/or roles from the shell, use the importUsers command.

Command syntax 
importUsers <input file path>

Examples

Import users and/or roles from C:\export.user.xml

g! importUsers "C:\\export.user.xml"
Users/roles from [C:\export.user.xml] successfully imported into the platform
g!

Import users/roles via JMX

Step Action
1

Use a JMX client such as jconsole and connect to the application
2
In the  MBeans tree, open the node  com.systar.carbon.security.impl.UserManagerCommandsMXBean 

3 You can then invoke the operation importUsers. The operation is self-documented in JMX.


Export users/roles

You can export users and/or roles from the graphical user interface, from the shell or via JMX.

Export file must end with the suffix .user.xml

  • Export users/roles from the user interface

Step Action
1

On the main menu, click the Configuration    icon. On the left menu, click Roles. 
OR click the  Security   & Monitoring   icon. On the left menu, click Users.
2

Click the Export button. 

3

Select what you want to export, then click the Export button to generate an export file.
4

Click the Download here hyperlink and save the file onto your computer


Export users/roles from the shell

To export users from the shell, use the exportUsers command.

Command syntax 
exportUsers <output file path> true|false true|false
Help on exportUsers command 
g! ? exportUsers
exportUsers - Export users information into a file
   scope: carbon-user
   parameters:
    String    Full path of the export file (ex: "~/export/my_node.users.xml")
    boolean    true to include users in xml
    boolean    true to include roles in xml
g!

Examples

Export users into C:\export.user.xml

g! exportUsers "C:\\export.user.xml" true true
Users successfully exported into [C:\export.user.xml]
g!

Export users/roles via JMX

Step Action
1

Use a JMX client such as jconsole and connect to the application.
2

In the MBeans tree, open the node com.systar.carbon.security.impl.UserManagerCommandsMXBean

3 You can then invoke the operation exportUsers. The operation is self-documented in JMX.



User file format

The name of XML files must end with .user.xml.  An example of a valid file name is list.user.xml .

The XML file must comply with the following format (sample content: list.user.xml ):

file.user.xml 
<users xmlns="http://www.systar.com/carbon/users">

  <role name="...">
    <description>...</description>
    <platformCapability name="..."/>
  </role>

  <user name="..." password="..." hash="..." firstName="..." lastName="..." email="..." avatar="..." developmentMode="..." accountDisabled="..." authenticationDelegated="...">
    <description>...</description>
    <role name="..."/>
 </user>

</users> 

Role syntax

Each role is defined with the following attributes/elements:

Attribute / Element Description Mandatory / Optional
name

Name of the role.

 mandatory
description A role description (see below) optional
platformCapability.name Name of the capability granted to the role (see below) optional, multiple

User syntax

Each user is defined with the following attributes/elements:

Attribute / Element Description Mandatory / Optional
name

Name of the user.

(warning) The only valid characters are lowercase letters, numbers, dashes, underscores and periods.

 mandatory
password Password of the user, in clear form either password or hash attributes must be filled
or authenticationDelegated must be set to true 
hash

Password of the user, in hashed form ( using PBKDF2 (Wikipedia), HMAC, 4096 iterations and a 24 bytes salt)

 either password or hash attributes must be filled
or authenticationDelegated must be set to true 
firstName First name of the user optional
lastName Last name of the user optional
email Email of the user optional
description A user description (see below) optional
avatar Name of the user avatar optional  (default: none)
developmentMode Whether the development mode is active in the interface optional  (default: false)
accountDisabled Whether the user account is disabled optional  (default: false)
authenticationDelegated Whether the password is stored on another system such as LDAP

mandatory

If set to true, password and hash must not be set.
role.name Name of a role for the user optional, multiple

The user file is using a UTF-8 encoded charset: it means you can use accents in your attributes (except name and password, due to authentication rules).

Description

Description of a user or role is a multiline field, and it must be contained in its own tag.

You can enter text directly within the tag, or use a CDATA section if you need multiline (and other) abilities:

<users xmlns="http://www.systar.com/carbon/users">
    <user name="user1" authenticationDelegated="true"><description>Simple user description</description></user>
    <user name="user2" authenticationDelegated="true">
        <description><![CDATA[User description on its own tag.
You can use multi line description !!
Groovy baby !]]></description>
    </user>
</users>

You can also use the line feed character &#xD; if you need to enter a multiline description.

Permissions

When creating / updating roles, you can use one of the following names in the attribute platformCapability.name

platformCapability.name Full name
data-integration-api Access data integration API
debug-tools Access debugging tools
full-admin Bypass Security
libraries-import Access data integration libraries (UI/Import)
manage-application Manage the application
platform-administration Access administration tools
platform-logs Access logs
platform-monitoring Access monitoring tools
rights-management Manage users and roles

Related Links