Documentum security enhancements

Introduction

The present document offers a detailed description of the Documentum security enhancements introduced with version 3.2.4 of migration-center.

The additional security features provide means for system administrators to define an additional layer of security between migration-center and Documentum repositories.

Some of the features offered are:

• delegating access to users without having to give them superuser privileges and credentials directly on the respective repositories

• controlling the type of operation a user is allowed to perform on a given repository (import and/or export)

• controlling which paths a user can access to perform the above actions on a given repository

• controlling where a user is allowed to export scanned documents to

• limit the validity or duration of a security configuration by setting a date until which the configuration is considered valid

• encrypting any passwords saved in the security configuration file

The implementation and configuration of the security enhancement features is transparent to end-users working with migration-center. End-users working with migration-center will be notified through on-screen messages if they trigger actions or use configurations which conflict with any enhanced security settings.

Usage of the enhanced security features is also optional. Removing or renaming the main security configuration file will disable the feature and will revert migration-center to its standard behavior when working with Documentum repositories (as described in the Documentum Scanner and Documentum Importer user guides).

Targeted audience

The security features as well as this document is targeted specifically at system administrators managing Documentum Content Servers and access to the respective repositories, especially through migration-center.

Technical Information

System requirements

System requirements are unchanged for the Documentum security enhancements feature. The same requirements as for using migration-center with the Documentum Scanner and Documentum Importer apply. For more information about general system requirements as well as supported Documentum versions and requirements please see the Installation Guide, Documentum Scanner user guide, and Documentum Importer user guide.

Implementation and integration with migration-center

The Documentum security enhancements features are implemented as an additional, optional module which integrates with migration-center’s Documentum Scanner and Documentum Importer.

The presence of the Documentum security enhancements module will be detected by migration-center automatically, and if a valid configuration exists the settings within will apply every time a Documentum Scanner or Documentum Importer job is executed.

The Documentum security enhancements module is located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder. This folder contains the code package, sample configuration file, and tools used by the feature.

There is one tool for encrypting passwords to be stored in the configuration file, and another tool for validating the configuration file’s structure. The configuration file itself is a human-readable and editable XML file. The tools and configuration file will be described in detail in the following chapters.

The Documentum security enhancements feature is disabled by default (after installation). Since the configuration of the features depends on the customer’s preferences and requirements, this configuration must be created first before the feature can work. Configuration is described in section Configuration.

Disabling Documentum Security Enhancements

The Documentum security enhancements feature is disabled by default and will become active only after a correct configuration file has been created and provided by the system administrator.

Should it be required to disable this feature after it has been configured and is in use, this can be achieved easily using either one of the below approaches:

• Rename, move, or delete the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder

• Rename, move, or delete the mc-dctm-security-config.xml file located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder

As always, consider backing up any files before making changes to them.

Changes to the security configuration file, deleting, renaming or moving it, will not affect currently running Documentum Scanner or Documentum Importer jobs. Changes will only take effect for jobs started afterwards

General Security Considerations

Since the Documentum security enhancements feature’s folder (<migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config) can contain sensitive information, it is advised to secure this folder using the file system and network security and access policies applicable to such information for the environment where migration-center is deployed in order to prevent unauthorized access.

At the same time the user account used for running the migration-center Jobserver service must be allowed access to this folder, as any Documentum Scanner or Documentum Importer will run in the context of the migration-center Jobserver, thus requiring access to the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder and its contents.

Configuration

Configuration file

The configuration file controls all aspects of the Documentum security enhancement features. A valid configuration file needs to be provided by the system administrator configuring migration-center for the feature to work. As long as no valid configuration file exists, the feature will be disabled and will have no effect.

The configuration file must be named mc-dctm-security-config.xml and must be located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder.

Since the exact configuration depends on the customer’s environment, a preconfigured file cannot be delivered with migration-center. Instead a sample file illustrating the structure and parameters available for configuration is delivered and can be used as a starting point for creating a valid configuration. The sample file is named mc-dctm-security-config-sample.xml and is located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder.

The sample configuration file can be copied and renamed to mc-dctm-security-config.xml to create the base for the actual configuration file, which will be edited by a system administrator.

The sample configuration file is also listed in section Sample configuration file.

General Information regarding XML

The configuration file is a human-readable XML file and can be edited with any text editor, or application providing XML editing capabilities. In order for the configuration file to be valid it will have to conform to XML standards in terms of syntax and encoding, something that should be considered when editing the file using a text editor. Migration-center will validate the file and refuse operation if the file structure or its contents are found to be invalid.

Special characters

Certain special characters need to be escaped according to the XML syntax in order to be entered and interpreted correctly as values. See below a list of these characters:

Character	Escape in XML as
" (quote)	"
' (apostrophe)	'
< (less than)	&lt;
> (greater than)	&gt;
& (ampersand)	&amp;

Encoding

The XML standard allows many different types of encodings to be used XML files. Encodings affect how international characters are interpreted and displayed. It is recommended to use the UTF-8 encoding, which can represent all international characters available today in the UTF character set.

Note that the (mandatory) XML header tag <?xml version="1.0" encoding="UTF-8"?> does not set the encoding, it merely specifies that the current file is supposed to be encoded using UTF-8; the actual encoding used is not directly visible to the user and depends on how the file is saved by the application used to save it after editing. Please consult your text editor’s documentation about saving files using specific encodings, such as UTF-8.

See the official source http://www.w3.org/standards/xml/ for more information about XML.

Configuration file parameters

This paragraph describes the structure of the Documentum Enhanced Security configuration file. It will list all available configuration elements, their allowed values and whether the respective parameter is mandatory to be set or not.

The <configuration> element

A <configuration> block defines an entire configuration block controlling access of one user to a repository. All other parameters which apply to that repository and user must be contained in the same <configuration> block.

Multiple repositories and users can be configured by creating multiple <configuration> blocks in the configuration file.

configuration Properties
Mandatory	yes
Can occur multiple times	yes
Attributes	repository_name migration_user action_allowed
Allowed values	None (contains other elements, not value)
Example	<configuration repository_name="repo1" migration_user="external.user" action_allowed="scan"> … … … </configuration>

Attribute repository_name

repository_name is an attribute of a <configuration> element and defines the Documentum repository the current configuration block applies to.

repository_name Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None (is an attribute)
Allowed values	String representing one valid Document repository name
Example	<configuration repository_name="repo1" migration_user="external.user" action_allowed="scan"> … … … </configuration>

Attribute migration_user

migration_user is an attribute of a <configuration> element and defines the migration user who will be granted access to the repository. This user will need to be configured in any Documentum job (scanner or importer) meant to access the repository defined in repository_name.

migration_user Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None (is an attribute)
Allowed values	String identifying a migration user
Example	<configuration repository_name="repo1" migration_user="external.user" action_allowed="scan"> … … … </configuration>

Attribute action_allowed

action_allowed is an attribute of a <configuration> element and defines what type of action a user is allowed to perform on the repository defined in repository_name. A user may be allowed to scan, import, or perform both actions on the repository.

action_allowed Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None (is an attribute)
Allowed values	scan import both
Example	<configuration repository_name="repo1" migration_user="external.user" action_allowed="scan"> … … … </configuration>

Element effective_date

effective_date is a child element of configuration. effective_date sets a date until which the current configuration is allowed to be executed. If the set date is exceeded when a job is started, the job will not be permitted to execute and the user will be notified about the configuration having expired.

effective_date Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None
Allowed values	Valid date using the format YYYY-MM-DD
Example	<configuration …> … <effective_date>2013-12-22</effective_date> … </configuration>

Element super_user_name

super_user_name is a child element of configuration. super_user_name defines a Documentum superuser which will be used to connect to the repository defined in repository_name. The migration-center user running the job will not need to know the Documentum superuser’s name or password, this will only be known and used internally by migration-center.

super_user_name Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None
Allowed values	String identifying a valid Documentum superuser
Example	<configuration …> … <super_user_name>dmadmin</super_user_name> … </configuration>

Element super_user_password

super_user_password is a child element of configuration. super_user_password defines the password for the Documentum superuser which will be used to connect to the repository defined in repository_name. The migration-center user running the job will not need to know the Documentum superuser’s name or password, this will only be known and used internally by migration-center.

The password needs to be stored in encrypted form; see Password encryption tool for information about how to encrypt the password.

super_user_password Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None
Allowed values	String defining the Documentum superuser’s password (in encrypted form)
Example	<configuration …> … <super_user_password>DSzl1hrzj+yYMLOtxR5jlg==</super_user_password> … </configuration>

Element migration_user_password

migration_user_password is a child element of configuration. migration_user_password defines the password for the migration user who will be granted access to the repository. This password will need to be configured in any Documentum job (scanner or importer) meant to access the repository defined in repository_name.

The password needs to be stored in encrypted form; see Password encryption tool for information about how to encrypt the password.

migration_user_password Properties
Mandatory	yes
Can occur multiple times	no
Attributes	None
Allowed values	String defining the migration user’s password (in encrypted form)
Example	<configuration …> … <migration_user_password>DSzl1hrzj+yYMLOtxR5jlg==</migration_user_password> … </configuration>

Element allowed_paths

allowed_paths is a child element of configuration. allowed_paths defines paths the migration user will be allowed to access in the specified Documentum repositories. The allowed_paths element is optional; if this element is omitted, access to all folders will be granted (whether access will actually succeed depends on the respective Documentum repositories permissions of course).

allowed_paths Properties
Mandatory	no
Can occur multiple times	no
Attributes	None
Allowed values	Elements of type <path>
Example	<configuration …> … <allowed_paths> <path>/Import</path> <path>/Public/Documents</path> <path>/User Cabinets</path> </allowed_paths> … </configuration>

Element allowed_export_locations

allowed_export_locations is a child element of configuration. allowed_export_locations defines local paths or UNC paths (network shares) where the migration user will be allowed to export content from Documentum repositories. This (these) path(s) will need to be used in the Documentum scanner’s configuration as exportLocation (please see the Documentum Scanner User Guide for more information about the Documentum Scanner and the exportLocation parameter).

allowed_export_locations Properties
Mandatory	yes when running a Documentum Scanner not relevant when running a Documentum Importer
Can occur multiple times	no
Attributes	None
Allowed values	Elements of type <path>
Example	<configuration …> … <allowed_export_locations> <path>d:\mc\export</path> <path>\\server\share\mc export folder</path> </allowed_export_locations> … </configuration>

Element path

path is a child element of allowed_paths or allowed_export_location. It specifies individual Documentum paths (when used with allowed_paths) or local file system paths or UNC paths (network shares) when used with allowed_export_locations.

path Properties
Mandatory	Depends on whether it is used with allowed_paths or allowed_export_locations. Please see the respective elements’ descriptions
Can occur multiple times	yes
Attributes	None
Allowed values	One string per <path> element representing a valid Documentum path (when used with allowed_paths) or local file system path or UNC path (when used with allowed_export_locations)
Example	<configuration …> … <allowed_paths> <path>/Import</path> <path>/Public/Documents</path> <path>/User Cabinets</path> </allowed_paths> <allowed_export_locations> <path>d:\mc\export</path> <path>\\server\share\mc export folder</path> </allowed_export_locations> … </configuration>

Supporting Tools

Password encryption tool

Passwords must be encrypted when saved to the configuration file. Encryption is performed using the supplied password encryption tool. The password encryption tool is located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder and can be executed using encrypt-tool.

Usage:

1. Enter password

2. Confirm password

3. Press [Encrypt] button (password and confirmed password must match in order to proceed)

4. Password is encrypted and displayed

5. Copy encrypted password

6. Paste encrypted password in migration_user_password or super_user_password element of configuration file

Configuration file verification tool

The configuration file must be a valid XML file. For convenience a verification tool is provided to check the validity of the configuration file against an XML Schema Definition file.

Migration-center will also validate the file internally and refuse operation if the file structure or its contents are found to be invalid.

The configuration file verification tool is located in the <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config folder and can be executed using check-configuration.

Sample output for a valid configuration file

C:\Program Files (x86)\fme AG\migration-center Server Components 3.13\lib\mc-dctm-adaptor\security-config>check-configuration.cmd

******************************** * Configuration OK * ********************************

Sample output for an invalid (corrupted) configuration file

C:\Program Files (x86)\fme AG\migration-center Server Components 3.13\lib\mc-dctm-adaptor\security-config>check-configuration.cmd

******************************** * Configuration FAILED * ******************************** de.fme.mc.common.MCException: An error has occured when loading security configuration: org.xml.sax.SAXParseException; systemId: file:///C:/Program%20Files%20(x86)/fme%20AG/migration-center%20Server%20Components%203.13/lib/mc-dctm-adaptor/security-config/mc-dctm-security-config.xml; lineNumber: 5; columnNumber: 29; The element type "effective_date" must be terminated by the matching end-tag "</effective_date>".

Sample configuration file

A sample configuration file is provided in <migration-center Server Components installation folder>/lib/mc-dctm-adaptor/security-config/mc-dctm-security-config-sample.xml.

The contents of this file are also listed below for reference.

<?xml version="1.0" encoding="UTF-8"?>
<security-configuration>
    <!-- A configuration should be created for each users that needs to use migration center
    to scan or import data from/into Documentum
    The attributes repository_name, migration_user and action_allowed are mandatory
    and are used to uniquely identify a configuration.
    The allowed values for "action_allowed" are: scan, import or both. Both meaning
    that the configuration will apply to both scanners and importers.
    -->
    <configuration repository_name="production" migration_user="John Smith" action_allowed="both">
        <!-- Encrypted password of the migration_user. The encryption tool must be used to
        get the encrypted password.
        Mandatory.
        -->
        <migration_user_password>NVnP0RwMfTulUrpjOYj0tA==</migration_user_password>
        <!-- The date until the configuration is valid.
        Mandatory.
        -->
        <effective_date>2013-11-04</effective_date>
        <!-- The super user name that will be used for connecting to Documentum.
        Mandatory.
        -->
        <super_user_name>Administrator</super_user_name>
        <!-- Encrypted password of the super userr. The encryption tool must be used to
        get the encrypted password.
        Mandatory.
        -->
        <super_user_password>DSzl1hrzj+yYMLOtxR5jlg==</super_user_password>
        <!-- Documentum folder and cabinets where the users is allowed to scan from or to import into.
        This is optional. If it's not set there is no restriction for the users.
        -->
        <allowed_paths>
            <path>/Cabinet1</path>
            <path>Cabinet2/Folder1</path>
        </allowed_paths>
        <!-- The local folders or shares are the user is allowed to export objects.
        This apply only to scanners. The folders configured here should be not
        accessible to the migration users in order to protect the exported content
        but it should be accessible to the windows user under Jobserver service is running.
        This is mandatory for the scanner.
        -->
        <allowed_export_locations>
            <path>\\fileserver\mc_export</path>
            <path>d:\export_location</path>
        </allowed_export_locations>
    </configuration>
</security-configuration>