README revision 8379ee46ec93e390435dc32135a00a26bb5d77b7
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen/**
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen *
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * Copyright (c) 2014 ForgeRock AS. All rights reserved.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen *
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * The contents of this file are subject to the terms
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * of the Common Development and Distribution License
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * (the License). You may not use this file except in
7d6389e4053c2dac1fb37180b5756b00785983dcTimo Sirainen * compliance with the License.
7d6389e4053c2dac1fb37180b5756b00785983dcTimo Sirainen *
22535a9e685e29214082878e37a267157044618eTimo Sirainen * You can obtain a copy of the License at
ffa179f76a2b6f4ef97bd560f65fa9e3e35361b4Timo Sirainen * http://forgerock.org/license/CDDLv1.0.html
22535a9e685e29214082878e37a267157044618eTimo Sirainen * See the License for the specific language governing
22535a9e685e29214082878e37a267157044618eTimo Sirainen * permission and limitations under the License.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen *
345648b341f228bd7f0b89f8aa3ecb9c470d817eTimo Sirainen * When distributing Covered Code, include this CDDL
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * Header Notice in each file and include the License file
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * at http://forgerock.org/license/CDDLv1.0.html
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * If applicable, add the following below the CDDL Header,
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * with the fields enclosed by brackets [] replaced by
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * your own identifying information:
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen * "Portions Copyrighted [year] [name of copyright owner]"
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen */
22535a9e685e29214082878e37a267157044618eTimo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo SirainenSample 5b - "All-or-Nothing" Synchronization of Two Resources
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen-------------------------------------------------------------
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo SirainenThis sample demonstrates flowing data between external resources just as
22535a9e685e29214082878e37a267157044618eTimo Sirainenin the regular sample 5 on which it is based. It simulates two directory
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenresources using XML files. It extends sample 5 in that it configures a
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainencompensation script that attempts to ensure either all the synchronization
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenor none of the synchronization is performed after making a change to a
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenmanaged user.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
6a23f65e314ee81050a6077e46dfc956aafb09c7Timo SirainenWhenever a change is made to a managed/user resource, OpenIDM implicitly
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenattempts to synchronize external resources according to the object mapping
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenin sync.json where managed/user is the source. Typically, if the
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainensynchronization fails--owing to a policy validation for the target,
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenmissing required properties for the target, or simply that the target
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenis unavailable--the synchronization stops, leaving the managed/user
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenresource, and any targets that were synchronized before the failure,
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenupdated. The target that failed, and any targets specified
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenin mappings subsequent to the one that failed are not updated.
25757faf029c369a8318349dafe952e2358df1d8Timo SirainenThis situation would usually result in a set of systems that are out of
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainensync. The only way to re-synchronize them would be a reconciliation operation.
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo SirainenReconciliations can be expensive with large data sets.
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainen
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo SirainenOpenIDM 3.0 enhances synchronization to multiple targets by providing
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainensynchronization details to an "onSync" script, after successfully synchronizing
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainenall targets or failing one target. This script hook can be used to "revert"
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainenthe partial change to managed/user and the corresponding external resources
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenper the object mappings.
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainen
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo SirainenSample 5b includes a script that demonstrates compensating for a synchronization
0fda2dfa8c91818085202f278ab913cc9e9bf8f1Timo Sirainenfailure.
22535a9e685e29214082878e37a267157044618eTimo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo SirainenFor documentation pertaining to this example see:
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainenhttp://openidm.forgerock.org/doc/install-guide/index.html#more-sample5b
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo SirainenTo try the sample, follow these steps.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen Steps 1 and 2 are optional, and only necessary if you'd like to receive emailed
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen recon summaries.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen 1. Copy the samples/misc/external.email.json file into samples/sample5b/conf
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen $ cd /path/to/openidm
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen $ cp samples/misc/external.email.json samples/sample5b/conf
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen Edit this file to have your email server SMTP details.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen See http://openidm.forgerock.org/doc/integrators-guide/index.html#chap-mail
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen for more information.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen 2. Edit samples/sample5b/script/reconStats.js and change these values to your
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen own email addresses:
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen var params = {
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen //UPDATE THESE VALUES
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen from : "openidm@example.com",
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen to : "idmadmin1@example.com",
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen cc : "idmadmin2@example.com,idmadmin3@example.com",
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen subject : "Recon stats for " + source.name + " -> " + target.name,
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen type : "text/html"
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen }
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen 3. Start OpenIDM with the configuration for sample 5b.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen $ cd /path/to/openidm
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen $ ./startup.sh -p samples/sample5b
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen When you start OpenIDM, it creates data in the new external resource file
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen that represents an AD directory, samples/sample5b/data/xml_AD_Data.xml.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen The new file is empty until you run reconciliation.
25757faf029c369a8318349dafe952e2358df1d8Timo Sirainen
4. Run reconciliation.
$ curl -k -H "Content-type: application/json" -u "openidm-admin:openidm-admin" -X POST "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser"
{"reconId":"b149f0e3-4bb9-4790-9266-fab2e5c80ec6"}
5. Check
$ cat /path/to/openidm/samples/sample5b/data/xml_AD_Data.xml
<?xml version="1.0" encoding="UTF-8"?>
<icf:OpenICFContainer xmlns:icf="http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd"
xmlns:ri="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://openidm.forgerock.com/xml/ns/public/resource/instances/resource-schema-extension samples/sample5b/data/resource-schema-extension.xsd http://openidm.forgerock.com/xml/ns/public/resource/openicf/resource-schema-1.xsd samples/sample5b/data/resource-schema-1.xsd">
<ri:__ACCOUNT__>
<ri:firstname>Darth</ri:firstname>
<icf:__DESCRIPTION__/>
<icf:__GROUPS__/>
<icf:__UID__>68077c05-32ae-4438-b250-d23be784ea07</icf:__UID__>
<icf:__NAME__>DDOE1</icf:__NAME__>
<ri:email>mail1@example.com</ri:email>
<icf:__PASSWORD__>initial_Passw0rd</icf:__PASSWORD__>
<icf:__ENABLE__/>
<ri:lastname>Doe</ri:lastname>
</ri:__ACCOUNT__>
</icf:OpenICFContainer>
6. Create a new user in the source external resource file,
samples/sample5b/data/xml_LDAP_Data.xml, and run reconciliation again
to see the result show up in samples/sample5b/data/xml_AD_Data.xml.
7. Login to the UI at https://localhost:8443/openidmui. You can use
openidm-admin/openidm-admin for admin access or DDOE1/TestPassw0rd2 for
non-admin access. Updates to DDOE1 will be synced backed to both XML files.
8. Now make the LDAP xml file unavailable by renaming it so it is unreadable.
You may need to have root or sudo access to do this:
$ mv /path/to/openidm/samples/sample5b/data/xml_LDAP_Data.xml /path/to/openidm/samples/sample5b/data/xml_LDAP_Data.xml.bak
9. Perform an update to the DDOE1 user. It will be updated in managed/user,
the synchronization to AD will be successful, but the synchronization to
LDAP should fail. The compensate.js script will be invoked and will
attempt to revert the change by performing another update to DDOE1 in
managed/user, which will, in turn, perform the sync to AD and LDAP.
On the second time through, the sync will again fail to LDAP, which will
trigger the compensate.js again. The script this time will recognize
that the change was originally called from compensation and will abort.
The original sync error on the first update will be thrown from the
script and the UI should display an error.
Note that if you are making these updates from the UI, the UI screen does
not refresh after the failure. It will still show the "pending update"
that has not taken effect. Go back to the Users tab and start over and
you will see the old managed/user data has been restored. View the
xml_AD_Data.xml file and you will see that DDOE1 has also been reverted
to its condition prior to update.
10. If you have configured the recon email summary in steps 1 and 2, you
should have received an email that lists the details for the reconciliation.