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