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) | < |
> (greater than) | > |
& (ampersand) | & |
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:
Enter password
Confirm password
Press [Encrypt] button (password and confirmed password must match in order to proceed)
Password is encrypted and displayed
Copy encrypted password
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.
