如何在AWS Smithy中规范描述操作授权及身份信息传递

问题背景 #

从Smithy的常见实践来看，工程师定义操作与输入结构时通常不会显式声明操作执行者。例如以下Smithy定义：

@auth([httpBearerAuth])
@http(method: "PUT", uri: "/api/v1/tasks/{id}", code: 200)
operation PutTask {
    input: PutTaskInput
    output: Unit
}

structure PutTaskInput {
    @httpLabel
    @required
    id: TaskId

    @httpPayload
    @required
    body: TaskBody
}

生成的Python HTTP服务代码如下：

class TasksService(HttpEndpoint):
    def put_task(id, body):
        raise NotImplementedError("PutTask operation is not implemented")

现需以符合Smithy惯例的方式修改定义，使生成的代码包含author参数，用于授权判断与业务处理，期望生成代码示例：

class TasksService(HttpEndpoint):
    # 需要知道操作执行者身份
    # 根据执行者信息决定是否拒绝请求，或按特定逻辑处理任务
    def put_task(author, id, body):
        raise NotImplementedError("PutTask operation is not implemented")

符合Smithy惯例的解决方案 #

方法1：在输入结构中添加author字段并绑定认证上下文

Smithy支持通过@context注解将认证上下文数据注入输入参数。你可以在PutTaskInput中添加author字段，并用@context标记其来自认证上下文：

@auth([httpBearerAuth])
@http(method: "PUT", uri: "/api/v1/tasks/{id}", code: 200)
operation PutTask {
    input: PutTaskInput
    output: Unit
}

structure PutTaskInput {
    @httpLabel
    @required
    id: TaskId

    @httpPayload
    @required
    body: TaskBody

    // 从认证上下文注入执行者标识
    @context
    @required
    author: PrincipalId
}

其中PrincipalId可定义为字符串类型或自定义结构，用于表示执行者的唯一标识。代码生成器会自动将认证流程中解析出的执行者信息注入author参数，最终生成的Python方法会包含该参数。

方法2：定制代码生成器扩展

如果使用的Smithy代码生成器支持扩展（如Smithy Python的自定义插件），可以通过定制扩展逻辑自动添加author参数：

• 实现自定义Smithy插件，在操作处理阶段为输入自动添加author参数
• 配置代码生成器启用该插件，确保生成的方法包含author参数

这种方式适合有深度定制需求的场景。

方法3：通过@auth注解配置执行者提取逻辑

部分Smithy代码生成器支持在@auth注解中添加自定义属性，指定如何从认证凭证中提取执行者信息。例如：

@auth([{
    name: "httpBearerAuth",
    properties: {
        principalExtractor: "extract_author_from_token"
    }
}])
@http(method: "PUT", uri: "/api/v1/tasks/{id}", code: 200)
operation PutTask {
    input: PutTaskInput
    output: Unit
}

这种方式需要代码生成器支持自定义属性解析，生成的方法会自动包含author参数，其值由指定的extract_author_from_token逻辑从Bearer Token中提取。

内容的提问来源于stack exchange，提问作者chuwy