Merge pull request #644 from mposolda/master

Docs about sync. Tooltips and minor fixes

docbook/reference/en/en-US/modules/user-federation.xml

@@ -101,7 +101,8 @@
                         <term>Other options</term>
                         <listitem>
                             <para>
-                                The rest of the configuration options should be self explanatory.
+                                The rest of the configuration options should be self explanatory. You can use tooltips in admin console
+                                to see some more details about them.
                             </para>
                         </listitem>
                     </varlistentry>
@@ -109,6 +110,46 @@
             </para>
         </section>
     </section>
+    <section>
+        <title>Sync of LDAP users to Keycloak</title>
+        <para>
+            LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into Keycloak database.
+            For example once you first authenticate LDAP user <literal>john</literal> from Keycloak UI, LDAP Federation provider will
+            first import this LDAP user into Keycloak database and then authenticate against LDAP password.
+        </para>
+        <para>
+            Thing is that Federation Provider import just requested users by default, so if you click to <literal>View all users</literal>
+            in Keycloak admin console, you will see just those LDAP users, which were already authenticated/requested by Keycloak.
+        </para>
+        <para>If you want to sync all LDAP users into Keycloak database, you may configure and enable Sync, which is in
+            admin console on same page like the configuration of Federation provider itself. There are 2 types of sync:
+            <variablelist>
+                <varlistentry>
+                    <term>Full sync</term>
+                    <listitem>
+                        <para>
+                            This will synchronize all LDAP users into Keycloak DB. Those LDAP users, which already exist in Keycloak and were
+                            changed in LDAP directly will be updated in Keycloak DB (For example if user <literal>Mary Kelly</literal> was changed in LDAP to <literal>Mary Doe</literal>).
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>Changed users sync</term>
+                    <listitem>
+                        <para>
+                            This will check LDAP and it will sync into Keycloak just those users, which were created or updated in LDAP from the time of last sync.
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </para>
+        <para>
+            In usual cases you may want to trigger full sync at the beginning, so you will import all LDAP users to Keycloak just once. Then you may setup
+            periodic sync of changed users, so Keycloak will periodically ask LDAP server for newly created or updated users and backport them to Keycloak DB.
+            Also you may want to trigger full sync again after some longer time or setup periodic full sync as well.
+        </para>
+        <para>In admin console, you can trigger sync directly or you can enable periodic changed or full sync.</para>
+    </section>
     <section>
         <title>Writing your own User Federation Provider</title>
         <para>

forms/common-themes/src/main/resources/theme/admin/base/resources/partials/federated-generic.html

@@ -32,12 +32,14 @@
                     <div class="col-sm-4">
                         <input class="form-control" id="consoleDisplayName" type="text" ng-model="instance.displayName" placeholder="defaults to id">
                     </div>
+                    <span tooltip-placement="right" tooltip="Display name of provider when linked in admin console." class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="priority">Priority </label>
                     <div class="col-sm-4">
                         <input class="form-control" id="priority" type="text" ng-model="instance.priority">
                     </div>
+                    <span tooltip-placement="right" tooltip="Priority of provider when doing a user lookup.  Lowest first." class="fa fa-info-circle"></span>
                 </div>
                 <div data-ng-repeat="option in providerFactory.options" class="form-group">
                     <label class="col-sm-2 control-label">{{option|capitalize}} </label>
@@ -56,24 +58,28 @@
                     <div class="col-sm-4">
                         <input ng-model="fullSyncEnabled" name="fullSyncEnabled" id="fullSyncEnabled" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Does periodic full synchronization of provider users to Keycloak should be enabled or not" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix" data-ng-show="fullSyncEnabled">
                     <label class="col-sm-2 control-label" for="fullSyncPeriod">Full sync period</label>
                     <div class="col-sm-4">
                         <input class="form-control" type="number" ng-model="instance.fullSyncPeriod" id="fullSyncPeriod" />
                     </div>
+                    <span tooltip-placement="right" tooltip="Period for full synchronization in seconds" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="changedSyncEnabled">Periodic changed users sync</label>
                     <div class="col-sm-4">
                         <input ng-model="changedSyncEnabled" name="changedSyncEnabled" id="changedSyncEnabled" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Does periodic synchronization of changed or newly created provider users to Keycloak should be enabled or not" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix" data-ng-show="changedSyncEnabled">
                     <label class="col-sm-2 control-label" for="changedSyncPeriod">Changed users sync period</label>
                     <div class="col-sm-4">
                         <input class="form-control" type="number" ng-model="instance.changedSyncPeriod" id="changedSyncPeriod" />
                     </div>
+                    <span tooltip-placement="right" tooltip="Period for synchronization of changed or newly created provider users in seconds" class="fa fa-info-circle"></span>
                 </div>
             </fieldset>
 

forms/common-themes/src/main/resources/theme/admin/base/resources/partials/federated-ldap.html

@@ -72,6 +72,7 @@
                             </select>
                         </div>
                     </div>
+                    <span tooltip-placement="right" tooltip="LDAP vendor (provider)" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="usernameLDAPAttribute">Username LDAP attribute </label>
@@ -83,18 +84,21 @@
                             </select>
                         </div>
                     </div>
+                    <span tooltip-placement="right" tooltip="Name of LDAP attribute, which is mapped as Keycloak username" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="userObjectClasses">User Object Classes </label>
                     <div class="col-sm-4">
                         <input class="form-control" id="userObjectClasses" type="text" ng-model="instance.config.userObjectClasses" placeholder="LDAP User Object Classes (div. by comma)">
                     </div>
+                    <span tooltip-placement="right" tooltip="All values of LDAP objectClass attribute divided by comma, which are used for newly created LDAP users" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="ldapConnectionUrl">Connection URL<span class="required">*</span></label>
                     <div class="col-sm-4">
                         <input class="form-control" id="ldapConnectionUrl" type="text" ng-model="instance.config.connectionUrl" placeholder="LDAP connection URL" required>
                     </div>
+                    <span tooltip-placement="right" tooltip="Connection URL to your LDAP server" class="fa fa-info-circle"></span>
                     <div class="col-sm-4" data-ng-show="access.manageRealm">
                         <a class="btn btn-primary" data-ng-click="testConnection()">Test connection</a>
                     </div>
@@ -104,24 +108,28 @@
                     <div class="col-sm-4">
                         <input class="form-control" id="ldapBaseDn" type="text" ng-model="instance.config.baseDn" placeholder="LDAP Base DN" required>
                     </div>
+                    <span tooltip-placement="right" tooltip="Base DN of LDAP tree where your data are. Base DN is usually ancestor of User DN Suffix" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="ldapUserDnSuffix">User DN Suffix <span class="required">*</span></label>
                     <div class="col-sm-4">
                         <input class="form-control" id="ldapUserDnSuffix" type="text" ng-model="instance.config.userDnSuffix" placeholder="LDAP User DN Suffix" required>
                     </div>
+                    <span tooltip-placement="right" tooltip="Base DN of LDAP tree where your users are. This DN is parent of all DNs of LDAP users" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="ldapBindDn">Bind DN <span class="required">*</span></label>
                     <div class="col-sm-4">
                         <input class="form-control" id="ldapBindDn" type="text" ng-model="instance.config.bindDn" placeholder="LDAP Bind DN" required>
                     </div>
+                    <span tooltip-placement="right" tooltip="DN of LDAP admin, which will be used by Keycloak to access LDAP server" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="ldapBindCredential">Bind Credential <span class="required">*</span></label>
                     <div class="col-sm-4">
                         <input class="form-control" id="ldapBindCredential" type="text" ng-model="instance.config.bindCredential" placeholder="LDAP Bind Credentials" required>
                     </div>
+                    <span tooltip-placement="right" tooltip="Password of LDAP admin" class="fa fa-info-circle"></span>
                     <div class="col-sm-4" data-ng-show="access.manageRealm">
                         <a class="btn btn-primary" data-ng-click="testAuthentication()">Test authentication</a>
                     </div>
@@ -131,6 +139,7 @@
                     <div class="col-sm-4">
                         <input ng-model="connectionPooling" name="connectionPooling" id="connectionPooling" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Does Keycloak should use connection pooling for accessing LDAP server" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="pagination">Pagination</label>
@@ -144,6 +153,8 @@
                     <div class="col-sm-4">
                         <input ng-model="userAccountControlsAfterPasswordUpdate" name="userAccountControlsAfterPasswordUpdate" id="userAccountControlsAfterPasswordUpdate" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Useful just for Active Directory. If enabled, then Keycloak will always set
+                    Active Directory userAccountControl attribute to 512 after password update. This would mean that particular user will be enabled in Active Directory" class="fa fa-info-circle"></span>
                 </div>
             </fieldset>
 
@@ -154,30 +165,35 @@
                     <div class="col-sm-4">
                         <input class="form-control" type="text" ng-model="instance.config.batchSizeForSync" id="batchSizeForSync" />
                     </div>
+                    <span tooltip-placement="right" tooltip="Count of LDAP users to be imported from LDAP to Keycloak within single transaction." class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="fullSyncEnabled">Periodic full sync</label>
                     <div class="col-sm-4">
                         <input ng-model="fullSyncEnabled" name="fullSyncEnabled" id="fullSyncEnabled" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Does periodic full synchronization of LDAP users to Keycloak should be enabled or not" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix" data-ng-show="fullSyncEnabled">
                     <label class="col-sm-2 control-label" for="fullSyncPeriod">Full sync period</label>
                     <div class="col-sm-4">
                         <input class="form-control" type="number" ng-model="instance.fullSyncPeriod" id="fullSyncPeriod" />
                     </div>
+                    <span tooltip-placement="right" tooltip="Period for full synchronization in seconds" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix">
                     <label class="col-sm-2 control-label" for="changedSyncEnabled">Periodic changed users sync</label>
                     <div class="col-sm-4">
                         <input ng-model="changedSyncEnabled" name="changedSyncEnabled" id="changedSyncEnabled" onoffswitch />
                     </div>
+                    <span tooltip-placement="right" tooltip="Does periodic synchronization of changed or newly created LDAP users to Keycloak should be enabled or not" class="fa fa-info-circle"></span>
                 </div>
                 <div class="form-group clearfix" data-ng-show="changedSyncEnabled">
                     <label class="col-sm-2 control-label" for="changedSyncPeriod">Changed users sync period</label>
                     <div class="col-sm-4">
                         <input class="form-control" type="number" ng-model="instance.changedSyncPeriod" id="changedSyncPeriod" />
                     </div>
+                    <span tooltip-placement="right" tooltip="Period for synchronization of changed or newly created LDAP users in seconds" class="fa fa-info-circle"></span>
                 </div>
             </fieldset>
 

services/src/main/java/org/keycloak/services/managers/UsersSyncManager.java

@@ -68,7 +68,7 @@ public class UsersSyncManager {
                     try {
                         syncAllUsers(sessionFactory, realmId, fedProvider);
                     } catch (Throwable t) {
-                        logger.error("Error occured during full sync of users", t);
+                        logger.error("Error occurred during full sync of users", t);
                     }
                 }
 
@@ -86,7 +86,7 @@ public class UsersSyncManager {
                     try {
                         syncChangedUsers(sessionFactory, realmId, fedProvider);
                     } catch (Throwable t) {
-                        logger.error("Error occured during sync of changed users", t);
+                        logger.error("Error occurred during sync of changed users", t);
                     }
                 }
 

testsuite/integration/src/test/java/org/keycloak/testsuite/forms/SyncProvidersTest.java

@@ -1,6 +1,5 @@
 package org.keycloak.testsuite.forms;
 
-import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -18,7 +17,6 @@ import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.KeycloakSessionFactory;
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.UserFederationProvider;
-import org.keycloak.models.UserFederationProviderFactory;
 import org.keycloak.models.UserFederationProviderModel;
 import org.keycloak.models.UserModel;
 import org.keycloak.models.UserProvider;