Chapter 9. Connecting to External Resources

1. Download the OPENICF .NET Connector Server from the OpenIDM download page under the ForgeRock Open Stack download page.

2. Execute ServiceInstall--dotnet.msi.

3. Complete the wizard.

The .NET Connector Server can be started one of two ways.

1. In the Microsoft Service Console, go to Start, type Services, Services.

   or

2. In the command prompt, go to Start, type cmd, then cmd again.

3. Change the directory to the location where the Connector Server was installed. The default location is Program Files/Identity Connectors/Connector Server.

4. Enter cd Program Files (x86)/Identity Connectors/Connector Server.

5. Start the server with the following command:

   ConnectorServer.exe/run

   .

After starting the Microsoft Services Console, follow these steps to configure the .NET Connector Server.

1. Check to see if the Connector Server is currently running. If so, stop it. All configuration changes require that the Connector Server be stopped and restarted after the changes are saved.

2. At the command prompt (click Start, Run, then type cmd, set the key for the Connector Server by changing to the directory where the Connector Server was installed and executing the following command, using a string value for newkey:

   ConnectorServer.exe /setkey <newkey>

   This key is used by clients connecting to the Connector Server.

3. Review the ConnectorServer.exe.config file to verify additional configuration, including the port, address, and SSL settings in the AppSettings.

   <add key="connectorserver.port" value="8759" />
   <add key="connectorserver.usessl" value="false" />
   <add key="connectorserver.certificatestorename" value="ConnectorServerSSLCertificate" />
   <add key="connectorserver.ipaddress" value="0.0.0.0" />
   

   The port can be set by changing the value of connectorserver.port. The listening socket can be bound to a particular address, or can be left as 0.0.0.0.

   To configure the server to use SSL, set the value of connectorserver.usessl to true and set the value of connectorserver.certifacatestorename to the certificate store name.

4. Trace settings are also in the configuration file.

   <system.diagnostics>
   <trace autoflush="true" indentsize="4">
   <listeners>
   <remove name="Default" />
   <add name="myListener" type="System.Diagnostics.TextWriterTraceListener" 
   initializeData="c:\connectorserver2.log" traceOutputOptions="DateTime">
   <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information" />
   </add>
   </listeners>
   </trace>
   </system.diagnostics>
         

   The Connector Server uses the standard .NET trace mechanism. For more information about the tracing options, see Microsoft's .NET documentation for System.Diagnostics.

   Note

   The default settings are a good starting point, but for less tracing, you can change the EventTypeFilter's initializeData to "Warning" or "Error". For very verbose logging you can set the value to "Verbose" or "All". The amount of logging performed has a direct effect on the performance of the Connector Servers, so be careful of the setting.

5. Download the AD Connector from the OpenIDM download page under the ForgeRock Open Stack download page.

6. Unzip the directory in the Connector Server folder.

7. Start the Connector Server service.

When you configure remote connectors, you must use the connector info provider service to connect through remote connector servers. The configuration is stored in the configuration file, openidm/conf/provisioner.openicf.connectorinfoprovider.json. A sample can be found under openidm/samples/provisioners/.

1. Make sure that OpenIDM is running and copy the provisioner.openicf.connectorinfoprovider.json to /path/to/openidm/conf and edit it as needed.

   $ cd path/to/openidm
   $ cp samples/provisioners/provisioner.openicf.connectorinfoprovider.json conf/
         

2. Create the connector file provisioner.openicf-ad.json in conf/ directory. The following is an example of what the name, bundleVersion, and a few other configuration properties will look like.

         {
   "name" : "ad",
   "connectorRef" : {
   "connectorHostRef" : "dotnet",
   "connectorName" : "Org.IdentityConnectors.ActiveDirectory.ActiveDirectoryConnector",
   "bundleName" : "ActiveDirectory.Connector",
   "bundleVersion" : "1.0.0.0"
   },
   "poolConfigOption" : {
   "maxObjects" : 10,
   "maxIdle" : 10,
   "maxWait" : 150000,
   "minEvictableIdleTimeMillis" : 120000,
   "minIdle" : 1
   },
   "operationTimeout" : {
   "SYNC" : -1,
   "TEST" : -1,
   "SEARCH" : -1,
   "RESOLVEUSERNAME" : -1,
   "SCRIPT_ON_CONNECTOR" : -1,
   "VALIDATE" : -1,
   "DELETE" : -1,
   "UPDATE" : -1,
   "AUTHENTICATE" : -1,
   "CREATE" : -1,
   "SCRIPT_ON_RESOURCE" : -1,
   "GET" : -1,
   "SCHEMA" : -1
   },
   "configurationProperties" : {
   "DirectoryAdminName" : "EXAMPLE\\Administrator",
   "DirectoryAdminPassword" : {
   "$crypto" : {
   "value" : {
   "iv" : "QJctjWJi9w2uPLsO2Pucfw==",
   "data" : "Akqzk1PW0m9QP5cfOMIuYw==",
   "cipher" : "AES/CBC/PKCS5Padding",
   "key" : "openidm-sym-default"
   },
   "type" : "x-simple-encryption"
   }
   },
   "ObjectClass" : "User",
   "Container" : "dc=example,dc=com",
   "CreateHomeDirectory" : true,
   "LDAPHostName" : "10.0.0.2",
   "SearchChildDomains" : false,
   "DomainName" : "example",
   "SyncGlobalCatalogServer" : null,
   "SyncDomainController" : null,
   "SearchContext" : ""
   }

3. Edit the configurationProperties according to your setup and make sure that the bundleVersion is the same version as ActiveDirectory.Connector.dll in the Windows Connector Server folder. (Right click on the dll, properties, tab details, and Product version.)

4. Make sure the connector was installed properly using the following command:

   scr list
         

   This should return all of the installed modules, including the following:

   [  24] [active       ] org.forgerock.openidm.provisioner.openicf

   Note

   The number may differ. Make sure to note the number returned.

   Review the content of the connector using the following command, using the number returned from the previous step:

   scr info <your number>

5. Create the sync.json file where you define mappings of various attributes and behaviors during reconciliation. The following is a simple example of a sync.json.

   { 
   "mappings" : [ 
   { 
   "name" : "systemADAccounts_managedUser", 
   "source" : "system/ad/account", 
   "target" : "managed/user", 
   "properties" : [ 
    { 
      "source" : "sAMAccountName", 
       "target" : "userName" 
    }, 
    { 
       "source" : "sn", 
       "target" : "lastname" 
    }, 
    { 
       "source" : "givenName", 
       "target" : "firstname" 
       } 
      ] 
     }
    ]
   }

6. Run the reconciliation with the following command.

   $ curl --header "X-OpenIDM-Username: openidm-admin" --header "X-OpenIDM-Password: 
   openidm-admin" --request POST  "http://localhost:8080/openidm/recon?
   _action=recon&mapping=systemADAccounts_managedUser"

   This will return a reconciliation id similar to the following:

   {"_id":"0629d920-e29f-4650-889f-4423632481ad"}

7. Check the internal repository (OrientDB or MySQL) to make sure that the users were reconciled. For information about connecting to OrientDB, see Before You Begin in the Installation Guide. For information about using MySQL as a repository, see Installing a Repository For Production in the Installation Guide.

1. Download the OPENICF JAVA Connector Server from the OpenIDM download page under the ForgeRock Open Stack download page.

2. Run the terminal and unpack it. The following command will unzip the file in the current folder, so make sure to move to the appropriate location prior to running the command.

   unzip openicf--java.zip

3. Change the directory to OpenICF using the following command:

   $ cd path/to/openicf

4. If needed, secure the communication between OpenIDM and JCS. The JCS uses a property called secret key to authenticate the connection. The default secret key value is changeit. To change the value of the secret key enter the following, replacing newkey with the your own string value:

   java - cp "./lib/framework/*" org.identityconnectors.framework.server.Main 
          -setKey -key <newkey> -properties ./conf/ConnectorServer.properties

5. Review the ConnectorServer.properties in the /conf directory, and make changes as necessary. The file contains setting information, including things like ports, the allowance of one/all IP addresses, and SSL. The file provides the required information to update these settings.

6. Run the JCS.

   java -cp "./lib/framework/*"
   org.identityconnectors.framework.server.Main -run -properties 
   ./conf/ConnectorServer.properties

7. If necessary, you can stop the JCS by pressing ^C.

1. Download the OPENICF JAVA Connector Server from the OpenIDM download page under the ForgeRock Open Stack download page.

2. Unpack the zip file in the desired location, for example C:\openicf.

3. Run the command line (Start, type cmd, and cmd) and change the working directory to openicf\bin cd c:\openicf\bin

4. Change the directory to OpenICF using the following command:

   $ cd path/to/openicf

5. If needed, secure the communication between OpenIDM and JCS. The JCS uses a property called secret key to authenticate the connection. The default secret key value is changeit.

   To change the value of the secret key enter the following, replacing newkey with the your own string value:

   /ConnectorServer.bat /setkey <newkey>

6. Review the ConnectorServer.properties in the /conf directory, and make changes as necessary. The file contains setting information, including things like ports, the allowance of one/all IP addresses, and SSL. The file provides the required information to update these settings.

7. If you would like the JCS to run as a Windows service, enter the following command.

   ./ConnecorServer.bat /install (for uninstalling use /uninstall )

   Note

   If you install JCS as a Windows service you can start/stop it by Microsoft's Service Console (Start, type Service, and Service). The JCS service is called: OpenICFConnectorServerJava.

   Or

   If you would like to run the JCS from command line, enter the following command:

   .\ConnectorServer.bat /run

8. If necessary, stop the JCS by pressing ^C.

• Copy the openidm/samples/sample1/data directory to a location on the JCS machine.

1. Start OpenIDM. You can ignore errors like cannot connect to database and cannot find jdbc driver. These errors will be fixed once OpenIDM has been configured and restarted.

2. Copy the openidm/samples/sample1/conf directory to openidm/conf. Overwrite any existing files.

   For Unix/Linux, enter the following in a terminal window.

   $ cd path/to/openidm
   $ cp -r ./samples/sample1/conf ./conf

   For Windows, enter the following on the command line.

   c:\> cd path\to\openidm
   .\> copy .\samples\sample1\conf .\conf

3. Copy the openidm/samples/provisioners/provisioner.openicf.connectorinfoprovider.jso to openidm/conf.

   $ cp . samples/provisioners/provisioner.openicf.connectorinfoprovider.json ./conf

4. Edit the provisioner.openicf.connectorinfoprovider.json to match your network setup. The following is an example of how it could look.

   { 
   	    "connectorsLocation" : "connectors", 
   	    "remoteConnectorServers" : [ 
   	        { 
   	            "name" : "xml", 
   	            "host" : "10.0.0.2", 
   	            "port" : 8759, 
   	            "useSSL" : false, 
   	            "timeout" : 0, 
   	            "key" : "password" 
   	        } 
   	    ], 
   	}

5. Edit the provisioner.openicf-xml.json in the /conf directory to read like the following.

   {
       "name" : "xmlfile", 
       "connectorRef" : { 
           "connectorHostRef" : "xml", 
           "bundleName" : "org.forgerock.openicf.connectors.file.openicf-xml-connector", 
           "bundleVersion" : "",
           "connectorName" : "com.forgerock.openicf.xml.XMLConnector" 
       }, 
       "producerBufferSize" : 100, 
       "connectorPoolingSupported" : true, 
       "poolConfigOption" : { 
           "maxObjects" : 10, 
           "maxIdle" : 10, 
           "maxWait" : 150000, 
           "minEvictableIdleTimeMillis" : 120000, 
           "minIdle" : 1 
       }, 
       "operationTimeout" : { 
           "CREATE" : -1, 
           "TEST" : -1, 
           "AUTHENTICATE" : -1, 
           "SEARCH" : -1, 
           "VALIDATE" : -1, 
           "GET" : -1, 
           "UPDATE" : -1, 
           "DELETE" : -1, 
           "SCRIPT_ON_CONNECTOR" : -1, 
           "SCRIPT_ON_RESOURCE" : -1, 
           "SYNC" : -1, 
           "SCHEMA" : -1 
       }, 
       "configurationProperties" : { 
           "xsdIcfFilePath" : "/Program files (x86)/openicf/data/
           resource-schema-1.xsd", 
           "xsdFilePath" : "/Program Files (x86)/openicf/data/
           resource-schema-extension.xsd", 
           "xmlFilePath" : "/Program Files (x86)/openicf/data/xmlConnectorData.xml" 
       }, 
       "objectTypes" : { 
           "account" : { 
               "$schema" : "http://json-schema.org/draft-03/schema", 
               "id" : "__ACCOUNT__", 
               "type" : "object", 
               "nativeType" : "__ACCOUNT__", 
               "properties" : { 
                   "description" : { 
                       "type" : "string", 
                       "nativeName" : "__DESCRIPTION__", 
                       "nativeType" : "string" 
                   }, 
                   "firstname" : { 
                       "type" : "string", 
                       "nativeName" : "firstname", 
                       "nativeType" : "string" 
                   }, 
                   "email" : { 
                       "type" : "array", 
                       "items" : { 
                           "type" : "string", 
                           "nativeType" : "string" 
                       }, 
                       "nativeName" : "email", 
                       "nativeType" : "string" 
                   }, 
                   "__UID__" : { 
                       "type" : "string", 
                       "nativeName" : "__UID__" 
                   }, 
                   "password" : { 
                       "type" : "string", 
                       "required" : false, 
                       "nativeName" : "__PASSWORD__", 
                       "nativeType" : "JAVA_TYPE_GUARDEDSTRING", 
                       "flags" : [ 
                           "NOT_READABLE", 
                           "NOT_RETURNED_BY_DEFAULT" 
                       ] 
                   }, 
                   "name" : { 
                       "type" : "string", 
                       "required" : true, 
                       "nativeName" : "__NAME__", 
                       "nativeType" : "string" 
                   }, 
                   "lastname" : { 
                       "type" : "string", 
                       "required" : true, 
                       "nativeName" : "lastname", 
                       "nativeType" : "string" 
                   } 
               } 
           } 
       }, 
       "operationOptions" : { } 
   }

6. Verify that the following settings are correct.

   • The value of connectorHostRef : xml points to the property name of provisioner.openicf.connectorinfoprovider.json. This indicates which connectorinfoprovider to use.

   • The bundleVersion : must be exactly the same as openicf-scriptedsql-connector-.jar. on JCS /bundles.

   • The path to xsdIcfFilePath : /Program files (x86)/openicf/data/resource-schema-1.xs

7. Restart OpenIDM to verify that all of the configuration changes have occurred. There should be no error message when OpenIDM is restarted. To check, run the following command:

   src list

   This returns a list of installed modules, including the following:

   [  17] [active       ] org.forgerock.openidm.provisioner.openicf 

   Note

   The number may differ. Make sure to note the number returned.

   When you have installed more connectors, there will be more OpenIFC modules. If the state of the module is active, the module is installed properly. If the state is unsatisfied, then you have not configured it correctly and you must check your configuration. You can also check the content of installed modules. This can be useful if you have an unsatisfied state and you want to check that the content is the same as in the *.json file, to verify that the configuration change you made was picked up. To list the content of the module run the following command, with the number returned from the previous step:

   scr info 17 <your number>

   Note

   You can also check the provisioner.openicf.connectorinfoprovider

8. Run reconciliation with the following command.

   $ curl --header "X-OpenIDM-Username: openidm-admin" 
   --header "X-OpenIDM-Password: openidm-admin" --request POST 
   "http://localhost:8080/openidm/recon?_action=recon&mapping=systemXmlfileAccounts_managedUser"

   This will return a reconciliation id similar to the following:

   {"_id":"a5346543-db9a-4f8b-ba25-af2a1b576a54"}

9. Check the internal repository (OrientDB or MySQL) to make sure that the users were reconciled. For information about connecting to OrientDB, see Before You Begin in the Installation Guide. For information about using MySQL as a repository, see Installing a Repository For Production in the Installation Guide.