From 5b79e80bbfac20afd94510725b3e875f1aa74782 Mon Sep 17 00:00:00 2001
From: devnull- <fettprodj@hotmail.com>
Date: Thu, 16 Feb 2017 18:46:34 +0100
Subject: [PATCH] Clean & improve README.md of CertAuth

---
 app/Plugin/CertAuth/README.md | 81 +++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 27 deletions(-)

diff --git a/app/Plugin/CertAuth/README.md b/app/Plugin/CertAuth/README.md
index 69cffeb8a..9c4c268f8 100644
--- a/app/Plugin/CertAuth/README.md
+++ b/app/Plugin/CertAuth/README.md
@@ -4,7 +4,9 @@ This plugin enables CakePHP applications to use client SSL certificates to state
 
 Basically it loads the `SSL_CLIENT_*` variables, parses and maps the certificate information to the user. So you first need a server that checks client certificates and forwards that information to the PHP `$_SERVER` environment.
 
-## Usage
+## Configuration
+
+1. Enable the plugin
 
 Enable the plugin at bootstrap.php:
 
@@ -12,34 +14,59 @@ Enable the plugin at bootstrap.php:
 CakePlugin::load('CertAuth');
 ```
 
-And configure it:
+2. Configure
+
+* Uncomment the line "'auth'=>array('CertAuth.Certificate')," in Config.php, section "Security"
 
 ```php
-Configure::write('CertAuth',
-  array(
-    'ca'    => array( 'FIRST.Org' ), // allowed CAs
-    'caId'          => 'O',          // which attribute will be used to verify the CA
-    'userModel'     => 'User',       // name of the User class to check if user exists
-    'userModelKey'  => 'nids_sid',   // User field that will be used for querying
-    'map'           => array(        // maps client certificate attributes to User properties
-      'O'           => 'org',
-      'emailAddress'=>'email',
-    ),
-    'syncUser'      => true,         // should the User be synchronized with an external REST API
-    'restApi'       => array(        // API parameters
-      'url'         => 'https://example.com/data/users',  // URL to query
-      'headers'     => array(),                           // additional headers, used for authentication
-      'param'       => array( 'email' => 'email'),        // query parameters to add to the URL, mapped to USer properties
-      'map'         =>  array(                            // maps REST result to the User properties
-        'uid'       => 'id',
-        'name'      => 'name',
-        'company'   => 'org',
-        'email'     => 'email',
-      ),
-    ),
-    'userDefaults'  => array ( 'role_id' => 3 ),          // default attributes for new users
-  )
-);
+    ....
+	'Security'         =>
+		array(
+			'level'      => 'medium',
+			'salt'       => '',
+			'cipherSeed' => '',
+		    'auth'=>array('CertAuth.Certificate'), // additional authentication methods
+			//'auth'=>array('ShibbAuth.ApacheShibb'dd),
+		),
+    .....
+```
+
+* Uncomment the following lines in Config.php, section "CertAuth" and configure them.
+
+```php
+	'CertAuth'         =>
+        array(
+
+            // CA
+            'ca'           => array('FIRST.Org'), // List of CAs authorized
+            'caId'         => 'O',          // Certificate field used to verify the CA. In this example, the field O (organization) of the client certificate has to equal to 'FIRST.Org' in order to validate the CA
+
+            // User/client configuration
+			'userModel'    => 'User',       // name of the User class (MISP class) to check if the user exists
+            'userModelKey' => 'email',      // User field that will be used for querying. In this example, the field email of the MISP accounts will be used to search if the user exists.
+            'map'          => array(        // maps client certificate attributes to User properties. This map will be used as conditions to find if the user exists. In this example, the client certificate fields 'O' (organization) and 'emailAddress' have to match with the MISP fields 'org' and 'email' to validate the user.
+				'O'            => 'org',
+				'emailAddress' => 'email',
+            ),
+
+            // Synchronization/RestAPI
+			'syncUser'     => true,         // should the User be synchronized with an external REST API
+			'userDefaults' => array(          // default user attributes, only used when creating new users. By default, new users are "Read only" users (role_id: 6).
+				'role_id' => 6,
+            ),
+			'restApi'      => array(        // API parameters
+				'url'     => 'https://example.com/data/users',  // URL to query
+				'headers' => array(),                           // additional headers, used for authentication
+				'param'   => array('email' => 'email'),       // query parameters to add to the URL, mapped to User properties
+				'map'     => array(                            // maps REST result to the User properties
+					'uid'        => 'nids_sid',
+					'team'       => 'org',
+					'email'      => 'email',
+					'pgp_public' => 'gpgkey',
+				),
+			),
+			'userDefaults' => array('role_id' => 6),          // default attributes for new users. By default, new users are "Read only" users (role_id: 6).
+		),
 ```
 
 If you set *syncUser* to *true* and *restApi.url* to *null*, new users will be created with the defaults defined by *userDefaults* without the need for a REST server.