From ee2974c8bedee52551a31b803f222df697b0c1fb Mon Sep 17 00:00:00 2001
From: Joel Bout <joel.bout@taotesting.com>
Date: Wed, 23 Dec 2015 17:35:12 +0100
Subject: [PATCH] added mapping examples and explanations

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/README.md b/README.md
index a7fb666..18c89b1 100644
--- a/README.md
+++ b/README.md
@@ -55,3 +55,59 @@ here the domain is test.com All the parameters are in a separate dc in ldap
 These are the configuration of the connection to the ldap server. 
 
 Then the login will try to use this library. 
+
+Configuration
+============================
+
+By default and LDAP user will be considered a test-taker belonging to no group.
+
+The following attributes will be taken from LDAP and mapped to TAO properties by default:
+
+* 'mail' as PROPERTY_USER_MAIL
+* 'givenName' as PROPERTY_USER_FIRSTNAME
+* 'sn' as PROPERTY_USER_LASTNAME
+* 'displayName' as RDFS_LABEL
+
+However there are several ways to enhance or override this default behaviour:
+
+------------------------------
+
+To hardcode one of the user properties, you would need to add a mapping of the type 'value' to the configuration:
+
+    array(
+        'driver' => 'oat\authLdap\model\LdapAdapter',
+        'config' => SEE_ABOVE
+        'mapping' => array(
+            'http://www.tao.lu/Ontologies/TAOGroup.rdf#member' => array(
+                'type' => 'value',
+                'value' => array('http://localnamespace.com/install#i123456789')
+            )
+        );
+    ),
+
+This example would set the group membership of all users loging in to a group identified by the id http://localnamespace.com/install#i123456789
+    
+------------------------------
+
+Alternatively if you want to take over a value of an LDAP attribute you would add a mapping of type 'attributeValue'
+
+    array(
+        'driver' => 'oat\authLdap\model\LdapAdapter',
+        'config' => SEE_ABOVE
+        'mapping' => array(
+            'http://www.tao.lu/Ontologies/TAOGroup.rdf#member' => array(
+                'type' => 'value',
+                'value' => array('http://localnamespace.com/install#i123456789')
+            ),
+            'http://www.w3.org/2000/01/rdf-schema#label' => array(
+                'type' => 'attributeValue',
+                'attribute' => 'username'
+            )
+        );
+    ),
+    
+This would use the value of the LDAP attribute 'username' as label for the user.
+
+------------------------------
+
+For more advanced cases there is the type 'callback' which allows you to programmatically enhance the mapping of the LDAP attributes to the TAO properties. See oat\authLdap\model\LdapUserFactory for details.