GraphOS 路由器中的 JWT 验证

验证对于防止非法访问并保护您的图至关重要。The GraphOS Router支持通过JSON Web Token (JWT) 和 JSON Web Key (JWK) 标准。这种支持与流行的身份提供者（IdP），如 Okta 和 Auth0 兼容。

通过启用 JWT 验证，您可以在边缘阻止恶意流量，而不是依赖于标题转发将令牌传播到您的子图。

JWT身份验证的工作原理

以下是在GraphOS Router中使用JWT基于身份验证的高级步骤：

1. 每当客户端与您的系统进行身份验证时，您的身份提供者（IdP）都会向该客户端颁发一个有效的JSON Web令牌（JWT）。

2. 在后续请求您的路由器时，经过身份验证的客户端会在指定的HTTP头中提供其JWT。

3. 每当您的路由器收到客户端请求时，它会从指定的头（如果有）中提取JWT。

   • 如果没有JWT存在，请求将继续。您可以在稍后的阶段拒绝没有附加JWT的请求（见下文）。

4. 您的路由器使用相应的JSON Web密钥（JWK）验证提取的JWT。

   • 您的路由器从其配置文件中指定的URL获取其所有已知的JWK。每个URL在其JWK集中提供其密钥，JWK集是一个名为JWK Set或JWKS）中。
   • 如果验证失败，路由器将拒绝请求。这可以发生在JWT格式不正确或过期超过60秒（此窗口考虑了同步问题）的情况下。

5. 路由器从经过验证的JWT中提取所有断言并将其包含在请求的上下文中，使它们可供您的路由器自定义使用，例如Rhai脚本。

6. 您的自定义可以根据提取的断言的详细信息以不同的方式处理请求，或者您可以将断言传播到子图以启用更精细的访问控制。

   • 例如，见下文。

开启它

如果您使用自己的自定义IdP，需要高级配置。

否则，如果您通过流行的第三方IdP（Auth0、Okta、PingOne等）颁发JWT，则在您的路由器中启用JWT身份验证是一个两步过程，如下所述。

1. 在路由器的YAML配置文件中设置JWT身份验证的配置选项，在身份验证密钥：

   YAML

   router.yaml

   1
   authentication:
   2
     router:
   3
       jwt:
   4
         jwks: # This key is required.
   5
           - url: https://dev-zzp5enui.us.auth0.com/.well-known/jwks.json
   6
             issuer: <optional name of issuer>
   7
             poll_interval: <optional poll interval>
   8
             headers: # optional list of static headers added to the HTTP request to the JWKS URL
   9
               - name: User-Agent
   10
                 value: router
   11
         # These keys are optional. Default values are shown.
   12
         header_name: Authorization
   13
         header_value_prefix: Bearer
   14
         # array of alternative token sources
   15
         sources:
   16
           - type: header
   17
             name: X-Authorization
   18
             value_prefix: Bearer
   19
           - type: cookie
   20
             name: authz

   复制

   以下选项的文档如下。

2. 在启动时将以下所有内容传递给router可执行文件：

   • 路由器的YAML配置文件路径（通过--config选项）
   • 路由器应使用的GraphOS变体的图引用（通过APOLLO_GRAPH_REF环境变量）
   • 一个图API密钥，启用路由器通过GraphOS进行认证以获取其超图模式（通过APOLLO_KEY环境变量）
   Bash

   1
   APOLLO_GRAPH_REF=docs-example-graph@main APOLLO_KEY="..." ./router --config router.yaml

   复制

路由器启动时，会显示一条确认使用了哪些jwks的日志信息：

1
2023-02-03T14:05:28.018932Z  INFO JWT authentication using JWKSets from jwks=[{ url: "file:///router/jwks.json" }]

配置选项

以下配置选项受支持

1
authentication:
2
  router:
3
    jwt:
4
      jwks:
5
        - url: https://dev-zzp5enui.us.auth0.com/.well-known/jwks.json
6
      sources:
7
        - type: header
8
          name: X-Authorization
9
          value_prefix: Bearer
10
        - type: cookie
11
          name: authz

与JWT声明一起工作

在GraphOS Router验证客户端请求的JWT之后，它将该令牌的声明添加到请求的上下文中的此键：apollo_authentication::JWT::claims

如果应该拒绝未认证的请求，则可以按以下方式配置路由器：

1
authorization:
2
  require_authentication: true

声明是JWT作用域的个别细节。它们可能包括相关用户的ID、分配给该用户的任何角色以及JWT的过期时间。查看规范。

由于声明被添加到上下文中，您可以定义根据每个请求的声明细节处理每个请求的自定义逻辑。您可以在supergraph服务级别（有关这些选项的更多信息，请参阅路由器自定义）中定义此逻辑。

以下是2个示例Rhai脚本自定义，展示了路由器可以根据请求的声明执行的操作。

示例：将声明作为标题转发到子图

以下是一个示例Rhai脚本，该脚本将JWT的声明通过HTTP头（每个声明一个头）转发到单个子图。这使每个子图能够定义逻辑来处理（或可能拒绝）基于声明细节的 incoming请求。此功能应在您的main.rhai文件中导入和运行。

1
fn process_request(request) {
2
    let claims = request.context[Router.APOLLO_AUTHENTICATION_JWT_CLAIMS];
3
    if claims ==() {
4
      throw #{
5
        status: 401
6
      };
7
    }
8
    // Add each claim key-value pair as a separate HTTP header.
9
    // Note that that claims that are not present in the JWT will be added as empty strings.
10
    let claim_names = ["claim_1", "claim_2", "claim_3"];
11
    for claim_name in claim_names {
12
      let claim = claims[claim_name];
13
      claim = if claim == () {""} else {claim};
14
      request.subgraph.headers[claim_name] = claim;
15
    }
16
}

示例：将声明作为 GraphQL 扩展转发到 subgraph

以下是一个 Rhai 脚本 的示例，该脚本通过 GraphQL 扩展将 JWT 的声明转发到单个 subgraph。这允许每个 subgraph 定义逻辑来处理（或拒绝）基于声明细节的传入请求。此函数应导入到您的 main.rhai 文件中运行。

1
fn process_request(request) {
2
    let claims = request.context[Router.APOLLO_AUTHENTICATION_JWT_CLAIMS];
3
    if claims ==() {
4
      throw #{
5
        status: 401
6
      };
7
    }
8
    request.subgraph.body.extensions["claims"] = claims;
9
}

示例：抛出针对无效声明的错误

以下是一个 Rhai 脚本 的示例，该脚本为不同的无效 JWT 声明细节抛出不同的错误。此函数应导入到您的 main.rhai 文件中运行。

1
fn process_request(request) {
2
    // Router.APOLLO_AUTHENTICATION_JWT_CLAIMS is a Rhai-scope
3
    // constant with value `apollo_authentication::JWT::claims`
4
    let claims = request.context[Router.APOLLO_AUTHENTICATION_JWT_CLAIMS];
5
    if claims == () || !claims.contains("iss") || claims["iss"] != "https://idp.local" {
6
        throw #{
7
            status: 401,
8
            message: "Unauthorized"
9
        };
10
    }
11
    // Happy path: We have valid claims from the correct idP.
12
}

示例 main.rhai

为了使用上述 Rhai 示例，您必须像这样将它们导入到您的 main.rhai 中：

1
import "claims_validation" as claims_validation;
2
import "claims_forwarding" as claims_forwarding;
3

4
fn supergraph_service(service) {
5
    let request_callback = |request| {
6
        claims_validation::process_request(request);
7
    };
8

9
    service.map_request(request_callback);
10
}
11

12
fn subgraph_service(service, subgraph) {
13
    let request_callback = |request| {
14
        claims_forwarding::process_request(request);
15
    };
16

17
    service.map_request(request_callback);
18
}

通过协处理器进行声明增强

您可能需要比 JSON 网络令牌提供的信息更多的信息。例如，令牌的声明可能包括用户 ID，然后您可以使用这些 ID 来查找用户角色。对于这种情况，您可以使用 协处理器 增强您的 JSON 网络令牌的声明。

1
authentication:
2
  router:
3
    jwt:
4
      jwks:
5
        - url: "file:///etc/router/jwks.json"
6

7
coprocessor:
8
  url: http://127.0.0.1:8081
9
  router:
10
    request:
11
      context: true

1
{
2
  "version": 1,
3
  "stage": "RouterRequest",
4
  "control": "continue",
5
  "id": "d0a8245df0efe8aa38a80dba1147fb2e",
6
  "context": {
7
    "entries": {
8
      "apollo_authentication::JWT::claims": {
9
        "exp": 10000000000,
10
        "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
11
      }
12
    }
13
  },
14
  "method": "POST"
15
}

1
{
2
  "version": 1,
3
  "stage": "RouterRequest",
4
  "control": "continue",
5
  "id": "d0a8245df0efe8aa38a80dba1147fb2e",
6
  "context": {
7
    "entries": {
8
      "apollo_authentication::JWT::claims": {
9
        "exp": 10000000000,
10
        "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a",
11
        "scope": "profile:read profile:write"
12
      }
13
    }
14
  }
15
}

创建自己的 JWKS（高级）

GraphOS Router通过以下地址从您指定的配置选项中获取它使用的每个JSON Web密钥（JWK）：jwks。每个地址必须提供一个包含JWK集（或称为JWKS）的有效JWK的JSON对象。

请查阅您的IdP文档以获取传递给路由器的JWKS URL。

为了向您的路由器提供JWKS，请配置您的IdP服务在其有效JWK集合更改时（例如，当JWK到期或轮换时）执行以下操作：

1. 生成一个包含路由器用于执行令牌验证的每个JWK详细信息的有效JWKS对象。
2. 将JWKS对象写入路由器可以通过file://或https://URL访问的位置。
   • ⚠️ 如果任何JWK使用对称签名算法（如HS256），则始终使用file://URL。对称签名算法使用一组共享密钥绝对不应该通过网络访问。

JWKS格式

JWKS是一个具有单级属性的JSON对象：keys。keys的值是一个对象数组，每个对象代表单个JWK：

1
{
2
  "keys": [
3
    {
4
      // These JWK properties are explained below.
5
      "kty": "RSA",
6
      "alg": "RS256",
7
      "kid": "abc123",
8
      "use": "sig",
9
      "n": "0vx7agoebGcQSuu...",
10
      "e": "AQAB"
11
    }
12
  ]
13
}

通常情况下，keys数组只包含一个JWK，如果您的IdP正在轮换密钥，有时可能包含两个。

JWK对象参考

JWK对象属性分为两大类

• 通用属性。无论您使用哪种签名算法，您都会在JWK对象中包含这些属性。
• 算法特定属性。您只为使用对应签名算法的JWK对象包含这些属性。

通用属性

以下属性适用于任何JWK：

特定算法的属性

RSA

1
{
2
  // Universal properties
3
  "kty": "RSA",
4
  "alg": "RS256",
5
  "kid": "abc123",
6

7
  // Algorithm-specific properties
8
  "n": "0vx7agoebGcQSuu...", // Shortened for readability
9
  "e": "AQAB"
10
}

EC（椭圆曲线）

1
{
2
  // Universal properties
3
  "kty": "EC",
4
  "alg": "ES256",
5
  "kid": "afda85e09a320cf748177874592de64d",
6
  "use": "sig",
7

8
  // Algorithm-specific properties
9
  "crv": "P-256",
10
  "x": "opFUViwCYVZLmsbG2cJTA9uPvOF5Gg8W7uNhrcorGhI",
11
  "y": "bPxvCFKmlqTdEFc34OekvpviUUyelGrbi020dlgIsqo"
12
}

对称密钥算法（如HMAC）

1
{
2
  // Universal properties
3
  "kty": "oct",
4
  "alg": "HS256",
5
  "kid": "key1",
6
  "use": "sig",
7

8
  // Symmetric-algorithm-specific property
9
  "k": "c2VjcmV0Cg" // ⚠️ This is a base64-encoded shared secret! ⚠️
10
}

JWK匹配

要匹配传入的JWT与其对应的JWK，路由器会按从高到低的“匹配特定级别”进行匹配，直到确定其JWK集中的第一个兼容JWK：

1. JWT和JWK的kid和alg完全匹配。
2. JWT和JWK匹配kid，且JWT的alg与JWK的kty兼容。
3. JWT和JWK的alg完全匹配。
4. JWT的alg与JWK的kty兼容。

这种匹配策略是必要的，因为某些身份提供者（IdP）在它们的JWKS中未指定alg或kid值。然而，它们总是指定一个kty，因为该值由JWK规范要求。

转发JWT到子图

由于GraphOS路由器处理验证传入JWT，您很少需要将整个JWT传递到单个subgraphs。相反，您通常希望将JWT 断言 传递到子图以实现精细粒度的访问控制。

如果您确实需要将整个JWT传递到subgraphs，您可以通过GraphOS路由器的一般用途HTTP头传播设置来实现。

可观测性

如果您的router启用了追踪，JWT身份验证插件有自己的追踪跨度：authentication_plugin

如果您的router启用了通过Prometheus的指标收集，JWT身份验证插件提供并导出了以下指标：

• apollo_authentication_failure_count
• apollo_authentication_success_count

这些指标具有以下形态

1
# HELP apollo_authentication_failure_count apollo_authentication_failure_count
2
# TYPE apollo_authentication_failure_count counter
3
apollo_authentication_failure_count{kind="JWT",service_name="apollo-router"} 1
4

5
# HELP apollo_authentication_success_count apollo_authentication_success_count
6
# TYPE apollo_authentication_success_count counter
7
apollo_authentication_success_count{kind="JWT",service_name="apollo-router"} 11