From 4063754e12340b86d44c21ffa8fea5a43c890c47 Mon Sep 17 00:00:00 2001
From: Matthew Scragg <scragg@gmail.com>
Date: Sun, 22 Nov 2015 11:19:11 -0600
Subject: [PATCH] update readme

---
 README.md                           | 67 ++++++++++++++++++++++++++++-
 realms/modules/auth/ldap/forms.py   |  2 +-
 realms/modules/auth/ldap/models.py  |  2 +
 realms/modules/auth/ldap/views.py   |  1 +
 realms/modules/auth/oauth/models.py |  1 +
 realms/modules/search/views.py      |  2 +-
 6 files changed, 72 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index afa19d0..4fb4e8e 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ You may want to customize your app and the easiest way is the setup command:
 
     realms-wiki setup
     
-This will ask you questions and create a `realms-wiki.json` file in where you can find it.
+This will ask you questions and create a `realms-wiki.json` file.
 You can manually edit this file as well.
 Any config value set in `realms-wiki.json` will override values set in `realms/config/__init__.py`.
 
@@ -273,6 +273,71 @@ WHOOSH_INDEX has to be a path readable and writeable by Realm's user. It will be
 Whoosh is set up to use language optimization, so set WHOOSH_LANGUAGE to the language used in your wiki. For available languages, check `whoosh.lang.languages`.
 If your language is not supported, Realms will fall back to a simple text analyzer.
 
+## Authentication
+
+### Local
+
+Local default will be done using a backend database as defined in the config.
+
+### LDAP (beta)
+
+Realms uses the following library to authenticate using LDAP.  https://github.com/ContinuumIO/flask-ldap-login
+It supports direct bind and bind by search. 
+Use these examples as a guide and place it in your realms-wiki.json config.
+
+
+#### Bind By Search Example
+
+In this example, BIND_DN and BIND_AUTH are used to search and authenticate.  Leaving them blank implies anonymous authentication.
+
+```
+"LDAP": {
+    "URI": "ldap://localhost:8389",
+    "BIND_DN": "",
+    "BIND_AUTH": "",
+    "USER_SEARCH": {"base": "dc=realms,dc=io", "filter": "uid=%(username)s"},
+    "KEY_MAP": {
+        "username":"cn",
+        "email": "mail"
+    }
+}
+```
+
+#### Direct Bind Example
+
+```
+"LDAP": {
+    "URI": "ldap://localhost:8389",
+    "BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
+    "KEY_MAP": {
+        "username":"cn",
+        "email": "mail",
+    },
+    "OPTIONS": {
+        "OPT_PROTOCOL_VERSION": 3,
+    }
+}
+```
+
+### OAuth (beta)
+
+Realms currently supports Github, Twitter, Facebook and Google.  Each provider requires a key and secret.
+Put them in your `realms-wiki.json` config file.  Use the example below.
+
+```
+"OAUTH": {
+    "twitter": {
+        "key": "",
+        "secret": ""
+    },
+    "github": {
+        "key": "",
+        "secret": ""
+    }
+}
+```
+
+
 ## Running
 
     realms-wiki start
diff --git a/realms/modules/auth/ldap/forms.py b/realms/modules/auth/ldap/forms.py
index ddbc54c..71dd215 100644
--- a/realms/modules/auth/ldap/forms.py
+++ b/realms/modules/auth/ldap/forms.py
@@ -3,5 +3,5 @@ from wtforms import StringField, PasswordField, validators
 
 
 class LoginForm(Form):
-    email = StringField('Email', [validators.DataRequired()])
+    login = StringField('Username', [validators.DataRequired()])
     password = PasswordField('Password', [validators.DataRequired()])
\ No newline at end of file
diff --git a/realms/modules/auth/ldap/models.py b/realms/modules/auth/ldap/models.py
index 269512d..0d97ef2 100644
--- a/realms/modules/auth/ldap/models.py
+++ b/realms/modules/auth/ldap/models.py
@@ -7,12 +7,14 @@ from ..models import BaseUser
 
 users = {}
 
+
 @ldap.save_user
 def save_user(username, userdata):
     user = User(userdata.get('username'), userdata.get('email'))
     users[user.id] = user
     return user
 
+
 class User(BaseUser):
     type = 'ldap'
 
diff --git a/realms/modules/auth/ldap/views.py b/realms/modules/auth/ldap/views.py
index ccb0414..7ab82f4 100644
--- a/realms/modules/auth/ldap/views.py
+++ b/realms/modules/auth/ldap/views.py
@@ -4,6 +4,7 @@ from flask_ldap_login import LDAPLoginForm
 
 blueprint = Blueprint('auth.ldap', __name__)
 
+
 @blueprint.route("/login/ldap", methods=['POST'])
 def login():
     form = LDAPLoginForm()
diff --git a/realms/modules/auth/oauth/models.py b/realms/modules/auth/oauth/models.py
index 8320293..72de533 100644
--- a/realms/modules/auth/oauth/models.py
+++ b/realms/modules/auth/oauth/models.py
@@ -82,6 +82,7 @@ providers = {
     }
 }
 
+
 class User(BaseUser):
     type = 'oauth'
     provider = None
diff --git a/realms/modules/search/views.py b/realms/modules/search/views.py
index d462348..f94d27e 100644
--- a/realms/modules/search/views.py
+++ b/realms/modules/search/views.py
@@ -1,4 +1,4 @@
-from flask import abort, g, render_template, request, redirect, Blueprint, flash, url_for, current_app
+from flask import render_template, request, Blueprint
 from realms import search as search_engine
 
 blueprint = Blueprint('search', __name__)