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