身份认证中间件

身份认证中间件用于识别用户身份，保护 API 和页面资源，是安全开发的基础。

请求管道与中间件流程图

下面以典型的中间件管道为例，展示请求从进入到响应的完整流程：

类比说明

• 认证中间件如同物流中心的守卫，负责验证快递员是否有资格进入物流中心（身份是否合法）
• 快递员身份合法前提下，导航仪（路由中间件）带领快递员，找到对应的快递（终结点）
• 此时保险柜（授权中间件）再次验证快递员是否有权限取的快递，授权开柜，取的所需的快递（终结点）

快速启动

只需 4 步即可集成认证服务：

import spire_web_hosting.*
import spire_web_http.*
import spire_web_authentication.*

main() {
    // 1. 构建Web主机
    let builder = WebHost.createBuilder()

    // 2. 注册认证服务
    builder.services.addAuthentication()
    let host = builder.build()

    // 3. 启用认证中间件
    host.useAuthentication()

    // 4. 启动主机
    host.run()
}

添加依赖

需要在依赖配置文件(cjpm.toml)中添加如下依赖：

[dependencies]
  spire_web_http = { path = "/spire_web_http"}
  spire_web_hosting = { path = "/spire_web_hosting"}
  spire_web_authentication = { path = "/spire_web_authentication"}
  spire_extensions_injection = { path = "/spire_extensions_injection"}

认证方案扩展

支持多种认证方式（如 Cookie、JWT、OIDC 等）：

import spire_web_hosting.*
import spire_web_http.*
import spire_web_authentication.*
import spire_web_jwtbearer.*

main() {
    // 1. 创建Web主机构建器
    let builder = WebHost.createBuilder()

    // 2. 注册认证服务，并添加JWT Bearer方案
    builder.services.addAuthentication({ options =>
        // 设置默认认证方案为"jwt"
        options.defaultScheme = "jwt"
    }).addJwtBearer("jwt", { options =>
        // 配置JWT参数
        options.authority = "https://demo.identity" // 身份认证服务器地址
        options.audience = "api"                    // 令牌受众
        // 如有需要可配置更多参数，如options.requireHttpsMetadata = false
    })

    // 3. 构建主机
    let host = builder.build()

    // 4. 启用认证中间件
    host.useAuthentication()

    // 5. 配置受保护的API路由
    host.useEndpoints({ endpoints =>
        // 需要认证的接口
        endpoints.mapGet("/secure", [Authorize()], context => {
            context.response.write("已通过JWT认证，访问成功！")
        })
        // 公共接口
        endpoints.mapGet("/public", context => {
            context.response.write("无需认证即可访问。")
        })
    })

    // 6. 启动主机
    host.run()
}

认证流程说明

• 认证中间件会自动解析请求头、Cookie 等，识别用户身份
• 认证失败时可返回 401 Unauthorized
• 可结合授权中间件实现细粒度访问控制

常见问题与建议

• 认证中间件应在授权、路由等中间件之前注册。
• 生产环境务必启用 HTTPS，防止凭据泄露。
• 认证失败应返回明确的错误信息，便于前端处理。
• 可结合第三方登录、单点登录等扩展认证能力。

最佳实践

• 推荐 JWT 用于 API，Cookie 用于 Web 页面。
• 认证信息建议短时有效，降低风险。
• 认证相关配置（密钥、地址等）应安全存储。