.. _examples:

===================
Generating QR codes
===================

PyBankID can generate QR codes for you. There is an demo application in the
`examples folder of the repo <https://github.com/hbldh/pybankid/tree/master/examples>`_ where a
Flask application called ``qrdemo`` shows one way to do authentication with animated QR codes.

The QR code content generation is done with the ``generate_qr_code_content`` method on the BankID Client instances, or directly
through the identically named method in ``bankid.qr`` module.

Below follows the app's README file, for your convenience.

QR Authentication Example
-------------------------

Making a simple authentication via QR code solution using Flask, Flask-Caching and PyBankID.

Running the application
~~~~~~~~~~~~~~~~~~~~~~~

1. Navigate your terminal to the same folder that this ``README.md`` resides in.
2. Create a virtualenv: ``python -m venv .venv``
3. Activate it.
4. Install requirements: ``pip install -r requirements.txt``
5. Run Flask app:

   1. From Bash:

      .. code-block:: bash

          $ export FLASK_APP=qrdemo.app:app
          $ flask run -h 0.0.0.0

   2. From Powershell:

      .. code-block:: powershell

          > $env:FLASK_APP = "qrdemo.app:app"
          > flask run -h 0.0.0.0


The app can now be accessed from the running computer on ``http://127.0.0.1:5000``, ``http://localhost:5000`` or from an
external device on the same network on ``http://<ip for the running computer>:5000``.


Basic workflow
~~~~~~~~~~~~~~

These are the steps that the application takes:

1. Ask the user for Swedish Personal Identity Number (PN) or initiate an authentication without.
2. Upon POSTing that PN to the backend, initiate a BankID ``authenticate`` session. This generates tokens that
   one can create QR codes from using the ``client.generate_qr_code_content`` method.
3. Continuously update the QR code according to the description in the BankID Relying Party Guidelines
   Version: 3.6 (see below, Chapter 4). The new QR code content to display MUST be fetched from the backend since
   the ``qrStartSecret`` must never be shown to the user for the authentication to be trustworthy.
4. Also make ``collect`` calls to the BankID servers continuously and monitor if signing is complete or failed.
5. Redirect when complete or failed.


Missing components
~~~~~~~~~~~~~~~~~~

There are a few shortcuts taken here:

- There is no error handling of ``status: failed`` results when collecting the authentication response.
- There is no ``Recommended User Messages (RFA)`` handling. It merely displays the ``status`` and ``hintCode`` from the collect response.
- The Cache is a memory cache on this single instance web app.

References
~~~~~~~~~~

- `BankID Integration Guide <https://www.bankid.com/en/utvecklare/guider/teknisk-integrationsguide/>`_