身份验证 | Fern Documentation

身份验证方案的配置在 api.yml 文件中进行。所有 Fern 生成的 SDK 都支持直接配置和环境变量来配置身份验证凭据。

$ fern/
$ ├─ fern.config.json # 根级别配置
$ ├─ generators.yml # 你正在使用的生成器
$ └─ definition/
$   ├─ api.yml  # API 级别配置
$   └─ imdb.yml # 端点、类型和错误

要添加身份验证方案，请在 auth-schemes 部分下指定身份验证方法。

api.yml

1 auth-schemes:
2   AuthScheme:                     
3     ...

要在所有端点中应用身份验证方案，请在 api.yml 文件的 auth 部分中引用 auth-scheme。

api.yml

1 auth: AuthScheme                  
2 auth-schemes:
3   AuthScheme:                     
4     ...

Bearer 身份验证

首先在 api.yml 中定义一个 Bearer 身份验证方案：

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer

这将生成一个 SDK，用户需要提供一个名为 token 的必需参数。

index.ts

1 const client = new Client({
2   token: "ey34..."
3 })

如果你想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer
5     token:
6       name: apiKey 
7       env: PLANTSTORE_API_KEY

生成的 SDK 会是这样：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // token 已被重命名为 apiKey
5 client = new Client({
6   apiKey: "ey34..."
7 })

基本身份验证

首先在 api.yml 中定义一个 Basic 身份验证方案：

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic

这将生成一个 SDK，用户需要提供名为 username 和 password 的必需参数。

index.ts

1 const client = new Client({
2   username: "joeschmoe"
3   password: "ey34..."
4 })

如果你想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic
5     username:
6       name: clientId
7       env: PLANTSTORE_CLIENT_ID
8     password:
9       name: clientSecret
10       env: PLANTSTORE_CLIENT_SECRET

生成的 SDK 会是这样：

index.ts

1 // 使用 process.env.PLANTSTORE_CLIENT_ID 和 process.env.PLANTSTORE_CLIENT_SECRET
2 let client = new Client(); 
3 
4 // 参数已被重命名
5 client = new Client({
6   clientId: "joeschmoe", 
7   clientSecret: "ey34..."
8 })

自定义头部（例如 API 密钥）

你也可以使用自定义头部创建自己的身份验证方案。

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string

这将生成一个 SDK，用户需要提供一个名为 apiKey 的必需参数。

index.ts

1 const client = new Client({
2   xApiKey: "ey34..."
3 })

如果你想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string
6     name: apiKey
7     env: PLANTSTORE_API_KEY

生成的 SDK 会是这样：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // 参数已被重命名
5 client = new Client({
6   apiKey: "ey34..."
7 })

OAuth 客户端凭据

团队版、专业版和企业版功能

此功能仅适用于团队版（文档）、专业版（SDK）和企业版计划。要开始使用，请联系 support@buildwithfern.com。

如果你的 API 使用 OAuth，你可以在 api.yml 中指定 oauth 方案，并在单独的 auth.yml 文件中定义令牌检索端点（示例）。

api.yml

1 name: api
2 
3 imports:
4   auth: auth.yml
5 
6 auth: OAuthScheme
7 auth-schemes:
8   OAuthScheme:
9     scheme: oauth
10     type: client-credentials
11     client-id-env: YOUR_CLIENT_ID
12     client-secret-env: YOUR_CLIENT_SECRET
13     get-token:
14       endpoint: auth.getTokenWithClientCredentials
15       request-properties:
16         client-id: $request.client_id         # 格式: parameter-name: $request.property_name
17         client-secret: $request.client_secret # 格式: parameter-name: $request.property_name            
18       response-properties:
19         access-token: $response.access_token  # 格式: parameter-name: $response.property_name
20         expires-in: $response.expires_in      # 格式: parameter-name: $response.property_name

request-properties 和 response-properties 将 OAuth 标准参数映射到在 auth.yml 中定义的实际端点的请求和响应字段名称。

如果设置了 expires-in 属性，生成的 OAuth 令牌提供程序将在令牌过期时自动刷新令牌。否则，假设访问令牌永久有效。

相应的 auth.yml 文件（示例）定义了令牌端点：

auth.yml

1 types:
2   TokenResponse:
3     docs: |
4       OAuth 令牌响应。
5     properties:
6       access_token: string
7       expires_in: integer
8       refresh_token: optional<string>
9 
10 service:
11   auth: false
12   base-path: /
13   endpoints:
14     getTokenWithClientCredentials:
15       path: /token
16       method: POST
17       request:
18         name: GetTokenRequest
19         body:
20           properties:
21             client_id: string
22             client_secret: string
23             audience: literal<"https://api.example.com">
24             grant_type: literal<"client_credentials">
25             scope: optional<string>
26       response: TokenResponse

如果你的 OAuth 服务器托管在与主 API 不同的 URL 上，你可以使用每个环境多个 URL 为身份验证和 API 调用指定单独的基础 URL。

有了这些，所有的 OAuth 逻辑都会在生成的 SDK 中自动处理。只要你配置了这些设置，你的客户端将自动检索访问令牌并根据需要刷新它。

在使用文档 playground 时，可以选择设置 token-header 和 token-prefix 来自定义头部键名和头部值前缀，以匹配 API 身份验证方案的预期格式。

例如，以下配置将产生头部 Fern-Authorization: Fern-Bearer <token>：

api.yml

1 auth-schemes:
2   OAuthScheme:
3     scheme: oauth
4     type: client-credentials
5     token-header: Fern-Authorization
6     token-prefix: Fern-Bearer
7     get-token:
8       ...