docs for OAuth

TODO.txt

@@ -21,3 +21,4 @@
 - (TODO) Fix, changed menu item "User's Statistics" to "User Statistics".
 - (TODO) Fix, changed menu item "Permission on Views/Menus" to "Permissions on Views/Menus".
 - (TODO) Fix, Relation/No Relation filter labels changed to Only/All But.
+- (TODO) Fix, OpenID Code rework.

babel/messages.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PROJECT VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2015-05-25 17:50+0100\n"
+"POT-Creation-Date: 2015-06-03 14:38+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -237,37 +237,37 @@ msgstr ""
 msgid "Email"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:363
+#: flask_appbuilder/security/manager.py:406
 #: flask_appbuilder/security/views.py:95
 msgid "List Users"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:365
+#: flask_appbuilder/security/manager.py:408
 msgid "Security"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:368
+#: flask_appbuilder/security/manager.py:411
 #: flask_appbuilder/security/views.py:293
 msgid "List Roles"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:374
+#: flask_appbuilder/security/manager.py:417
 msgid "User's Statistics"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:380
+#: flask_appbuilder/security/manager.py:423
 msgid "User Registrations"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:386
+#: flask_appbuilder/security/manager.py:429
 msgid "Base Permissions"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:389
+#: flask_appbuilder/security/manager.py:432
 msgid "Views/Menus"
 msgstr ""
 
-#: flask_appbuilder/security/manager.py:392
+#: flask_appbuilder/security/manager.py:435
 msgid "Permission on Views/Menus"
 msgstr ""
 
@@ -523,11 +523,15 @@ msgstr ""
 msgid "Sign In"
 msgstr ""
 
-#: flask_appbuilder/templates/appbuilder/baselib.html:110
+#: flask_appbuilder/templates/appbuilder/baselib.html:115
+msgid "Profile"
+msgstr ""
+
+#: flask_appbuilder/templates/appbuilder/baselib.html:116
 msgid "Logout"
 msgstr ""
 
-#: flask_appbuilder/templates/appbuilder/baselib.html:115
+#: flask_appbuilder/templates/appbuilder/baselib.html:122
 msgid "Login"
 msgstr ""
 

docs/_build/html/_sources/intro.txt

@@ -34,7 +34,7 @@ Includes:
       - Inserts on the Database all the detailed permissions possible on your application.
       - Public (no authentication needed) and Private permissions.
       - Role based permissions.
-      - Authentication support for OpenID, Database, LDAP and REMOTE_USER environ var.
+      - Authentication support for OAuth, OpenID, Database, LDAP and REMOTE_USER environ var.
       - Support for self user registration.
   - Views and Widgets
       - Automatic menu generation.

docs/_build/html/_sources/security.txt

@@ -12,6 +12,7 @@ You have four types of authentication methods
 :REMOTE_USER: Reads the *REMOTE_USER* web server environ var, and verifies if it's authorized with the framework users table.
        It's the web server responsibility to authenticate the user, useful for intranet sites, when the server (Apache, Nginx)
        is configured to use kerberos, no need for the user to login with username and password on F.A.B.
+:OAUTH: Authentication using OAUTH (v1 or v2). You need to install flask-oauthlib.
 
 Configure the authentication type on config.py, take a look at :doc:`config`
 
@@ -140,6 +141,150 @@ exclude them from add and edit form. Using our example you will define our view
         add_columns = ['name']
         edit_columns = ['name']
 
+Authentication Methods
+----------------------
+
+We are now looking at the authentication methods, and how you can configure them and customize them.
+The framework as 5 authentication methods and you choose one of them, you configure the method to be used
+on the **config.py** (when using the create-app, or following the propused app structure). First the
+configuration imports the constants for the authentication methods::
+
+    from flask_appbuilder.security.manager import AUTH_OID, \ 
+                                              AUTH_REMOTE_USER, \ 
+                                              AUTH_DB, AUTH_LDAP, \ 
+                                              AUTH_OAUTH, \
+                                              AUTH_OAUTH
+
+Next you will use the **AUTH_TYPE** key to choose the type::
+
+    AUTH_TYPE = AUTH_DB
+
+Additionally you can customize the name of the builtin roles for Admin and Public accesses::
+
+    AUTH_ROLE_ADMIN = 'My Admin Role Name'
+    AUTH_ROLE_PUBLIC = 'My Public Role Name'
+
+Finally you can allow users to self register (take a look at the following chapters for further detail)::
+
+    AUTH_USER_REGISTRATION = True
+    AUTH_USER_REGISTRATION_ROLE = "My Public Role Name"
+
+These settings can apply to all the authentication methods. When you create your first admin user
+using **fabmanager** command line, this user will be authenticated using the authentication method
+defined on your **config.py**.
+
+Authentication: Database
+------------------------
+
+The database authentication type is the most *simple* one, it authenticates users against an
+username and hashed password field kept on your database.
+
+Administrators can create users with passwords, and users can change their passwords. This is all done using the UI.
+(You can override and extend the default UI as we'll see on *Your Custom Security*)
+
+Authentication: OpenID
+----------------------
+
+This authentication method uses `Flask-OpenID <https://github.com/mitsuhiko/flask-openid>`_. All configuration is done
+on **config.py** using OPENID_PROVIDERS key, just add or remove from the list the providers you want to enable::
+
+    AUTH_TYPE = AUTH_OID
+    OPENID_PROVIDERS = [
+        { 'name': 'Yahoo', 'url': 'https://me.yahoo.com' },
+        { 'name': 'AOL', 'url': 'http://openid.aol.com/<username>' },
+        { 'name': 'Flickr', 'url': 'http://www.flickr.com/<username>' },
+        { 'name': 'MyOpenID', 'url': 'https://www.myopenid.com' }]
+
+Each list entry is a dict with a readable OpenID name and it's url, if the url needs an username just add it using <username>.
+The login template for this method will provide a text box for the user to fillout his/her username.
+
+F.A.B. will ask for the 'email' from OpenID, and if this email belongs to some user on your application he/she will login successfully.
+
+Authentication: LDAP
+--------------------
+
+This method will authenticate the user's credentials against an LDAP server. Using this method without self user registration
+is very simple, just define the LDAP server::
+
+    AUTH_TYPE = AUTH_LDAP
+    AUTH_LDAP_SERVER = "ldap://ldapserver.local"
+
+Authentication: OAuth
+---------------------
+
+By using this method it will be possible to use the provider API, this is because your requesting the user to give
+permission to your app to access or manage the user's account on the provider.
+
+So you can send tweets, post on the users facebook, retrieve the user's linkedin profile etc.
+
+To use OAuth you need to install `Flask-OAuthLib <https://flask-oauthlib.readthedocs.org/en/latest/>`_. It's usefull
+to get to know this library since F.A.B. will expose the remote application object for you to play with.
+
+Take a look at the `example <https://github.com/dpgaspar/Flask-AppBuilder/tree/master/examples/oauth>`_ 
+to get an idea of a simple use for this.
+
+Use **config.py** configure OAUTH_PROVIDERS with a list of oauth providers, notice that the remote_app
+key is just the configuration for flask-oauthlib::
+
+    AUTH_TYPE = AUTH_OAUTH
+
+    OAUTH_PROVIDERS = [
+        {'name':'twitter', 'icon':'fa-twitter',
+            'remote_app': {
+                'consumer_key':'TWITTER KEY',
+                'consumer_secret':'TWITTER SECRET',
+                'base_url':'https://api.twitter.com/1.1/',
+                'request_token_url':'https://api.twitter.com/oauth/request_token',
+                'access_token_url':'https://api.twitter.com/oauth/access_token',
+                'authorize_url':'https://api.twitter.com/oauth/authenticate'}
+        },
+        {'name':'google', 'icon':'fa-google', 'token_key':'access_token',
+            'remote_app': {
+                'consumer_key':'GOOGLE KEY',
+                'consumer_secret':'GOOGLE SECRET',
+                'base_url':'https://www.googleapis.com/plus/v1/',
+                'request_token_params':{
+                  'scope': 'https://www.googleapis.com/auth/userinfo.email'
+                },
+                'request_token_url':None,
+                'access_token_url':'https://accounts.google.com/o/oauth2/token',
+                'authorize_url':'https://accounts.google.com/o/oauth2/auth'}
+        }
+    ]
+
+This needs a small explanation, you basically have five special keys:
+
+:name: The name of the provider, you can choose whatever you want. But the framework as some 
+    builtin logic to retrieve information about a user that you can make use of if you choose:
+    'twitter', 'google', 'github','linkedin'.
+
+:icon: The font-awesome icon for this provider.
+:token_key: The token key name that this provider uses, google and github uses *'access_token'*,
+    twitter uses *'oauth_token'* and thats the default.
+:token_secret: The token secret key name, default is *'oauth_token_secret'*
+
+After the user authenticates and grants access permissions to your application
+the framework retrieves information about the user, username and email. This info
+will be checked with the internal user (user record on User Model), first by username next by email.
+
+To override/customize the user information retrieval from oauth, you can create your own method like this::
+
+    @appbuilder.sm.oauth_user_info_getter
+    def my_user_info_getter(sm, provider, response=None):
+        if provider == 'github':
+            me = sm.oauth_remotes[provider].get('user')
+            return {'username': me.data.get('login')}
+        else:
+            return {}
+
+Decorate your method with the SecurityManager **oauth_user_info_getter** decorator.
+Make your method accept the exact parameters as on this example, and then return a dictionary 
+with the retrieved user information. The dictionary keys must have the same column names as the User Model.
+Your method will be called after the user authorizes your application on the OAuth provider, and it will
+receive the following: **sm** is F.A.B's SecurityManager class, **provider** is a string with the name you configured 
+this provider with, **response** is the response.
+
+Take a look at the `example <https://github.com/dpgaspar/Flask-AppBuilder/tree/master/examples/oauth>`_
 
 Your Custom Security
 --------------------
@@ -209,6 +354,7 @@ If your using:
 - AUTH_LDAP extend UserLDAPModelView
 - AUTH_REMOTE_USER extend UserRemoteUserModelView
 - AUTH_OID extend UserOIDModelView
+- AUTH_OAUTH extend UserOAuthModelView
 
 ::
 

docs/_build/html/_sources/versions.txt

@@ -11,17 +11,16 @@ Improvements and Bug fixes on 1.4.0
 - New, class method for BaseView's get_default_url, returns the default_view url.
 - New, OAuth authentication method.
 - New, Search for role with a particular set of permissions on views or menus.
-+ TODO, add_exclude_columns
-+ TODO, edit_exclude_columns
-+ TODO, show_exclude_columns
-+ TODO, exclude_columns on tests.
-+ TODO, docs for exclude_columns
-- TODO, remove id warning for MongoDB on filters.
-- TODO, docs for OAUTH.
-- TODO, better docs for LDAP.
-- TODO, finish translations.
-- TODO, example for OAUTH.
-- TODO, self register OpenID code rework.
+- New, Possible to filter MongoEngine ObjectId's.
+- Fix, MongoEngine (MongoDB) ObjectId's not included in search forms.
+- Fix, Menu html and icons rework.
+- New, add_exclude_columns
+- New, edit_exclude_columns
+- New, show_exclude_columns
+- New, exclude_columns on tests.
+- New, docs for exclude_columns
+- New, remove id warning for MongoDB on filters.
+- Fix, missing translations.
 
 Improvements and Bug fixes on 1.3.7
 -----------------------------------

docs/_build/html/_sources/views.txt

@@ -221,7 +221,7 @@ or something.
 
         def form_post(self, form):
             # post process form
-            flash(as_unicode(self.message), 'info')
+            flash(self.message, 'info')
 
     appbuilder.add_view(MyFormView, "My form View", icon="fa-group", label=_('My form View'),
                          category="My Forms", category_icon="fa-cogs")

docs/_build/html/api.html

@@ -1567,16 +1567,16 @@ <h3>BaseSecurityManager<a class="headerlink" href="#basesecuritymanager" title="
 </dd></dl>
 
 <dl class="method">
-<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_key">
-<code class="descname">get_oauth_token_key</code><span class="sig-paren">(</span><em>provider</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.get_oauth_token_key"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_key" title="Permalink to this definition">¶</a></dt>
+<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_key_name">
+<code class="descname">get_oauth_token_key_name</code><span class="sig-paren">(</span><em>provider</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.get_oauth_token_key_name"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_key_name" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns the token_key name for the oauth provider
 if none is configured defaults to oauth_token
 this is configured using OAUTH_PROVIDERS and token_key key.</p>
 </dd></dl>
 
 <dl class="method">
-<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_secret">
-<code class="descname">get_oauth_token_secret</code><span class="sig-paren">(</span><em>provider</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.get_oauth_token_secret"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_secret" title="Permalink to this definition">¶</a></dt>
+<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_secret_name">
+<code class="descname">get_oauth_token_secret_name</code><span class="sig-paren">(</span><em>provider</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.get_oauth_token_secret_name"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.get_oauth_token_secret_name" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns the token_secret name for the oauth provider
 if none is configured defaults to oauth_secret
 this is configured using OAUTH_PROVIDERS and token_secret</p>
@@ -1643,6 +1643,26 @@ <h3>BaseSecurityManager<a class="headerlink" href="#basesecuritymanager" title="
 <dd><p>OAuth tokengetter function override to implement your own tokengetter method</p>
 </dd></dl>
 
+<dl class="method">
+<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.oauth_user_info_getter">
+<code class="descname">oauth_user_info_getter</code><span class="sig-paren">(</span><em>f</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.oauth_user_info_getter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.oauth_user_info_getter" title="Permalink to this definition">¶</a></dt>
+<dd><p>Decorator function to be the OAuth user info getter
+for all the providers, receives provider and response 
+return a dict with the information returned from the provider.
+The returned user info dict should have it&#8217;s keys with the same
+name as the User Model.</p>
+<p>Use it like this an example for GitHub</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="nd">@appbuilder.sm.oauth_user_info_getter</span>
+<span class="k">def</span> <span class="nf">my_oauth_user_info</span><span class="p">(</span><span class="n">sm</span><span class="p">,</span> <span class="n">provider</span><span class="p">,</span> <span class="n">response</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
+    <span class="k">if</span> <span class="n">provider</span> <span class="o">==</span> <span class="s">&#39;github&#39;</span><span class="p">:</span>
+        <span class="n">me</span> <span class="o">=</span> <span class="n">sm</span><span class="o">.</span><span class="n">oauth_remotes</span><span class="p">[</span><span class="n">provider</span><span class="p">]</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;user&#39;</span><span class="p">)</span>
+        <span class="k">return</span> <span class="p">{</span><span class="s">&#39;username&#39;</span><span class="p">:</span> <span class="n">me</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;login&#39;</span><span class="p">)}</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="k">return</span> <span class="p">{}</span>
+</pre></div>
+</div>
+</dd></dl>
+
 <dl class="attribute">
 <dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.oid">
 <code class="descname">oid</code><em class="property"> = None</em><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.oid" title="Permalink to this definition">¶</a></dt>
@@ -1751,6 +1771,12 @@ <h3>BaseSecurityManager<a class="headerlink" href="#basesecuritymanager" title="
 </table>
 </dd></dl>
 
+<dl class="method">
+<dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.set_oauth_session">
+<code class="descname">set_oauth_session</code><span class="sig-paren">(</span><em>provider</em>, <em>oauth_response</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.set_oauth_session"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.set_oauth_session" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set the current session with OAuth user secrets</p>
+</dd></dl>
+
 <dl class="method">
 <dt id="flask.ext.appbuilder.security.manager.BaseSecurityManager.update_user">
 <code class="descname">update_user</code><span class="sig-paren">(</span><em>user</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/flask_appbuilder/security/manager.html#BaseSecurityManager.update_user"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#flask.ext.appbuilder.security.manager.BaseSecurityManager.update_user" title="Permalink to this definition">¶</a></dt>