A. Sessions

Channels 支援使用 HTTP Cookie 的標準 Django 會話,這適用於 HTTP 和 WebSocket。不過,有一些注意事項需要留意。

1. 基本用法

Channels 的 SessionMiddleware 讓需要 session 資訊的 ASGI 應用程式可以從 scope 取得 Django session,它依賴 CookieMiddleware;channels.sessions.SessionMiddlewareStack 將兩者包在一起,方便套用到 URLRouter 或個別 Consumer。

在 asgi.py 中,把 SessionMiddlewareStack 包在需要 session 的 ASGI 應用程式外層即可。範例的 URLRouter 使用 path,因此也需要從 django.urls 匯入 path。

from django.urls import path
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from channels.sessions import SessionMiddlewareStack

from myapp import consumers

application = ProtocolTypeRouter({
    "websocket": AllowedHostsOriginValidator(
        SessionMiddlewareStack(
            URLRouter([
                path("frontend/", consumers.AsyncChatConsumer.as_asgi()),
            ])
        )
    ),

})

SessionMiddleware 只會在範圍內提供 HTTP 標頭的協議上運作——預設情況下,這包括 HTTP 和 WebSocket。

要在你的消費者(consumer)代碼中使用會話,可以使用 self.scope[“session”]。

class ChatConsumer(WebsocketConsumer):
    def connect(self):
        self.scope["session"]["seed"] = random.randint(1, 1000)

SessionMiddleware 遵循與預設的 Django 會話框架相同的所有 Django 設定,例如 SESSION_COOKIE_NAME 及 SESSION_COOKIE_DOMAIN。

2. Session保存

在 HTTP consumers 或 ASGI 應用中,會話的持久性如同你在 Django HTTP 視圖中期望的一樣運作——只要你傳送不具備狀態碼500的 HTTP 回應時,會話就會被保存。這是通過覆蓋任何 http.response.start 消息來完成的,以在你發送回應時將 cookie 標頭注入回應中。如果你將 `SESSION_SAVE_EVERY_REQUEST` 設定為 True,那麼它將在每次回應時保存會話並發送 cookie,否則只會在會話被修改時才保存。

然而,如果你處於 WebSocket 消費者中,會話會被填充但不會自動被保存——你必須自己調用 `scope["session"].save()`(或異步版本 `scope["session"].asave()`)來將會話持久化到你的會話存儲中。如果你不保存,會話仍會在消費者內正常工作(因為它被存儲為一個實例變數),但其他連接或 HTTP 視圖不會看到這些更改。

如果您在使用長輪詢的 HTTP 消費者(consumer),您可能需要在發送回應之前保存對會話的更改。如果您想這樣做,請調用 `scope["session"].save()`。

B. 身份驗證

Channels 原生支援標準的 Django 身份驗證,適用於 HTTP 和 WebSocket 消費者。如果您想支援不同的身份驗證方案(例如,URL 中的令牌),您可以撰寫自己的中間件或處理代碼。

1. Django authentication

Channels中的AuthMiddleware支持標準的Django身份驗證,其中使用者詳情存儲在會話中。它允許在範圍內以唯讀方式訪問user對象。 

AuthMiddleware需要SessionMiddleware才能運作,而SessionMiddleware本身需要CookieMiddleware。為了方便起見,這些都被作為一個名為AuthMiddlewareStack的組合呼叫提供,其中包含了這三者。 

要使用中介軟體,請將它包裹在asgi.py中相應層級的消費者周圍:

from django.urls import re_path

from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from channels.security.websocket import AllowedHostsOriginValidator

from myapp import consumers

application = ProtocolTypeRouter({
    "websocket": AllowedHostsOriginValidator(
        AuthMiddlewareStack(
            URLRouter([
                re_path(r"^front(end)/$", consumers.AsyncChatConsumer.as_asgi()),
            ])
        )
    ),

})

雖然您可以將中介軟體(middleware)包裝在每個消費者(consumer)上,但建議您將其包裝在較高層級的應用程式組件上,例如在這個例子中使用 URLRouter。 

請注意,AuthMiddleware 僅適用於在其作用域中提供 HTTP 標頭的協議——默認情況下,這適用於 HTTP 和 WebSocket。 

要訪問用戶,只需在您的消費者代碼中使用 `self.scope["user"]` 即可。

class ChatConsumer(WebsocketConsumer):
    def connect(self):
        self.user = self.scope["user"]
        self.accept()

2. Custom Authentication

自訂驗證中介軟體可以在 __call__(scope, receive, send) 中解析身分資訊,將結果放入 scope,再交給內層 ASGI 應用程式。以下用「依使用者 ID 查詢」展示 scope 的傳遞方式,但查到使用者並不代表已驗證該 ID 的擁有者;實際登入流程應驗證可信的 session 或 token,並處理解析失敗與匿名使用者。

from channels.db import database_sync_to_async

@database_sync_to_async
def get_user(user_id):
    try:
        return User.objects.get(id=user_id)
    except User.DoesNotExist:
        return AnonymousUser()

class QueryAuthMiddleware:
    """
    Custom middleware (insecure) that takes user IDs from the query string.
    """

    def __init__(self, app):
        # Store the ASGI application we were passed
        self.app = app

    async def __call__(self, scope, receive, send):
        # Look up user from query string (you should also do things like
        # checking if it is a valid user ID, or if scope["user"] is already
        # populated).
        scope['user'] = await get_user(int(scope["query_string"]))

        return await self.app(scope, receive, send)

相同的原則可以應用於非 HTTP 協議的身份驗證;例如,您可能希望使用聊天協議中的某人的聊天用戶名來將其轉換為用戶。

3. How to log a user in/out

Channels 提供了直接的登入和登出功能(就像 Django 的 contrib.auth 套件一樣)作為 channels.auth.login 和 channels.auth.logout。在您的消費者(consumer)中,您可以使用 await login(scope, user, backend=None) 來登入一個使用者。這要求您的 scope 中有一個 session 物件;最好的方法是確保您的消費者被包裹在 SessionMiddlewareStack 或 AuthMiddlewareStack 中。您可以使用 async 函數 logout(scope) 來登出一個使用者。

WebSocket Consumer 變更登入狀態後,session 不會自動持久化,必須另外保存。同步 Consumer 可呼叫 session.save();非同步 Consumer 應使用支援的 asave(),或像下例透過 database_sync_to_async 包裝同步的 save,避免直接在事件迴圈中執行同步資料庫操作。

from channels.auth import login

class ChatConsumer(AsyncWebsocketConsumer):

    ...

    async def receive(self, text_data):
        ...
        # login the user to this session.
        await login(self.scope, user)
        # save the session (if the session backend does not access the db you can use `sync_to_async`)
        await database_sync_to_async(self.scope["session"].save)()

當從同步函式中調用 `login(scope, user)`、`logout(scope)` 或 `get_user(scope)` 時,您需要將它們包裝在 `async_to_sync` 中,因為我們僅提供異步版本:

from asgiref.sync import async_to_sync
from channels.auth import login

class SyncChatConsumer(WebsocketConsumer):

    ...

    def receive(self, text_data):
        ...
        async_to_sync(login)(self.scope, user)
        self.scope["session"].save()

如果您正在使用長時間運行的消費者、WebSocket 或長輪詢 HTTP,可能會發生在您的消費者運行期間用戶在其他地方登出了他們的會話。您可以定期使用 `get_user(scope)` 來確保用戶仍然處於登入狀態。

4. 社群專案 – Django Channels auth token middlewares

在官方文件上列出的Community Projects,基於Django Channels進行開發,其中channels-auth-token-middlewares 是 Django Channels 的一個中介軟體,用於處理身份驗證。這包括使用 Django REST framework 的 token authentication middleware 和 SimpleJWT 的中介軟體,如 QueryStringSimpleJWTAuthTokenMiddleware,為 WebSocket 的身份驗證而設計。

使用時先執行指令安裝Python套件,pip install channels-auth-token-middlewares,並在settings的INSTALLED_APPS中加入channels_auth_token_middlewares。

以下節錄幾個用法範例:

from channels.routing import ProtocolTypeRouter, URLRouter

from channels_auth_token_middlewares.middleware import DRFAuthTokenMiddleware


application = ProtocolTypeRouter({
    "websocket": DRFAuthTokenMiddleware(
        URLRouter([
            # app paths
        ]),
    ),

})
from channels.routing import ProtocolTypeRouter, URLRouter

from channels_auth_token_middlewares.middleware import SimpleJWTAuthTokenMiddleware


application = ProtocolTypeRouter({
    "websocket": SimpleJWTAuthTokenMiddleware(
        URLRouter([
            # app paths
        ]),
    ),

})

詳細驗證方式與相容性請以 channels-auth-token-middlewares專案的Github 為準。這是社群中介軟體,不是 Channels 內建功能;實際採用時需確認套件版本、token 傳遞方式與驗證規則,特定需求也可以自行撰寫 ASGI 中介軟體。

C. 安全性

驗證出使用者之後,還要分別處理連線來源及資源授權。WebSocket 會帶入符合瀏覽器 Cookie 規則的資訊,因此私人資料不能只因連線具有 session 就直接開放。

WebSocket 由 HTTP 握手開始,瀏覽器可能在符合 Cookie 規則的情況下帶上既有 session;惡意網站也可能發起跨站連線,因此需要檢查允許的 Origin,並在 Consumer 中確認使用者及其可存取的資源。Origin 檢查與身分驗證各自解決不同問題,不能互相取代。

這可以通過 `channels.security.websocket` 套件及其包含的兩個 ASGI 中介軟體進行:`OriginValidator` 和 `AllowedHostsOriginValidator`。`OriginValidator` 允許您限制每個 WebSocket 發送的 Origin 標頭的合法選項,以指出其來源。只需將它包裹在您的 WebSocket 應用程式代碼周圍,並將有效域名的列表作為第二個參數傳遞給它。您可以僅傳遞一個域名(例如,.allowed-domain.com)或一個完整的來源,以 scheme://domain[:port] 的格式(例如,http://allowed-domain.com:80)進行傳遞。Port 是可選的,但建議使用。

from channels.security.websocket import OriginValidator

application = ProtocolTypeRouter({

    "websocket": OriginValidator(
        AuthMiddlewareStack(
            URLRouter([
                ...
            ])
        ),
        [".goodsite.com", "http://.goodsite.com:80", "http://other.site.com"],
    ),
})

OriginValidator 的 * 表示允許任何來源,不是進行網域解析;若 WebSocket 會傳送私人資料,就不應將它視為原本來源限制的等價替代。

通常,您想要限制的域集與Django的`ALLOWED_HOSTS`設置相同,該設置對Host標頭執行類似的安全檢查。因此,`AllowedHostsOriginValidator`使您可以使用此設置而無需重新宣告。

from channels.security.websocket import AllowedHostsOriginValidator

application = ProtocolTypeRouter({

    "websocket": AllowedHostsOriginValidator(
        AuthMiddlewareStack(
            URLRouter([
                ...
            ])
        ),
    ),
})

AllowedHostsOriginValidator 會自動允許本地連線通過,如果網站處於 DEBUG 模式,這與 Django 的主機驗證類似。

關於CSRF風險,可以參考以下方式進一步保障安全性:

  1. 在WebSocket連接設置中自行檢查CSRF令牌:當WebSocket初始連接進行時,可以將CSRF令牌作為請求的一部分發送,並在服務器端檢查其有效性。
  2. 應用使用者身分驗證:透過既有的安全 session Cookie 或經驗證的 token 確認使用者,不要額外把 session 密鑰放到 URL。若使用 query string 傳 token,還需考慮日誌記錄、有效期限與撤銷方式。
  3. 限制WebSocket的作用域與權限:基於用戶的角色或權限限制他們可通過WebSocket訪問的資源和數據。這可以阻止已認證用戶執行未授權的操作。
  4. 嚴格的連接速率限制:通過限制單個用戶短時間內可以開啟的WebSocket連接數量,以及數據發送頻率,從而減少由惡意用戶造成的拒絕服務(DoS)風險。

這些措施需要一起落在握手與訊息處理流程:Origin 限制控制網頁來源,驗證確認使用者,資源權限限制其可做的操作,速率與訊息大小限制則協助管理資源使用。

D. 總結

Channels 的 session、驗證與來源檢查中介軟體可分層組合:SessionMiddlewareStack 提供 session,AuthMiddlewareStack 再加入使用者資訊,OriginValidator 或 AllowedHostsOriginValidator 限制允許的來源。WebSocket 變更 session 時仍需自行保存,訊息處理也應另外檢查資源權限與使用限制;範例中的自訂 ID 中介軟體僅用來說明介面,不能直接當作安全的登入機制。