fief_client.integrations.flask

  1"""Flask integration."""
  2import uuid
  3from functools import wraps
  4from typing import Callable, List, Optional
  5
  6from flask import g, request
  7
  8from fief_client import (
  9    Fief,
 10    FiefAccessTokenACRTooLow,
 11    FiefAccessTokenExpired,
 12    FiefAccessTokenInfo,
 13    FiefAccessTokenInvalid,
 14    FiefAccessTokenMissingScope,
 15    FiefACR,
 16    FiefUserInfo,
 17)
 18from fief_client.client import FiefAccessTokenMissingPermission
 19
 20
 21class FiefAuthError(Exception):
 22    """
 23    Base error for FiefAuth integration.
 24    """
 25
 26
 27class FiefAuthUnauthorized(FiefAuthError):
 28    """
 29    Request unauthorized error.
 30
 31    This error is raised when using the `authenticated` or `current_user` decorator
 32    but the request is not authenticated.
 33
 34    You should implement an `errorhandler` to define the behavior of your server when
 35    this happens.
 36
 37    **Example:**
 38
 39    ```py
 40    @app.errorhandler(FiefAuthUnauthorized)
 41    def fief_unauthorized_error(e):
 42        return "", 401
 43    ```
 44    """
 45
 46
 47class FiefAuthForbidden(FiefAuthError):
 48    """
 49    Request forbidden error.
 50
 51    This error is raised when using the `authenticated` or `current_user` decorator
 52    but the access token doesn't match the list of scopes, permissions or minimum ACR level.
 53
 54    You should implement an `errorhandler` to define the behavior of your server when
 55    this happens.
 56
 57    **Example:**
 58
 59    ```py
 60    @app.errorhandler(FiefAuthForbidden)
 61    def fief_forbidden_error(e):
 62        return "", 403
 63    ```
 64    """
 65
 66
 67TokenGetter = Callable[[], Optional[str]]
 68"""Type of a function that can be used to retrieve a token."""
 69
 70UserInfoCacheGetter = Callable[[uuid.UUID], Optional[FiefUserInfo]]
 71"""
 72Type of a function that can be used to retrieve user information from a cache.
 73
 74Read more: https://docs.fief.dev/integrate/python/flask/#web-application-example
 75"""
 76
 77UserInfoCacheSetter = Callable[[uuid.UUID, FiefUserInfo], None]
 78"""
 79Type of a function that can be used to store user information in a cache.
 80
 81Read more: https://docs.fief.dev/integrate/python/flask/#web-application-example
 82"""
 83
 84
 85def get_authorization_scheme_token(*, scheme: str = "bearer") -> TokenGetter:
 86    """
 87    Return a `TokenGetter` function to retrieve a token from the `Authorization` header of an HTTP request.
 88
 89    :param scheme: Scheme of the token. Defaults to `bearer`.
 90    """
 91
 92    def _get_authorization_scheme_token():
 93        authorization = request.headers.get("Authorization")
 94        if authorization is None:
 95            return None
 96        parts = authorization.split()
 97        if len(parts) != 2 or parts[0].lower() != scheme.lower():
 98            return None
 99        return parts[1]
100
101    return _get_authorization_scheme_token
102
103
104def get_cookie(cookie_name: str) -> TokenGetter:
105    """
106    Return a `TokenGetter` function to retrieve a token from a `Cookie` of an HTTP request.
107
108    :param cookie_name: Name of the cookie.
109    """
110
111    def _get_cookie():
112        return request.cookies.get(cookie_name)
113
114    return _get_cookie
115
116
117class FiefAuth:
118    """
119    Helper class to integrate Fief authentication with Flask.
120
121    **Example:**
122
123    ```py
124    from fief_client import Fief
125    from fief_client.integrations.flask import (
126        FiefAuth,
127        get_authorization_scheme_token,
128    )
129    from flask import Flask, g
130
131    fief = Fief(
132        "https://example.fief.dev",
133        "YOUR_CLIENT_ID",
134        "YOUR_CLIENT_SECRET",
135    )
136
137    auth = FiefAuth(fief, get_authorization_scheme_token())
138
139    app = Flask(__name__)
140    ```
141    """
142
143    def __init__(
144        self,
145        client: Fief,
146        token_getter: TokenGetter,
147        *,
148        get_userinfo_cache: Optional[UserInfoCacheGetter] = None,
149        set_userinfo_cache: Optional[UserInfoCacheSetter] = None,
150    ) -> None:
151        """
152        :param client: Instance of a `fief_client.Fief` client.
153        :param token_getter: Function to retrieve a token.
154        It should follow the `TokenGetter` type.
155        :param get_userinfo_cache: Optional function to retrieve user information from a cache.
156        Otherwise, the Fief API will always be reached when requesting user information.
157        It should follow the `UserInfoCacheGetter` type.
158        :param set_userinfo_cache: Optional function to store user information in a cache.
159        It should follow the `UserInfoCacheSetter` type.
160        """
161        self.client = client
162        self.token_getter = token_getter
163        self.get_userinfo_cache = get_userinfo_cache
164        self.set_userinfo_cache = set_userinfo_cache
165
166    def authenticated(
167        self,
168        *,
169        optional: bool = False,
170        scope: Optional[List[str]] = None,
171        acr: Optional[FiefACR] = None,
172        permissions: Optional[List[str]] = None,
173    ):
174        """
175        Decorator to check if a request is authenticated.
176
177        If the request is authenticated, the `g` object will have an `access_token_info` property,
178        of type `fief_client.FiefAccessTokenInfo`.
179
180        :param optional: If `False` and the request is not authenticated,
181        a `FiefAuthUnauthorized` error will be raised.
182        :param scope: Optional list of scopes required.
183        If the access token lacks one of the required scope, a `FiefAuthForbidden` error will be raised.
184        :param acr: Optional minimum ACR level required.
185        If the access token doesn't meet the minimum level, a `FiefAuthForbidden` error will be raised.
186        Read more: https://docs.fief.dev/going-further/acr/
187        :param permissions: Optional list of permissions required.
188        If the access token lacks one of the required permission, a `FiefAuthForbidden` error will be raised.
189
190        **Example**
191
192        ```py
193        @app.get("/authenticated")
194        @auth.authenticated()
195        def get_authenticated():
196            return g.access_token_info
197        ```
198        """
199
200        def _authenticated(f):
201            @wraps(f)
202            def decorated_function(*args, **kwargs):
203                token = self.token_getter()
204                if token is None:
205                    if optional:
206                        g.access_token_info = None
207                        return f(*args, **kwargs)
208                    raise FiefAuthUnauthorized()
209
210                try:
211                    info = self.client.validate_access_token(
212                        token,
213                        required_scope=scope,
214                        required_acr=acr,
215                        required_permissions=permissions,
216                    )
217                except (FiefAccessTokenInvalid, FiefAccessTokenExpired) as e:
218                    if optional:
219                        g.access_token_info = None
220                        return f(*args, **kwargs)
221                    raise FiefAuthUnauthorized() from e
222                except (
223                    FiefAccessTokenMissingScope,
224                    FiefAccessTokenACRTooLow,
225                    FiefAccessTokenMissingPermission,
226                ) as e:
227                    raise FiefAuthForbidden() from e
228
229                g.access_token_info = info
230
231                return f(*args, **kwargs)
232
233            return decorated_function
234
235        return _authenticated
236
237    def current_user(
238        self,
239        *,
240        optional: bool = False,
241        scope: Optional[List[str]] = None,
242        acr: Optional[FiefACR] = None,
243        permissions: Optional[List[str]] = None,
244        refresh: bool = False,
245    ):
246        """
247        Decorator to check if a user is authenticated.
248
249        If the request is authenticated, the `g` object will have a `user` property,
250        of type `fief_client.FiefUserInfo`.
251
252        :param optional: If `False` and the request is not authenticated,
253        a `FiefAuthUnauthorized` error will be raised.
254        :param scope: Optional list of scopes required.
255        If the access token lacks one of the required scope, a `FiefAuthForbidden` error will be raised.
256        :param acr: Optional minimum ACR level required.
257        If the access token doesn't meet the minimum level, a `FiefAuthForbidden` error will be raised.
258        Read more: https://docs.fief.dev/going-further/acr/
259        :param permissions: Optional list of permissions required.
260        If the access token lacks one of the required permission, a `FiefAuthForbidden` error will be raised.
261        :param refresh: If `True`, the user information will be refreshed from the Fief API.
262        Otherwise, the cache will be used.
263
264        **Example**
265
266        ```py
267        @app.get("/current-user")
268        @auth.current_user()
269        def get_current_user():
270            user = g.user
271            return f"<h1>You are authenticated. Your user email is {user['email']}</h1>"
272        ```
273        """
274
275        def _current_user(f):
276            @wraps(f)
277            @self.authenticated(
278                optional=optional, scope=scope, acr=acr, permissions=permissions
279            )
280            def decorated_function(*args, **kwargs):
281                access_token_info: Optional[FiefAccessTokenInfo] = g.access_token_info
282
283                if access_token_info is None and optional:
284                    g.user = None
285                    return f(*args, **kwargs)
286
287                assert access_token_info is not None
288
289                userinfo = None
290                if self.get_userinfo_cache is not None:
291                    userinfo = self.get_userinfo_cache(access_token_info["id"])
292
293                if userinfo is None or refresh:
294                    userinfo = self.client.userinfo(access_token_info["access_token"])
295
296                    if self.set_userinfo_cache is not None:
297                        self.set_userinfo_cache(access_token_info["id"], userinfo)
298
299                g.user = userinfo
300
301                return f(*args, **kwargs)
302
303            return decorated_function
304
305        return _current_user
306
307
308__all__ = [
309    "FiefAuth",
310    "FiefAuthError",
311    "FiefAuthUnauthorized",
312    "FiefAuthForbidden",
313    "TokenGetter",
314    "UserInfoCacheGetter",
315    "UserInfoCacheSetter",
316    "get_authorization_scheme_token",
317    "get_cookie",
318]