Coverage for gws-app/gws/base/auth/__init__.py: 100%

1"""Authentication and authorization. 

2 

3This package provides the authorization manager, the base classes for the 

4authentication plugins and the user objects that check permissions. 

5 

6Authentication is split into four kinds of pluggable objects: 

7 

8- methods (``gws.AuthMethod``, plugins in ``gws.plugin.auth_method``, for example 

9 ``web``, ``basic``, ``token``) define how credentials and sessions reach the server, 

10 for example as a login form and a session cookie, or as HTTP basic auth. 

11- providers (``gws.AuthProvider``, for example ``file``, ``ldap``, ``postgres``) 

12 verify credentials and return users. 

13- multi-factor adapters (``gws.AuthMultiFactorAdapter``, for example ``email``, 

14 ``totp``) add a second verification step for users with an ``mfaUid``. 

15- the session manager (``gws.AuthSessionManager``, by default ``sqlite``) 

16 stores sessions between requests. 

17 

18Submodules: 

19 

20- ``manager``: the authorization manager (``root.app.authMgr``). It creates the 

21 methods, providers, adapters, session manager and the optional throttle, and, 

22 as the ``auth`` middleware, opens a session for every web request. 

23- ``method``: base class for authentication methods. 

24- ``provider``: base class for authentication providers. 

25- ``system_provider``: the built-in provider of the ``guest`` and ``system`` users. 

26- ``mfa``: base class for multi-factor adapters, with TOTP code generation and checking. 

27- ``session``: the session object. 

28- ``session_manager``: base class for session managers. 

29- ``throttle``: blocking of repeated failed login attempts, counted per address and, 

30 optionally, per login name, and stored in an sqlite file. 

31- ``user``: user classes, permission checks and conversion of provider records to users. 

32- ``cli``: the ``gws auth`` CLI commands to list and remove sessions. 

33 

34Multi-factor authentication (handled by the ``web`` method) is used for users 

35with an ``mfaUid`` attribute, the uid of a configured adapter. Specific adapters 

36can require other user attributes, for example ``email`` or ``mfaSecret``. The 

37login starts a ``gws.AuthMultiFactorTransaction``, which is kept in the session 

38until it is verified, fails or expires. Some adapters can be restarted, for 

39example by sending a new code by email. A transaction fails when its life time 

40has elapsed or the number of verification attempts exceeds the limit. A restart 

41creates a new transaction with an increased restart count. 

42 

43If no methods are configured, the ``web`` method is used. The ``system`` 

44provider with the guest and system users is always added after the configured 

45providers. ``maxLifeTime`` of the session manager, if set, must not be less than 

46``lifeTime``. 

47 

48The manager is registered as the ``auth`` middleware, depending on ``db``. On 

49each web request, it asks every method in turn to open a session. If no method 

50returns one, the request runs with the guest session. After the request, the 

51method of the session closes it, for example by setting the session cookie. 

52Setting a session value marks the session as changed. When a user logs in, the 

53manager passes the credentials to each provider that allows the method, until 

54one returns a user. 

55 

56With a throttle configured, blocked login attempts raise 

57``gws.TooManyRequestsError`` and every attempt is registered with the throttle. 

58The login name is stored as a hash. The counts are kept in an sqlite table, so 

59they are shared between server processes. ``blockTime`` must be greater than 

60``windowTime``. 

61 

62Users carry a set of roles. Every user has the role ``all``; logged-in users 

63also have ``user`` (or ``admin``), the guest user has ``guest``. A user can 

64always read itself. Otherwise, access to an object is decided by the first 

65permission entry whose role the user has, walking up the given context objects 

66and then the object's parents until a decision is found. Without a decision, 

67access is denied. The ``system`` user and admin users are allowed everything. 

68 

69Example:: 

70 

71 auth { 

72 methods [ 

73 { type web secure true } 

74 ] 

75 providers [ 

76 { type file path "/data/users.json" } 

77 ] 

78 session { type sqlite lifeTime "30m" } 

79 throttle { maxAttemptsPerIp 5 } 

80 } 

81 

82Example:: 

83 

84 user = req.user 

85 if user.can_write(layer): 

86 ... 

87 project = user.require_project(p.projectUid) 

88""" 

89 

90from . import ( 

91 manager, 

92 method, 

93 mfa, 

94 provider, 

95 session, 

96 session_manager, 

97 throttle, 

98 user, 

99)