hyst-flask 0.0.27
Un package pour connecter une application Flask à l'HydroStore.
Requires Python: >=3.6

Ce connecteur remplace l'ancien connecteur OAuth2 appelé pystore (ou edf-pystore).
Il ne repose plus sur le serveur d'authentification OAuth mais directement sur l'HydroStore.

# Installation
```shell script
pip install hyst-flask
```

# Configuration
Ce connecteur nécessite la configuration suivante:

```python
import flask

app = flask.Flask(__name__)

app.secret_key = 'une cle secrete'

app.config['HF_STORE_SERVER_URL'] = 'url du store'
app.config['HF_APP_ID'] = 'id de votre application'

# Optionnel, par défaut 'index' sera utilisé
app.config['HF_INDEX_ENDPOINT'] = '(optionnel) un nom de route comme homepage ou index'

# Optionnel, par défaut True sra utilisé
app.config['HF_ROOT_CA_VERIFY'] = False
```

#### Paramètres obligatoires
Ces paramètres sont obligatoires, vous devez les définir pour que votre application fonctionne:
* `HF_STORE_SERVER_URL`: C'est l'url du serveur de l'HydroStore vers lequel votre application va authentifier ses utilisateurs.
* `HF_APP_ID`: C'est l'ID de votre application. Il sera utilisé par l'HydroStore pour savoir de quelle application il s'agit. 

#### Paramètres optionnels
* `HF_INDEX_ENDPOINT`: Cette valeur sera utilisée pour rediriger l'utilisateur une fois connecté.
Elle correspond au nom de l'endpoint vers lequel le rediriger. Dans Flask, un endpoint, 
c'est le nom de la fonction correspondant à une url. Pour plus de détails, [suivez ce lien](https://stackoverflow.com/questions/19261833/what-is-an-endpoint-in-flask).
* `HF_ROOT_CA_VERIFY`: Si cette valeur est à False, les certificats des connexions HTTPs effectuées par la librairie ne seront pas vérifiés.
Avant de mettre cette valeur à False, assurez vous de saisir ce qu'implique l'abscence de vérification de ces certificats.
Pour installer les certificats racine d'EDF et passer cette vérification sans avoir à la désactiver, [suivez ce lien](https://si-confluence.edf.fr/display/d3binnerpython/Python+-+Configurer+les+certificats+de+la+PKI+d%27EDF).

# Usage pour une application HTML
Pour les applications qui utilisent des templates HTML, `hyst_flask` va:
* Ajouter une route `/login` et une route `/logout` à votre application
  * `/login` affiche un formulaire de connexion qui va:
      * Vérifier les identifiants de cet utilisateur (authentification)
      * Vérifier les droits d'accès de cet utilisateur (autorisation)
      * Tracer l'accès à votre application dans l'HydroStore
  * `/logout` déconnecte votre utilisateur
* Exposer un décorateur `@login_required` à votre application
  * Ce décorateur vérifiera que l'utilisateur est bien connecté
  * Si ce n'est pas le cas il le redirigera automatiquement vers `/login`
  * Une fois connecté, l'utilisateur sera redirigé vers la page à laquelle il essayait de se rendre initialement


```python
import flask
from hyst_flask import html_bp, login_required

app = flask.Flask(__name__)

# Configuration
# ...

# Ajoute les routes /login et /logout à votre application
app.register_blueprint(html_bp)

# Ajoutez @login_required sur vos routes protégées
# Il redirigera l'utilisateur vers un formulaire de login si il n'est pas connecté
@app.route('/')
@login_required
def index():
    return 'index'
```

# Usage pour une API REST
Pour les applications qui utilisent une API REST, `hyst_flask` va:
* Exposer un générateur de décorateur `generate_token_required_decorator`
  * Ce générateur sert à générer un décorateur pour protéger vos urls d'API
  * Il ouvre le header `Authorization` et attend un token de type `Bearer` (le token généré par `/login`)
  * Si le token est invalide, il retournera la réponse que vous avez paramétré dans le générateur
  * Si le token est valide, il passe la main à votre route

```python
import flask
from hyst_flask import generate_token_required_decorator

app = flask.Flask(__name__)

# Configuration
# ...

# Créez votre propre décorateur @token_required en prenant soin de configurer
# la réponse qu'il doit retourner dans le cas où le token joint est invalide
token_required = generate_token_required_decorator(('Unauthorized.', 403))

@app.route('/')
@token_required
def index():
    return 'index'
```

# Signaler un bug
Si vous détectez un bug avec votre version de hyst-flask, vérifiez d'abord que vous êtes en présence de la dernière version disponible de la librairie.
Rendez vous sur https://pypi.org/project/hyst-flask/ et comparez la version courante du package avec votre version (`pip freeze`).
Assurez vous aussi d'avoir bien lu la documentation et d'avoir compris l'erreur indiquée. Il est possible qu'il s'agisse d'un problème réseau par exemple.

Rendez vous sur [GitLab](https://si-devops-gitlab.edf.fr/dih-dpih-sci/hydrostore/libs/hyst-micauth) et créez un ticket avec un exemple reproduisant l'erreur.

# Contributions
Pour contribuer au développement de ce projet, merci de créer un fork et de faire vos modifications
à partir de votre dépôt. Vous pourrez ensuite créer une merge request pour proposer vos modifications.

Ces modifications doivent respecter les règles suivantes:
* Votre code ne doit pas casser les tests déjà en place.
* Vos ajouts doivent être accompagné de leurs jeux de tests.
* Si vous fixez un bug, merci d'ajouter un test couvrant votre ajout pour éviter qu'il ne se reproduise.
* Votre code doit respecter la convention PEP8.
* Votre code doit être commenté et avec le format de commentaires déjà en place.