OpenRPC

Authentication

为 JSON-RPC API 建模身份验证方案，包括 Bearer、Basic 和 API Key 身份验证

以 Markdown 格式查看

OpenRPC 中的身份验证可以在服务器级别或方法级别进行配置，具体取决于您的 JSON-RPC 实现。与 REST API 不同，JSON-RPC 通常通过传输层（HTTP 头）或在 JSON-RPC 请求负载中处理身份验证。

HTTP 传输身份验证

当使用 HTTP 作为 JSON-RPC 的传输方式时，您可以使用标准的 HTTP 身份验证方案。

Bearer token 身份验证

为基于 HTTP 的 JSON-RPC 配置 bearer token 身份验证：

openrpc.yml
1servers:
2  - name: production
3    url: https://api.example.com/rpc
4    description: Production JSON-RPC server
5    security:
6      - bearerAuth: []
7components:
8  securitySchemes:
9    bearerAuth:
10      type: http
11      scheme: bearer
12      bearerFormat: JWT

这会生成需要 token 的 SDK 方法：

1const client = new JSONRPCClient({
2  url: "https://api.example.com/rpc",
3  auth: {
4    bearer: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5  }
6});
7
8// 调用 JSON-RPC 方法
9const result = await client.call("calculate.add", { a: 5, b: 3 });

API Key 身份验证

配置 API Key 身份验证：

openrpc.yml
1servers:
2  - name: production
3    url: https://api.example.com/rpc
4    description: Production JSON-RPC server
5    security:
6      - apiKeyAuth: []
7components:
8  securitySchemes:
9    apiKeyAuth:
10      type: apiKey
11      in: header
12      name: X-API-Key

在 SDK 中的使用方式：

1const client = new JSONRPCClient({
2  url: "https://api.example.com/rpc",
3  auth: {
4    apiKey: "your-api-key-here"
5  }
6});

Basic 身份验证

配置 Basic 身份验证：

openrpc.yml
1servers:
2  - name: production
3    url: https://api.example.com/rpc
4    description: Production JSON-RPC server
5    security:
6      - basicAuth: []
7components:
8  securitySchemes:
9    basicAuth:
10      type: http
11      scheme: basic

在 SDK 中的使用方式：

1const client = new JSONRPCClient({
2  url: "https://api.example.com/rpc",
3  auth: {
4    username: "user@example.com",
5    password: "password123"
6  }
7});

方法级别的身份验证

一些 JSON-RPC 实现可能需要为特定方法使用不同的身份验证：

openrpc.yml
1methods:
2  - name: public.getInfo
3    summary: Get public information
4    description: Publicly accessible method (no auth required)
5    params: []
6    result:
7      name: info
8      schema:
9        type: object
10  - name: user.getProfile
11    summary: Get user profile
12    description: Requires user authentication
13    security:
14      - bearerAuth: []
15    params:
16      - name: userId
17        schema:
18          type: string
19        required: true
20    result:
21      name: profile
22      schema:
23        $ref: '#/components/schemas/UserProfile'

WebSocket 身份验证

对于 WebSocket 传输，身份验证通常在连接建立过程中进行：

openrpc.yml
1servers:
2  - name: websocket
3    url: wss://api.example.com/rpc
4    description: WebSocket JSON-RPC server
5    variables:
6      token:
7        description: Authentication token for WebSocket connection
8        default: ""
9    security:
10      - wsAuth: []
11components:
12  securitySchemes:
13    wsAuth:
14      type: apiKey
15      in: query
16      name: token
17      description: Authentication token passed as query parameter

自定义身份验证参数

对于在请求负载内处理身份验证的 JSON-RPC API：

openrpc.yml
1methods:
2  - name: auth.login
3    summary: Authenticate user
4    description: Login method that returns authentication token
5    params:
6      - name: credentials
7        schema:
8          type: object
9          properties:
10            username:
11              type: string
12            password:
13              type: string
14          required:
15            - username
16            - password
17    result:
18      name: authResult
19      schema:
20        type: object
21        properties:
22          token:
23            type: string
24          expiresIn:
25            type: integer
26          refreshToken:
27            type: string

Fern 身份验证扩展

使用 Fern 扩展来自定义身份验证行为：

openrpc.yml
1components:
2  securitySchemes:
3    bearerAuth:
4      type: http
5      scheme: bearer
6      x-fern-token:
7        name: authToken
8        env: AUTH_TOKEN

这允许用户通过环境变量或构造函数参数设置身份验证，使 SDK 更加灵活和安全。

身份验证的错误处理

为身份验证失败定义标准化的错误响应：

openrpc.yml
1components:
2  errors:
3    - code: -32001
4      message: Authentication required
5      data:
6        type: object
7        properties:
8          error:
9            type: string
10            const: "Authentication token is required"
11    - code: -32002
12      message: Invalid authentication
13      data:
14        type: object
15        properties:
16          error:
17            type: string
18            const: "Invalid or expired authentication token"

这些错误代码遵循 JSON-RPC 2.0 约定，同时为 API 消费者提供清晰的身份验证反馈。