About the Security Map wizard

With the Security Map wizard you can map the security policies for user and group accounts, also called security principals, in one domain to the same or different accounts in another domain. The mapping process is accomplished by updating the security principals contained in a specified XML import file according to the valid principals defined in the current realm.

NOTE  You cannot change from one directory server type to another when mapping accounts. For example, mapping accounts in the Active Directory to accounts in Sun Java™ System Directory Server is not supported.

The input requirements for the Security Map wizard are (1) a properly formatted import file and (2) a properly formatted security map file. The following sections describe the requirements and behavior of the wizard in greater detail:

How the XML import file is created

FileNet P8 supports the use of XML script files for exporting and importing object store information, including security principals.

Prior to FileNet P8 version 3.5.1, the export file generated by Enterprise Manager consisted of a single XML file called the export manifest file. As of FileNet P8 version 3.5.1, Enterprise Manager generated multiple XML files which were listed in a single TXT file, still called the export manifest. With release 4.0, Enterprise Manager generates an Export Descriptor File, which is an XML file containing the list of export XML files. The Security Mapping wizard accepts pre-3.5.1 (single) XML files, and the Export Manifest TXT files generated by 3.5.1 and subsequent 3.5.x releases, as well as the 4.0-generated XML Export Descriptor XML file as valid input.

When you export object store information in Enterprise Manager, you can also export the security policy information:

For each security principal that is defined in the XML, the following information is also exported:

The exported information is saved to one or more XML files which are listed in the .txt manifest file. The Security Map wizard then uses the import file to update the security principal information contained in the manifest according to the valid principals defined in the security map file or the current realm.

How the security map is created

A security map identifies how security principals in one domain should be mapped to principals in another domain. When you use the Security Map wizard, you can instruct the wizard to create a map file using the valid principals for the current realm, or specify that a previously generated security map should be used.

The Security Map wizard creates the security map by building a list of the security principals defined in the imported XML and then determining the "best match" for each principal by processing the principals contained in the preexisting map file, or by generating a new map using the valid principals for the current realm. For each security principal encountered in the XML file, the wizard attempts to locate the best matching principal according to the following steps:

  1. Use the Name to resolve the principal.
    NOTE   This condition will only yield a match when importing principals into the same domain. If no match is found, proceed to Step 2.
  2. Use the ShortName and iterate through the valid realms until a match is found and the principal is resolved. If no match is found, proceed to Step 3.
  3. Use the DisplayName and iterate through the valid realms until a match is found and the principal is resolved. If no match is found, proceed to Step 4.
  4. When the security principal could not be resolved (no match was found), leave the map entry blank.
    NOTE   All non-resolved security principals are listed first in the map.

The wizard provides options which allow you to edit the map and override any entries, as well save the map for future use.

How security principals are updated

The basic usage scenario and processing behavior of the Security Map wizard is as follows:

  1. Design and develop an application, including metadata and objects needed for the application.
  2. Using Enterprise Manager, export all application related data (including security) into an XML file for future deployment. For more information about how to include security information in the export manifest for an object store, see Exporting objects from an object store and How to choose objects to include on the export manifest.
  3. Just prior to deploying the application to another system, run the Security Map wizard through Enterprise Manager.
  4. Specify the XML import file generated in Step 2.
  5. Specify a new or existing security map file in which to store the generated map for future use.
  6. Specify an XML output file in which to save the updated security principal based on the map.
    NOTE   Selecting to save the results of the mapping operation to the existing XML import file specified in Step 4 can result in unexpected application behavior or even failure. Therefore, specify a different name for the output file, rather than using the same name as the import file.
  7. The Security Map wizard generates the security map.
  8. The wizard displays the map to the user and enables editing of map entries.
  9. The wizard completes the mapping operation, which results in two generated files:
    A security map file that can be used in the future.
    An XML output file containing the updated security principals based on the security map or current realm definitions, as well as any user edits.
  10. Import the XML output file into the target object store.

Example of a properly formatted security map file

A properly formatted security map file contains the following elements:

The following code fragment demonstrates how these elements should appear in a security map file Microsoft® Windows authentication:

<SecurityPrincipalMap>
    <PrincipalMap>
       <SourcePrincipal>
          <SID>S-1-5-21-588586621-1056035706-3148668796-1105</SID>
          <Name>guest@ALASKA1.LOCAL</Name>
          <ShortName>guest</ShortName>
          <DisplayName>Guest User</DisplayName>
          <PrincipalType>1</PrincipalType>
       </SourcePrincipal>
       <DestinationPrincipal>
          <SID>S-1-5-21-588586621-1056035706-3148668796-1407</SID>
          <Name>visitor@ALASKA1.LOCAL</Name>
          <ShortName>visitor</ShortName>
          <DisplayName>Visitor</DisplayName>
          <PrincipalType>1</PrincipalType>
       </DestinationPrincipal>
    </PrincipalMap>
    <PrincipalMap>
       <SourcePrincipal>
          <SID>S-1-3-0</SID>
          <Name>#CREATOR-OWNER</Name>
          <ShortName />
          <DisplayName />
          <PrincipalType>0</PrincipalType>
       </SourcePrincipal>
       <DestinationPrincipal>
          <SID>S-1-3-0</SID>
          <Name>#CREATOR-OWNER</Name>
          <ShortName />
          <DisplayName />
          <PrincipalType />
       </DestinationPrincipal>
    </PrincipalMap>
    <PrincipalMap>
       <SourcePrincipal>
          <SID>S-1-5-21-588586621-1056035706-3148668796-500</SID>
          <Name>Administrator@ALASKA1.LOCAL</Name>
          <ShortName>Administrator</ShortName>
          <DisplayName>Administrator</DisplayName>
          <PrincipalType>0</PrincipalType>
       </SourcePrincipal>
       <DestinationPrincipal>
          <SID>S-1-5-21-588586621-1056035706-3148668796-1133</SID>
          <Name>ADMIN_SYSTEM@ALASKA1.LOCAL</Name>
          <ShortName>ADMIN_SYSTEM</ShortName>
          <DisplayName>System Administrator</DisplayName>
          <PrincipalType>0</PrincipalType>
       </DestinationPrincipal>
    </PrincipalMap>
 </SecurityPrincipalMap>

Example of security principals in an XML import file

Security principals appear in the exported XML files (listed in the export manifest) as owner and access permission settings on a per object or object type basis. In addition to the properties identified in the previous section, the AccessType (same as PrincipalType), InheritableDepth, AccessMask, and PermissionSource attributes are also present as part of the security policy definition for an object. The following code fragment demonstrates how a security policy and security principal definitions might appear in an XML import file under Windows authentication:

...
    <PropertyTemplateObjectSecurity>
       <Owner>
          <SID>S-1-5-21-588586621-1056035706-3148668796-138</SID>
          <Name>bsmith@ALASKA1.LOCAL</Name>
          <ShortName>bsmith</ShortName>
          <DisplayName>Bob Smith</DisplayName>
          <PrincipalType>0</PrincipalType>
       </Owner>
       <Permissions>
          <AccessPermission> 
             <Grantee> 
                <SID>S-1-5-11</SID>
                <Name>#AUTHENTICATED-USERS</Name>
             </Grantee> 
             <AccessType>1</AccessType>
             <InheritableDepth>0</InheritableDepth>
             <AccessMask>131073</AccessMask>
             <PermissionSource>1</PermissionSource> 
          </AccessPermission>
          <AccessPermission> 
             <Grantee> 
                <SID>S-1-5-21-588586621-1056035706-3148668796-138</SID>
                <Name>bsmith@ALASKA1.LOCAL</Name>
                <ShortName>bsmith</ShortName>
                <DisplayName>Bob Smith</DisplayName>
                <PrincipalType>0</PrincipalType> 
             </Grantee> 
             <AccessType>1</AccessType>
             <InheritableDepth>0</InheritableDepth>
             <AccessMask>995587</AccessMask>
             <PermissionSource>0</PermissionSource> 
          </AccessPermission> 
       </Permissions>
    </PropertyTemplateObjectSecurity>
...

To run the Security Map wizard using Enterprise Manager

  1. Right-click the object store node and select All tasks > Security Mapping Wizard (pre-import).
  2. Follow the instructions in the wizard. The updates that you specify in the wizard will be saved in the XML file and network location which you specify.