Flask plugin (#17)

* Flask plugin init commit

Author: rszalski

plugins/flask_yoti/LICENSE

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include flask_yoti/templates *.html
+recursive-include example/templates *.html

plugins/flask_yoti/MANIFEST.in

@@ -0,0 +1,151 @@
+# Flask Yoti #
+
+## Plugin configuration ##
+### General settings ###
+
+* `flask_yoti` is a [Flask Blueprint](http://flask.pocoo.org/docs/0.11/blueprints/) 
+and all you have to do to add it to your Flask app is register it like this:
+```python
+# your_flask_project/app.py
+from flask import Flask
+from flask_yoti import flask_yoti_blueprint
+
+app = Flask(__name__)
+app.register_blueprint(flask_yoti_blueprint, url_prefix='/yoti')
+```
+*Don't forget to set an `app.secret_key` to be able to use `sessions`*
+
+* And then use the following settings to configure the plugin:
+
+
+```python
+# your_flask_project/app.py
+ 
+...
+ 
+app.config.update({
+    'YOTI_APPLICATION_ID': '...',
+    'YOTI_CLIENT_SDK_ID': '...',
+    'YOTI_KEY_FILE_PATH': '...',
+    'YOTI_VERIFICATION_KEY': '...',
+    ...
+})
+```
+* **`YOTI_APPLICATION_ID`** - **required**, *can be also set by env variable with the same name*<br>
+Your Yoti application's ID, found under the `INTEGRATIONS` tab of your 
+Yoti application's settings page ([Yoti Dashboard](https://www.yoti.com/dashboard/)).<br>
+It is used to configure the [Yoti Login Button](https://www.yoti.com/developers/#login-button-setup).<br>
+Example: `ca84f68b-1b48-458b-96bf-963868edc8b6`
+
+* **`YOTI_CLIENT_SDK_ID`** - **required**, *can be also set by env variable with the same name*<br>
+Your Yoti application's SDK ID, found under the `INTEGRATIONS` tab of your 
+Yoti application's settings page ([Yoti Dashboard](https://www.yoti.com/dashboard/)).<br>
+Example: `39aef70a-89d6-4644-a687-b3e891613da6`
+
+* **`YOTI_KEY_FILE_PATH`** - **required**, *can be also set by env variable with the same name*<br>
+The full path to your private key downloaded from your Yoti application's 
+settings page under the `KEYS` tab ([Yoti Dashboard](https://www.yoti.com/dashboard/)).<br>
+Example: `/home/user/.ssh/access-security.pem`
+
+* **`YOTI_VERIFICATION_KEY`** - *can be also set by env variable with the same name*<br>
+A key, used to verify your callback URL. Can be found under the 
+`INTEGRATIONS` tab of your Yoti application's settings page (Callback URL -> VERIFY).<br>
+Example: `b14886f972d0c717`
+
+
+### Endpoints configuration ###
+
+`flask_yoti` plugin provides some default endpoints:
+- `yoti_auth` (`/yoti/auth`) - is a callback used for receiving an 
+authentication token (shouldn't be changed)
+- `yoti_login` (`/yoti/login`) - a view with just a login button. Can (and should) 
+be overridden by `'YOTI_LOGIN_VIEW'` setting
+- `yoti_profile` (`/yoti/profile`) - a view with user profile details. It's 
+also given just for example and should be overridden by your view, using 
+`'YOTI_REDIRECT_TO'` setting
+
+```python
+# your_flask_project/app.py
+ 
+...
+ 
+app.config.update({
+    ...
+    'YOTI_LOGIN_VIEW': '...',
+    'YOTI_REDIRECT_TO': '...',
+    'YOTI_LOGIN_BUTTON_LABEL': '...',
+})
+```
+* **`YOTI_LOGIN_VIEW`**<br>
+If *not* authenticated user is trying to access a view with 
+`@yoti_authenticated` decorator, he/she will be redirected to this view.
+Example: `login`<br>
+In this case you should have something like this in your Flask app:
+```python
+@app.route('/login')
+def login():
+    render_template('login.html')
+```
+Default value: `flask_yoti.login` (with `/yoti/login/` URL)
+
+* **`YOTI_REDIRECT_TO`**<br>
+View name to which user is redirected after successful authentication.<br>
+Example: `profile`<br>
+In this case you should have something like this in your Flask app::
+```python
+@app.route('/profile')
+@yoti_authenticated
+def login():
+    user_profile = session.get('yoti_user_profile')
+    render_template('profile.html', **user_profile)
+```
+Default value: `flask_yoti.profile`  (with `/yoti/profile/` URL)
+
+<br>
+
+
+### Yoti application configuration ###
+
+Your Yoti application's callback URL should point to `your_site.com/yoti/auth`.<br>
+If you want to add a verification tag into any template using Jinja2 or DTL as a 
+template language (other than `/yoti/auth/`, because it's already has one),
+you can use a `{{ yoti_site_verification }}` tag inside `<head>` of that template.
+
+## Plugin usage ##
+
+1. First you need to add a login button to some of your view's templates.
+- You can do it by using one of the predefined login buttons:
+```
+{{ yoti_login_button_sm }}
+{{ yoti_login_button_md }}
+{{ yoti_login_button_lg }}
+```
+- or with `{{ yoti_login_button(size='small', text='Log In with Yoti')`<br>
+Available button sizes: `small`, `medium`, `large`
+
+By clicking this button, user will be redirected to the Yoti Authentication page.
+
+*Remember to add an appropriate script to your page with login 
+button in order for it to work. See: [Yoti Developers Documentation](https://www.yoti.com/developers/#login-button-setup)*
+
+2. After successful authentication, user will be redirected to a view,
+provided by the `YOTI_REDIRECT_TO` setting.
+3. In order to have an access to an authenticated user's information inside a view,
+you should use a `@yoti_authenticated` decorator.
+Example:
+```python
+from flask_yoti import yoti_authenticated
+ 
+@yoti_authenticated
+def profile_view(request):
+    user_id = request.yoti_user_id
+    user_profile = request.yoti_user_profile
+    return render(request, 'profile.html', user_profile)
+```
+
+4. All *not authenticated* users trying to access endpoint with this decorator, 
+will be redirected to an endpoint, provided by the `YOTI_LOGIN_VIEW` setting.
+
+## Tests ##
+
+To run unit tests just type `py.test` inside `flask_yoti` dir.

plugins/flask_yoti/README.md

@@ -0,0 +1,42 @@
+import os
+
+from flask import Flask, render_template, session
+from flask_yoti import flask_yoti_blueprint
+from flask_yoti.decorators import yoti_authenticated
+
+YOTI_APPLICATION_ID = os.environ.get('YOTI_APPLICATION_ID')
+
+app = Flask(__name__)
+app.secret_key = os.urandom(24)
+
+app.config.update(
+    YOTI_APPLICATION_ID=YOTI_APPLICATION_ID,
+    YOTI_VERIFICATION_KEY=os.environ.get('YOTI_VERIFICATION_KEY'),
+    YOTI_CLIENT_SDK_ID=os.environ.get('YOTI_CLIENT_SDK_ID'),
+    YOTI_KEY_FILE_PATH=os.environ.get('YOTI_KEY_FILE_PATH'),
+    YOTI_LOGIN_VIEW='login',
+    YOTI_REDIRECT_TO='profile'
+)
+
+app.register_blueprint(flask_yoti_blueprint, url_prefix='/yoti')
+
+
+@app.route('/')
+def index():
+    return render_template('index.html', app_id=YOTI_APPLICATION_ID)
+
+
+@app.route('/login')
+def login():
+    return render_template('login.html')
+
+
+@app.route('/profile')
+@yoti_authenticated
+def profile():
+    user_profile = session.get('yoti_user_profile', {})
+    return render_template('profile.html', **user_profile)
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

plugins/flask_yoti/example/app.py

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <!-- Your header content -->
+    <script src="https://sdk.yoti.com/clients/browser.js"></script>
+    <meta charset="UTF-8">
+    <title>Index</title>
+</head>
+
+<body style="background-color:papayawhip;">
+    <!-- Your website content -->
+
+    <!-- This span will create the Yoti button -->
+    Button: {{ yoti_login_button('small', 'Custom label') }}
+
+    <!-- This script snippet will also be required in your HTML body during the early pilot period -->
+    <script>
+        _ybg.config.service = 'https://www.yoti.com/connect/';
+        _ybg.init();
+    </script>
+</body>
+</html>

plugins/flask_yoti/example/templates/login.html

@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="yoti-site-verification" content="{{ verification_key }}">
+    <title>PROFILE</title>
+</head>
+<body style="background-color:papayawhip;">
+    <h3><a href="/">Home</a></h3>
+    <table>
+        {% if user_id %}
+            <tr>
+                <td>USER ID:</td>
+                <td>{{user_id}}</td>
+            </tr>
+        {% endif %}
+
+        {% if selfie %}
+            <tr>
+                <td>SELFIE:</td>
+                <td><img width="200" alt="photo" src="{{selfie}}" /></td>
+            </tr>
+        {% endif %}
+
+        {% if phone_number %}
+            <tr>
+                <td>PHONE:</td>
+                <td>{{phone_number}}</td>
+            </tr>
+        {% endif %}
+
+        {% if names %}
+            <tr>
+                <td>NAMES:</td>
+                <td>{{names}}</td>
+            </tr>
+        {% endif %}
+
+        {% if birthdate %}
+            <tr>
+                <td>DATE OF BIRTH</td>
+                <td>{{birthdate}}</td>
+            </tr>
+        {% endif %}
+
+        {% if nationality %}
+            <tr>
+                <td>NATIONALITY</td>
+                <td>{{nationality}}</td>
+            </tr>
+        {% endif %}
+
+        {% if gender %}
+            <tr>
+                <td>GENDER</td>
+                <td>{{gender}}</td>
+            </tr>
+        {% endif %}
+    </table>
+</body>
+</html>

plugins/flask_yoti/example/templates/profile.html

@@ -0,0 +1 @@
+from .flask_yoti import flask_yoti_blueprint

plugins/flask_yoti/flask_yoti/__init__.py

@@ -0,0 +1,33 @@
+from flask import Markup
+
+from .login_button import get_login_button_html
+from .settings import get_config_value
+
+
+def yoti_context():
+    context = login_button_context()
+    context.update(site_verification_context())
+    context.update(application_context())
+    return context
+
+
+def login_button_context():
+    return {
+        'yoti_login_button': get_login_button_html,
+        'yoti_login_button_sm': get_login_button_html('small'),
+        'yoti_login_button_md': get_login_button_html('medium'),
+        'yoti_login_button_lg': get_login_button_html('large')
+    }
+
+
+def site_verification_context():
+    verification_key = get_config_value('YOTI_VERIFICATION_KEY')
+    raw_text = '<meta name="yoti-site-verification" content="{0}">'.format(
+        verification_key
+    )
+    return {'yoti_site_verification': Markup(raw_text)}
+
+
+def application_context():
+    yoti_application_id = get_config_value('YOTI_APPLICATION_ID')
+    return {'yoti_application_id': yoti_application_id}

plugins/flask_yoti/flask_yoti/context_processors.py

@@ -0,0 +1,32 @@
+from time import time
+
+
+class ActivityDetailsStorage(object):
+
+    def __init__(self):
+        self.storage = {}
+        self._timestamps = {}
+        self._timeout_sec = 15
+
+    def save(self, activity_details):
+        user_id = activity_details.user_id
+        self.storage[user_id] = activity_details
+        self._timestamps[user_id] = time() + self._timeout_sec
+
+    def get(self, user_id):
+        self._clear_outdated()
+        return self.storage.pop(user_id, None)
+
+    def _clear_outdated(self):
+        current_time = time()
+        to_remove = []
+        for user_id, timestamp in self._timestamps.items():
+            if timestamp <= current_time:
+                to_remove.append(user_id)
+
+        for user_id in to_remove:
+            del self.storage[user_id]
+            del self._timestamps[user_id]
+
+
+activity_details_storage = ActivityDetailsStorage()

plugins/flask_yoti/flask_yoti/context_storage.py

@@ -0,0 +1,26 @@
+from functools import wraps
+from flask import redirect, session, url_for
+
+from .context_storage import activity_details_storage
+from .settings import get_config_value
+from .helpers import is_cookie_session
+
+
+def yoti_authenticated(view_func):
+    @wraps(view_func)
+    def _decorated(*args, **kwargs):
+        user_id = session.get('yoti_user_id')
+        if not is_cookie_session(session):
+            activity_details = session.get('activity_details')
+        else:
+            activity_details = activity_details_storage.get(user_id)
+        if not activity_details or activity_details.outcome != 'SUCCESS':
+            yoti_login_view = get_config_value('YOTI_LOGIN_VIEW')
+            return redirect(url_for(yoti_login_view))
+
+        session['yoti_user_id'] = activity_details.user_id
+        session['yoti_user_profile'] = activity_details.user_profile
+
+        return view_func(*args, **kwargs)
+
+    return _decorated