1 from zope.interface import Interface
2
5
7 """ On ingress: classify a request.
8 """
10 """ environ -> request classifier string
11
12 This interface is responsible for returning a string
13 value representing a request classification.
14
15 o 'environ' is the WSGI environment.
16 """
17
19 """ On egress: decide whether a challenge needs to be presented
20 to the user.
21 """
23 """ args -> True | False
24
25 o 'environ' is the WSGI environment.
26
27 o 'status' is the HTTP status as returned by the downstream
28 WSGI application.
29
30 o 'headers' are the headers returned by the downstream WSGI
31 application.
32
33 This interface is responsible for returning True if
34 a challenge needs to be presented to the user, False otherwise.
35 """
36
38
39 """
40 On ingress: Extract credentials from the WSGI environment and
41 turn them into an identity.
42
43 On egress (remember): Conditionally set information in the response headers
44 allowing the remote system to remember this identity.
45
46 On egress (forget): Conditionally set information in the response
47 headers allowing the remote system to forget this identity (during
48 a challenge).
49 """
50
52 """ On ingress:
53
54 environ -> { k1 : v1
55 , ...
56 , kN : vN
57 } | None
58
59 o 'environ' is the WSGI environment.
60
61 o If credentials are found, the returned identity mapping will
62 contain an arbitrary set of key/value pairs. If the
63 identity is based on a login and password, the environment
64 is recommended to contain at least 'login' and 'password'
65 keys as this provides compatibility between the plugin and
66 existing authenticator plugins. If the identity can be
67 'preauthenticated' (e.g. if the userid is embedded in the
68 identity, such as when we're using ticket-based
69 authentication), the plugin should set the userid in the
70 special 'repoze.who.userid' key; no authenticators will be
71 asked to authenticate the identity thereafer.
72
73 o Return None to indicate that the plugin found no appropriate
74 credentials.
75
76 o Only IIdentifier plugins which match one of the the current
77 request's classifications will be asked to perform
78 identification.
79
80 o An identifier plugin is permitted to add a key to the
81 environment named 'repoze.who.application', which should be
82 an arbitrary WSGI application. If an identifier plugin does
83 so, this application is used instead of the downstream
84 application set up within the middleware. This feature is
85 useful for identifier plugins which need to perform
86 redirection to obtain credentials. If two identifier
87 plugins add a 'repoze.who.application' WSGI application to
88 the environment, the last one consulted will"win".
89 """
90
92 """ On egress (no challenge required):
93
94 args -> [ (header-name, header-value), ...] | None
95
96 Return a list of headers suitable for allowing the requesting
97 system to remember the identification information (e.g. a
98 Set-Cookie header). Return None if no headers need to be set.
99 These headers will be appended to any headers returned by the
100 downstream application.
101 """
102
103 - def forget(environ, identity):
104 """ On egress (challenge required):
105
106 args -> [ (header-name, header-value), ...] | None
107
108 Return a list of headers suitable for allowing the requesting
109 system to forget the identification information (e.g. a
110 Set-Cookie header with an expires date in the past). Return
111 None if no headers need to be set. These headers will be
112 included in the response provided by the challenge app.
113 """
114
116
117 """ On ingress: validate the identity and return a user id or None.
118 """
119
121 """ identity -> 'userid' | None
122
123 o 'environ' is the WSGI environment.
124
125 o 'identity' will be a dictionary (with arbitrary keys and
126 values).
127
128 o The IAuthenticator should return a single user id (optimally
129 a string) if the identity can be authenticated. If the
130 identify cannot be authenticated, the IAuthenticator should
131 return None.
132
133 Each instance of a registered IAuthenticator plugin that
134 matches the request classifier will be called N times during a
135 single request, where N is the number of identities found by
136 any IIdentifierPlugin instances.
137
138 An authenticator must not raise an exception if it is provided
139 an identity dictionary that it does not understand (e.g. if it
140 presumes that 'login' and 'password' are keys in the
141 dictionary, it should check for the existence of these keys
142 before attempting to do anything; if they don't exist, it
143 should return None).
144
145 An authenticator is permitted to add extra keys to the 'identity'
146 dictionary (e.g., to save metadata from a database query, rather
147 than requiring a separate query from an IMetadataProvider plugin).
148 """
149
151
152 """ On egress: Conditionally initiate a challenge to the user to
153 provide credentials.
154
155 Only challenge plugins which match one of the the current
156 response's classifications will be asked to perform a
157 challenge.
158 """
159
160 - def challenge(environ, status, app_headers, forget_headers):
161 """ args -> WSGI application or None
162
163 o 'environ' is the WSGI environment.
164
165 o 'status' is the status written into start_response by the
166 downstream application.
167
168 o 'app_headers' is the headers list written into start_response by the
169 downstream application.
170
171 o 'forget_headers' is a list of headers which must be passed
172 back in the response in order to perform credentials reset
173 (logout). These come from the 'forget' method of
174 IIdentifier plugin used to do the request's identification.
175
176 Examine the values passed in and return a WSGI application
177 (a callable which accepts environ and start_response as its
178 two positional arguments, ala PEP 333) which causes a
179 challenge to be performed. Return None to forego performing a
180 challenge.
181 """
182
183
199