JMESPath documentation

docs/config.rst

@@ -34,6 +34,13 @@ Use config.py to configure the following parameters. By default it will use SQLL
 |                                        | exist. Mandatory when using user           |           |
 |                                        | registration                               |           |
 +----------------------------------------+--------------------------------------------+-----------+
+| AUTH_USER_REGISTRATION_ROLE_JMESPATH   | The `JMESPath <http://jmespath.org/>`_     |   No      |
+|                                        | expression used to evaluate user role on   |           |
+|                                        | registration. If set, takes precedence     |           |
+|                                        | over ``AUTH_USER_REGISTRATION_ROLE``.      |           |
+|                                        | Requires ``jmespath`` to be installed.     |           |
+|                                        | See :ref:`jmespath-examples` for examples  |           |
++----------------------------------------+--------------------------------------------+-----------+
 | AUTH_LDAP_SERVER                       | define your ldap server when AUTH_TYPE=2   |   Cond.   |
 |                                        | example:                                   |           |
 |                                        |                                            |           |
@@ -261,3 +268,25 @@ Next you only have to import them to the Flask app object, like this
     app.config.from_object('config')
 
 Take a look at the skeleton `config.py <https://github.com/dpgaspar/Flask-AppBuilder-Skeleton/blob/master/config.py>`_
+
+
+.. _jmespath-examples:
+
+Using JMESPath to map user registration role
+--------------------------------------------
+
+If user self registration is enabled and ``AUTH_USER_REGISTRATION_ROLE_JMESPATH`` is set, it is 
+used as a `JMESPath <http://jmespath.org/>`_ expression to evalate user registration role. The input
+values is ``userinfo`` dict, returned by ``get_oauth_user_info`` function of Security Manager.
+Usage of JMESPath expressions requires `jmespath <https://pypi.org/project/jmespath/>`_ package 
+to be installed.
+
+In case of Google OAuth, userinfo contains user's email that can be used to map some users as admins
+and rest of the domain users as read only users. For example, this expression:
+``contains(['user1@domain.com', 'user2@domain.com'], email) && 'Admin' || 'Viewer'``
+causes users 1 and 2 to be registered with role ``Admin`` and rest with the role ``Viewer``.
+
+JMESPath expression allow more groups to be evaluated:
+``email == 'user1@domain.com' && 'Admin' || (email == 'user2@domain.com' && 'Op' || 'Viewer')``
+
+For more example, see `specification <https://jmespath.org/specification.html>`_.

examples/oauth/config.py

@@ -98,7 +98,7 @@
 AUTH_USER_REGISTRATION_ROLE = "Admin"
 
 # Self registration role based on user info
-AUTH_USER_REGISTRATION_ROLE_JMESPATH = "contains(['alice', 'celine'], username) && 'Admin' || 'Public'"
+AUTH_USER_REGISTRATION_ROLE_JMESPATH = "contains(['alice@example.com', 'celine@example.com'], email) && 'Admin' || 'Public'"
 
 # When using LDAP Auth, setup the ldap server
 # AUTH_LDAP_SERVER = "ldap://ldapserver.new"

flask_appbuilder/security/manager.py

@@ -349,7 +349,7 @@ def auth_user_registration_role(self):
         return self.appbuilder.get_app.config["AUTH_USER_REGISTRATION_ROLE"]
 
     @property
-    def auth_user_registration_role_jmespath(self):
+    def auth_user_registration_role_jmespath(self) -> str:
         return self.appbuilder.get_app.config["AUTH_USER_REGISTRATION_ROLE_JMESPATH"]
 
     @property

requirements-dev.txt

@@ -14,3 +14,4 @@ mysqlclient>=1.4.2, < 2.0.0
 cython==0.29.17
 pymssql==2.1.4
 black==19.3b0
+jmespath==0.9.5

requirements.txt

@@ -22,7 +22,6 @@ flask==1.1.1
 idna==2.9                 # via email-validator
 itsdangerous==1.1.0       # via flask
 jinja2==2.10.1            # via flask, flask-babel
-jmespath==0.9.5
 jsonschema==3.0.1
 markupsafe==1.1.1         # via jinja2
 marshmallow-enum==1.5.1

setup.py

@@ -65,6 +65,7 @@ def desc():
         "PyJWT>=1.7.1",
         "sqlalchemy-utils>=0.32.21, <1",
     ],
+    extras_require={"jmespath": ["jmespath>=0.9.5"]},
     tests_require=["nose>=1.0", "mockldap>=0.3.0"],
     classifiers=[
         "Development Status :: 5 - Production/Stable",