WSO2 APIM 4.0.0自定义中介无法传递API调用方终端用户名至后端

问题背景 #

测试WSO2 APIM 4.0.0发布者门户的自定义中介功能，意图将API调用方的终端用户名传递至后端。参考旧文档创建了自定义请求序列，但后端收到的自定义user请求头为空。

自定义序列代码：

<sequence name="test" xmlns="http://ws.apache.org/ns/synapse"> 
<header name="user" expression="substring-before(get-property('api.ut.userId'), '@')" scope="transport"/>
</sequence>

后端测试API（Spring Boot）会打印所有请求头，但user头为空：

@RestController
@RequestMapping("greet")
public class GreetApi {

    @GetMapping
    public String greet(@RequestHeader Map<String,String> headers) {
        System.out.println(headers);
        return "Greetings";
    }
}

后端控制台输出示例：

{activityid=3221a82e-0679-4f6e-9a36-bd9abdefb6a4, accept=*/*, host=localhost:8080, user=, connection=Keep-Alive, user-agent=Synapse-PT-HttpComponents-NIO}

问题原因与解决步骤 #

1. 确认调用身份认证状态 #

api.ut.userId等用户属性仅在已认证调用时存在，如果是匿名调用（未携带令牌/认证信息），这些属性值为空，导致user头无内容。

• 解决：调用API时使用OAuth2令牌、Basic Auth等已认证方式，确保用户身份被正确识别。

2. 替换为APIM 4.0.0兼容的用户属性 #

旧文档针对的是早期APIM版本，4.0.0中api.ut.userId属性已不再推荐使用，需替换为当前版本支持的属性：

• 推荐使用username属性，修改序列如下：

<sequence name="test" xmlns="http://ws.apache.org/ns/synapse"> 
    <header name="user" expression="substring-before(get-property('username'), '@')" scope="transport"/>
</sequence>

• 若使用OAuth2 JWT令牌，也可直接从JWT的sub claim提取：

<sequence name="test" xmlns="http://ws.apache.org/ns/synapse">
    <property name="username" expression="json-eval($.sub)" scope="default" type="STRING"/>
    <header name="user" expression="get-property('username')" scope="transport"/>
</sequence>

3. 验证属性值是否存在 #

添加日志到自定义序列，确认目标属性是否有值，便于排查：

<sequence name="test" xmlns="http://ws.apache.org/ns/synapse"> 
    <log level="custom">
        <property name="api.ut.userId" expression="get-property('api.ut.userId')"/>
        <property name="username" expression="get-property('username')"/>
        <property name="synapse.ut.userName" expression="get-property('synapse.ut.userName')"/>
    </log>
    <header name="user" expression="substring-before(get-property('username'), '@')" scope="transport"/>
</sequence>

查看APIM的wso2carbon.log日志，确认哪个属性包含正确的用户名。

4. 检查APIM头过滤配置 #

APIM默认可能过滤部分自定义请求头，需确保user头允许被传递到后端：

• 编辑repository/conf/deployment.toml，添加如下配置：

[apim.gateway.environment]
allow_all_headers = true

• 或指定允许的头列表（更安全）：

[apim.gateway.environment]
allowed_headers = ["user", "accept", "host"]

配置完成后重启WSO2 APIM生效。

5. 确认序列配置位置 #

确保自定义序列被添加到API的请求中介位置，而非响应中介，且序列处于启用状态。

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