Authentication

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

Authentication

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

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

HTTP 传输身份验证

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

Bearer token 身份验证

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

openrpc.yml

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

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

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

API Key 身份验证

配置 API Key 身份验证：

openrpc.yml

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

在 SDK 中的使用方式：

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

Basic 身份验证

配置 Basic 身份验证：

openrpc.yml

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

在 SDK 中的使用方式：

1 const 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

1 methods:
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

1 servers:
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: []
11 components:
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

1 methods:
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

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

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

身份验证的错误处理

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

openrpc.yml

1 components:
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 消费者提供清晰的身份验证反馈。

HTTP 传输身份验证

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

Bearer token 身份验证

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

openrpc.yml

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

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

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

API Key 身份验证

配置 API Key 身份验证：

openrpc.yml

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

在 SDK 中的使用方式：

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

Basic 身份验证

配置 Basic 身份验证：

openrpc.yml

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

在 SDK 中的使用方式：

1 const 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

1 methods:
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

1 servers:
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: []
11 components:
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

1 methods:
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

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

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

身份验证的错误处理

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

openrpc.yml

1 components:
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 消费者提供清晰的身份验证反馈。

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

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

1	methods:
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'

1	servers:
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: []
11	components:
12	securitySchemes:
13	wsAuth:
14	type: apiKey
15	in: query
16	name: token
17	description: Authentication token passed as query parameter

1	methods:
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

1	components:
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"