迁移ATProtocol SDK至Java时PAR请求报client_assertion_type缺失错误排查

核心错误原因排查及解决步骤 #

1. JWT断言的aud字段配置错误 #

使用private_key_jwt认证时，JWT的aud（受众）必须严格匹配PAR端点URL：https://bsky.social/oauth/par，不能填成token端点地址。若aud不匹配，服务端会无法验证断言有效性，进而误判为client_assertion_type参数缺失。

2. JWT签名算法与客户端元数据不匹配 #

确认生成client_assertion时使用的签名算法是ES256，必须与client-metadata.json中token_endpoint_auth_signing_alg字段的值完全一致。算法不匹配会导致服务端拒绝识别断言，触发错误提示。

3. 客户端元数据的可访问性与格式问题 #

• 确保https://myapi.com/bluesky/client-metadata.json是公开可访问的，Bluesky的OAuth服务需要拉取该元数据验证客户端配置；
• 修正JSON格式：你提供的元数据中存在转义双引号（"），实际部署时需替换为普通双引号，保证JSON语法合法。正确格式示例：

  {
      "client_id": "https://myapi.com/bluesky/client-metadata.json",
      "application_type": "web",
      "redirect_uris": ["https://myapi.com/v3/social/api/connect/redirect"],
      "response_types": ["code"],
      "grant_types": ["authorization_code", "refresh_token"],
      "scope": "atproto transition:generic",
      "token_endpoint_auth_method": "private_key_jwt",
      "token_endpoint_auth_signing_alg": "ES256",
      "dpop_bound_access_tokens": true,
      "jwks": {
          "keys": [
              {
                  "crv": "P-256",
                  "x": "[val1]",
                  "y": "[val2]",
                  "kid": "v1",
                  "kty": "EC",
                  "use": "sig"
              }
          ]
      }
  }
  

4. 验证curl请求的参数传递 #

尝试直接使用预编码的参数字符串发起请求，排除--data-urlencode可能带来的编码异常：

curl --location 'https://bsky.social/oauth/par' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=[signed_JWT_assertion]&client_id=https%3A%2F%2Fmyapi.com%2Fbluesky%2Fclient-metadata.json&redirect_uri=https%3A%2F%2Fmyapi.com%2Fv3%2Fsocial%2Fapi%2Fconnect%2Fredirect&response_type=code&scope=atproto+transition%3Ageneric&code_challenge=MqQ20leWJI2CClySgAT5_oZ1GyFjsCfywr35F6AIjt4&code_challenge_method=S256&state=12345'

额外验证项 #

用JWT解析工具解码你的client_assertion，检查以下字段：

• iss：必须等于client_id（即元数据URL）
• sub：必须等于client_id
• aud：必须是PAR端点URL
• exp：过期时间需晚于当前时间
• kid：必须与元数据中jwks.keys[0].kid完全一致

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