Add consumer mode

Author: JBorrow

docs/README.md

@@ -28,4 +28,5 @@ Table of Contents
 - [Organization Checks](organizations.md)
 - [API Keys](api_keys.md)
 - [Hosting SOAuth](hosting.md)
+- [Consumer Mode](consume.md)
 - [Developing SOAuth](developing.md)

docs/consume.md

@@ -0,0 +1,67 @@
+Consumer Mode
+=============
+
+To enable easy integration with other services, we provide a 'consumer' version of the
+server that can accept POST requests with access tokens to validate them. This allows
+for 'external server' authentication (with e.g.
+[nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/)).
+
+To run the `soauth` server in consumer mode, you can use the same docker container as
+normal. However, you'll need to change the command that is run to:
+```
+soauth run consume
+```
+This server runs on port 8002 and does two main things:
+
+1. Handles the callback loop with the main `soauth` server
+2. Hosts an endpoint, `/introspect`, that takes the cookies in the request and 
+   returns a 200 code if the tokens are good, and a 401 if they are bad.
+
+Using with Nginx
+----------------
+
+The most common use case for this kind of authentication is with another web service.
+Nginx, for instance, can proxy all requests via the auth server to check if they
+have valid tokens in them, configured as follows:
+```
+# 'Private' webpages hosted behind soauth.
+
+# Reverse proxy to the 'consumer' service
+location /auth/ {
+  proxy_pass http://soauth:8002/;
+}
+
+# Handle the tokens.
+location = /auth/introspect {
+  proxy_pass http://soauth:8002/introspect;
+  proxy_method POST;
+}
+
+# When we 401 in /private, we want to redirect to login
+location @error401 {
+  return 302 https://identity.simonsobservatory.org/login/$YOUR_UUID;
+}
+
+# The 'private' web pages hosted behind soauth
+location /private/ {
+  root /private;
+  # This sends each request via /auth/introspect to make sure they have valid cookies.
+  auth_request /auth/introspect;
+  proxy_intercept_errors on;
+  error_page 401 = @error401;
+}
+
+# We get redirected to the root of the auth after login.
+location = /auth {
+  return 302 /private/;
+}
+```
+There are a few things here to note.
+
+1. We host the `soauth` service at `/auth/*`. 
+2. All requests to `/auth/introspect` are handled as POST requests (by default
+   Nginx makes these requests as GET requests).
+3. We set up a redirect on a 401 error directly to the login page for `soauth`.
+4. We host as set of webpages at `/private/`, and add the `auth_request` directive.
+5. When users are redirected by the auth service to its root, we send them instead
+   to the root of the private service.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soauth"
-version = "0.7.2"
+version = "0.8.0"
 requires-python = ">=3.11"
 dependencies = [
     "pydantic",

soauth/scripts/cli.py

@@ -31,9 +31,10 @@ def main():
         register = sys.argv[1] == "register"
         dev = sys.argv[2] == "dev"
         prod = sys.argv[2] == "prod"
+        consume = sys.argv[2] == "consume"
     except IndexError:
         print(
-            "Only supported command is soauth run dev, soauth run prod, or soauth setup {username}"
+            "Only supported command is soauth run dev, soauth run prod, soauth run consume, or soauth setup {username}"
         )
         exit(1)
 
@@ -78,7 +79,8 @@ def main():
         background_process.start()
         time.sleep(1)
         uvicorn.run("soauth.app.app:app", host="0.0.0.0", port=8001)
-
+    if run and consume:
+        uvicorn.run("soauth.toolkit.consumer:app", host="0.0.0.0", port=8002)
     if setup:
         from soauth.api.setup import initial_setup
         from soauth.config.settings import Settings

soauth/toolkit/consumer.py

@@ -0,0 +1,64 @@
+"""
+A small web server that hosts only one endpoint: /introspect. This processes an
+identity token and checks whether the user has the correct grant to be
+authenticated against the service. We provide a courtesy '/login' endpoint
+that is a small HTML page with a button that directs users to the login page
+to
+"""
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import HTMLResponse
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from soauth.core.uuid import UUID
+from soauth.toolkit.fastapi import global_setup
+
+
+class ConsumerSettings(BaseSettings):
+    app_base_url: str
+    authentication_base_url: str
+    app_id: UUID
+    client_secret: str
+    public_key: str
+    key_pair_type: str
+
+    required_grant: str = "grant:you_must_choose_one"
+
+    model_config = SettingsConfigDict(env_prefix="SOAUTH_", env_file=".env")
+
+
+settings = ConsumerSettings()
+
+app = global_setup(
+    app=FastAPI(),
+    app_base_url=settings.app_base_url,
+    authentication_base_url=settings.authentication_base_url,
+    app_id=settings.app_id,
+    client_secret=settings.client_secret,
+    public_key=settings.public_key,
+    key_pair_type=settings.key_pair_type,
+    handle_exceptions=False,
+    use_refresh_token=False,
+)
+
+
+@app.get("/login")
+def login(request: Request):
+    if request.user.is_authenticated:
+        return HTMLResponse(
+            content=f"<html><body><a href='{app.logout_url}'>Logout</a>"
+        )
+    else:
+        return HTMLResponse(content=f"<html><body><a href='{app.login_url}'>Login</a>")
+
+
+@app.post("/introspect")
+def introspect(request: Request):
+    if not request.user.is_authenticated:
+        print("Not authenticated")
+        raise HTTPException(401, "Not authenticated")
+
+    if settings.required_grant not in request.auth.scopes:
+        print(settings.required_grant, "not in", request.auth.scopes)
+        raise HTTPException(401, "Not authorized")
+    return Response()

soauth/toolkit/fastapi.py

@@ -53,14 +53,15 @@ async def secure_endpoint(user: AuthenticatedUserDependency):
     key_expired_handler,
     logout,
     on_auth_error,
+    transform_auth_error,
 )
 
 
 class SOUserWithGrants(SOUser):
     grants: set[str] = Field(default_factory=set)
 
 
-def add_exception_handlers(app: FastAPI) -> FastAPI:
+def add_exception_handlers(app: FastAPI, allow_refresh: bool = True) -> FastAPI:
     """
     Adds exception handlers for authentication. To use these, you must:
 
@@ -73,6 +74,10 @@ def add_exception_handlers(app: FastAPI) -> FastAPI:
 
     - Set `app.refresh_token_name` to change the cookie name for the refresh token
     - Set `app.access_token_name` to change the cookie name for the access token
+
+    If you do not wish to allow automatic refreshing of the keys by the application
+    (e.g. you are running in 'consumer' mode where only 401 or 200s are allowed),
+    you can set allow_refresh = False.
     """
     app.add_exception_handler(KeyDecodeError, key_decode_handler)
     app.add_exception_handler(KeyExpiredError, key_expired_handler)
@@ -179,6 +184,8 @@ def global_setup(
     public_key: str,
     key_pair_type: str,
     add_middleware: bool = True,
+    handle_exceptions: bool = True,
+    use_refresh_token: bool = True,
 ) -> FastAPI:
     """
     Transform the app such that it is ready for authentication. Can either add middleware
@@ -207,6 +214,13 @@ def global_setup(
         This allows for the use of starlette's `@requries()` (against user grants), and
         access to `request.user` and `request.auth.scopes`. Alternatively, you can use
         the dependencies defined in this file.
+    handle_exceptions: bool = True,
+        If this is used, we automatically handle expired/broken credentials via the server
+        itself (including using refresh tokens). If it is not, you are left on your own
+        to handle the resulting 400-level errors.
+    use_refresh_token: bool = True,
+        Whether or not to set and use the refresh token cookie. Otherwise your users will
+        need to round-trip to the identity server every time the access token expires.
 
     Example
     -------
@@ -274,6 +288,7 @@ async def test(request: Request):
     app.authentication_url = authentication_base_url
     app.client_secret = client_secret
     app.app_id = app_id
+    app.use_refresh_token = use_refresh_token
 
     app.public_key = public_key.encode("utf-8")
     app.key_pair_type = key_pair_type
@@ -289,9 +304,11 @@ async def test(request: Request):
         app.add_middleware(
             AuthenticationMiddleware,
             backend=SOAuthCookieBackend(
-                public_key=app.public_key, key_pair_type=app.key_pair_type
+                public_key=app.public_key,
+                key_pair_type=app.key_pair_type,
+                use_refresh_token=use_refresh_token,
             ),
-            on_error=on_auth_error,
+            on_error=on_auth_error if handle_exceptions else transform_auth_error,
         )
 
     app.add_api_route(path="/logout", endpoint=logout)