[Doc] Added full documentation to Auth

This commit is contained in:
Ferdinand Thiessen 2020-10-30 03:06:18 +01:00
parent 4a7caad7e8
commit 58302595f3
1 changed files with 70 additions and 28 deletions

View File

@ -1,13 +1,6 @@
"""Authentication plugin, provides basic routes
Allow management of authentication, login, logout, etc.
```Routes
/auth POST: login (new token)
GET: get all tokens for user
/auth/<token> GET: get lifetime of token
PUT: set new lifetime
DELETE: logout / delete token```
"""
from flask import Blueprint, request, jsonify
@ -27,10 +20,10 @@ class AuthRoutePlugin(Plugin):
@auth_bp.route("/auth", methods=["POST"])
def _login():
"""Login in an user and create a `flaschengeist.system.models.Session` for the user.
def login():
"""Login in an user and create a session
Route: ``/auth``
Route: ``/auth`` | Method: ``POST``
POST-data: {'userid': string, 'password': string}
@ -61,14 +54,28 @@ def _login():
@auth_bp.route("/auth", methods=["GET"])
@login_required()
def _get_sessions(current_session, **kwargs):
def get_sessions(current_session, **kwargs):
"""Get all valid sessions of current user
Route: ``/auth`` | Method: ``GET``
Returns:
A JSON array of `flaschengeist.system.models.session.Session` or HTTP error
"""
sessions = sessionController.get_users_sessions(current_session._user)
return jsonify(sessions)
@auth_bp.route("/auth/<token>", methods=["DELETE"])
@login_required()
def _delete_session(token, current_session, **kwargs):
def delete_session(token, current_session, **kwargs):
"""Delete a session aka "logout"
Route: ``/auth/<token>`` | Method: ``DELETE``
Returns:
200 Status (empty) or HTTP error
"""
logger.debug("Try to delete access token {{ {} }}".format(token))
session = sessionController.get_session(token, current_session._user)
if not session:
@ -78,12 +85,23 @@ def _delete_session(token, current_session, **kwargs):
raise Forbidden
sessionController.delete_session(session)
sessionController.clear_expired()
return jsonify({"ok": "ok"})
return ""
@auth_bp.route("/auth/<token>", methods=["GET"])
@login_required()
def _get_session(token, current_session, **kwargs):
def get_session(token, current_session, **kwargs):
"""Retrieve information about a session
Route: ``/auth/<token>`` | Method: ``GET``
Attributes:
token: Token identifying session to retrieve
current_session: Session sent with Authorization Header
Returns:
JSON encoded `flaschengeist.system.models.session.Session` or HTTP error
"""
logger.debug("get token {{ {} }}".format(token))
session = sessionController.get_session(token, current_session._user)
if not session:
@ -93,21 +111,22 @@ def _get_session(token, current_session, **kwargs):
return jsonify(session)
@auth_bp.route("/auth/<token>/user", methods=["GET"])
@login_required()
def _get_assocd_user(token, current_session, **kwargs):
logger.debug("get token {{ {} }}".format(token))
session = sessionController.get_session(token, current_session._user)
if not session:
# Return 403 error, so that users can not bruteforce tokens
# Valid tokens from other users and invalid tokens now are looking the same
raise Forbidden
return jsonify(session._user)
@auth_bp.route("/auth/<token>", methods=["PUT"])
@login_required()
def _set_lifetime(token, current_session, **kwargs):
def set_lifetime(token, current_session, **kwargs):
"""Set lifetime of a session
Route: ``/auth/<token>`` | Method: ``PUT``
POST-data: ``{value: int}``
Attributes:
token: Token identifying the session
current_session: Session sent with Authorization Header
Returns:
HTTP-200 (empty) or HTTP error
"""
session = sessionController.get_session(token, current_session._user)
if not session:
# Return 403 error, so that users can not bruteforce tokens
@ -117,6 +136,29 @@ def _set_lifetime(token, current_session, **kwargs):
lifetime = request.get_json()["value"]
logger.debug("set lifetime {{ {} }} to access token {{ {} }}".format(lifetime, token))
sessionController.set_lifetime(session, lifetime)
return jsonify({"ok": "ok"})
return ""
except (KeyError, TypeError):
raise BadRequest
@auth_bp.route("/auth/<token>/user", methods=["GET"])
@login_required()
def get_assocd_user(token, current_session, **kwargs):
"""Retrieve user owning a session
Route: ``/auth/<token>/user`` | Method: ``GET``
Attributes:
token: Token identifying the session
current_session: Session sent with Authorization Header
Returns:
JSON encoded `flaschengeist.system.models.user.User` or HTTP error
"""
logger.debug("get token {{ {} }}".format(token))
session = sessionController.get_session(token, current_session._user)
if not session:
# Return 403 error, so that users can not bruteforce tokens
# Valid tokens from other users and invalid tokens now are looking the same
raise Forbidden
return jsonify(session._user)