mirror of
https://gitee.com/dromara/sa-token.git
synced 2025-06-28 13:34:18 +08:00
284 lines
11 KiB
Markdown
284 lines
11 KiB
Markdown
# API Key 接口调用秘钥
|
||
|
||
API Key（应用程序编程接口密钥） 是一种用于身份验证和授权的字符串代码，通常由服务提供商生成并分配给开发者或用户。它的主要作用是标识调用 API（应用程序编程接口）的请求来源，确保请求的合法性，并控制访问权限。
|
||
|
||
以上是官话，简单理解：API Key 是一种接口调用密钥，类似于会话 token ，但比会话 token 具有更灵活的权限控制。
|
||
|
||
示例仓库地址：[sa-token-demo-apikey](https://gitee.com/dromara/sa-token/tree/master/sa-token-demo/sa-token-demo-apikey) 🔗
|
||
|
||
|
||
|
||
|
||
### 1、需求场景
|
||
|
||
为了帮助大家更好的理解 API Key 的应用场景，我们假设具有以下业务场景：
|
||
|
||
> [!NOTE| label:业务场景]
|
||
> 你们公司开发了一款论坛网站，非常火爆。
|
||
>
|
||
> 某日，你发现一位用户的头像可以随着日期而变化，Ta 的头像总是显示当前最新日期。
|
||
>
|
||
> 这并未引起你的警觉，因为你是一个程序员，在你看来，写一个任务脚本，每天定时调用 API 更新自己的头像是一件非常简单的事情。
|
||
>
|
||
> 一个月后，越来越多的账号“具有了此功能”，仿佛发生了人传人，Ta 们的头像都可以随着日期而变化，而且颜色各不相同，DIY 的不亦乐乎。
|
||
>
|
||
> 这引起了你的怀疑，如此大批账号的自动化更新行为，显然不是 “某个程序员利用定时脚本更新账号信息” 可以解释的。
|
||
>
|
||
> 一番调查之后，你发现了事情的真相，没有灰产公司捣乱，这批账号也不是机器账号，只是有一个公司为你们的网站开发了一款插件。
|
||
>
|
||
> 这款插件的作用是：用户把自己的 账号+密码 保存在插件中，插件便可以定时更新该账号的头像、昵称、资料等信息。
|
||
>
|
||
> 你觉得插件很有意思，但是插件“要求用户提交账号密码”的行为，让你感到很不爽。
|
||
>
|
||
> 总有一些用户为了得到“些许便利”，而出卖自己的账号密码给插件。
|
||
>
|
||
> 随着时间推移，越来越多的第三方公司或个人为你的网站开发插件：有的可以自动更新账号资料、有的可以自动发帖，有的检测到新粉丝就发送消息通知...
|
||
>
|
||
> 最终，不守规矩的插件出现了：一款插件在提供功能的同时，大量收集用户密码等隐私信息，作为不法用途。
|
||
>
|
||
> 为了遏制这种现象，你们公司升级了系统，增加了 IP 校验等风控判断，阻断了这些插件的 API 调用。
|
||
>
|
||
> 似乎……解决了问题？用户再也不会把账号密码交给第三方插件了。
|
||
>
|
||
> 但是插件的需求总是存在的呀，有些用户确实很需要这些插件的能力来提高网站使用体验。
|
||
>
|
||
> 俗话说的好，堵不如疏，既然用户有需求，第三方公司愿意免费打工开发插件，我们何不设计一套授权架构，
|
||
> 既不需要让用户把账号密码交给第三方插件，又能让插件得到一些权限来调用特定 API 为用户服务。
|
||
>
|
||
> API Key 就是为了完成这种“可控式部分授权” 而设计的一种身份凭证。
|
||
|
||
|
||
为了让第三方插件为用户工作，用户必定是要为插件提供一个“凭证”信息的，然后插件利用“凭证”信息，代替用户调用特定 API 完成一些功能。
|
||
|
||
不同的凭证信息将会带来不同的后果：
|
||
|
||
|
||
| 提供的凭证 | 后果 |
|
||
| :-------- | :-------- |
|
||
| 账号密码 | 插件可以得到账号所有权限，安全风险极高 |
|
||
| 会话 token | 插件可以调用几乎所有 API，安全风险极高，且容易受到用户退出登录导致 token 失效的影响 |
|
||
| API Key | 在可控的范围内进行部分授权，且可以方便的随时取消授权，只要设计得当，不会造成安全问题 |
|
||
|
||
API Key 具有以下特点：
|
||
- 1、格式类似于会话 token，是一个随机字符串。
|
||
- 2、每个 API Key 都会和具体的用户 id 发生绑定，后端可以查询到此 API Key 的授权人是谁。
|
||
- 3、一个用户可以创建多个 API Key，用作不同的插件中。
|
||
- 4、每个 API Key 都可以赋予不同的 scope 权限，以做到最小化授权。
|
||
- 5、API Key 可以设置有效期，并且随时删除回收，做到灵活控制。
|
||
|
||
|
||
|
||
### 2、引入依赖
|
||
在使用 API Key 模块之前，你必须先引入依赖：
|
||
``` xml
|
||
<!-- Sa-Token 整合 API Key -->
|
||
<dependency>
|
||
<groupId>cn.dev33</groupId>
|
||
<artifactId>sa-token-apikey</artifactId>
|
||
<version>${sa.top.version}</version>
|
||
</dependency>
|
||
```
|
||
|
||
|
||
### 3、创建 API Key
|
||
|
||
理解了应用场景后，让我们看看 Sa-Token 为 API Key 提供了哪些方法：
|
||
|
||
|
||
``` java
|
||
// 为指定用户创建一个新的 API Key
|
||
ApiKeyModel akModel = SaApiKeyUtil.createApiKeyModel(10001).setTitle("test");
|
||
System.out.println("API Key 值：" + akModel.getApiKey());
|
||
|
||
// 保存 API Key
|
||
SaApiKeyUtil.saveApiKey(akModel);
|
||
|
||
// 删除 API Key
|
||
SaApiKeyUtil.deleteApiKey(apiKey);
|
||
```
|
||
|
||
一个 ApiKeyModel 可设置以下属性：
|
||
``` java
|
||
ApiKeyModel akModel = new ApiKeyModel();
|
||
akModel.setLoginId(10001); // 设置绑定的用户 id
|
||
akModel.setApiKey("AK-NAO6u57zbOWCmLaiVQuVW2tyt3rHpZrXkaQp"); // 设置 API Key 值
|
||
akModel.setTitle("commit"); // 设置名称
|
||
akModel.setIntro("提交代码专用"); // 设置描述
|
||
akModel.addScope("commit", "pull"); // 设置权限范围
|
||
akModel.setExpiresTime(System.currentTimeMillis() + 2592000); // 设置失效时间，13位时间戳，-1=永不失效
|
||
akModel.setIsValid(true); // 设置是否有效
|
||
akModel.addExtra("name", "张三"); // 设置扩展信息
|
||
// 保存
|
||
SaApiKeyUtil.saveApiKey(akModel);
|
||
```
|
||
|
||
查询：
|
||
|
||
``` java
|
||
// 获取 API Key 详细信息
|
||
ApiKeyModel akModel = SaApiKeyUtil.getApiKey("AK-NAO6u57zbOWCmLaiVQuVW2tyt3rHpZrXkaQp");
|
||
|
||
// 直接获取 ApiKey 所代表的 loginId
|
||
Object loginId = SaApiKeyUtil.getLoginIdByApiKey("AK-NAO6u57zbOWCmLaiVQuVW2tyt3rHpZrXkaQp");
|
||
|
||
// 获取指定 loginId 的 ApiKey 列表记录
|
||
List<ApiKeyModel> apiKeyList = SaApiKeyUtil.getApiKeyList(10001);
|
||
```
|
||
|
||
|
||
### 4、校验 API Key
|
||
|
||
``` java
|
||
// 校验指定 API Key 是否有效，无效会抛出异常 ApiKeyException
|
||
SaApiKeyUtil.checkApiKey("AK-XxxXxxXxx");
|
||
|
||
// 校验指定 API Key 是否具有指定 Scope 权限，不具有会抛出异常 ApiKeyScopeException
|
||
SaApiKeyUtil.checkApiKeyScope("AK-XxxXxxXxx", "userinfo");
|
||
|
||
// 校验指定 API Key 是否具有指定 Scope 权限，返回 true 或 false
|
||
SaApiKeyUtil.hasApiKeyScope("AK-XxxXxxXxx", "userinfo");
|
||
|
||
// 校验指定 API Key 是否属于指定账号 id
|
||
SaApiKeyUtil.checkApiKeyLoginId("AK-XxxXxxXxx", 10001);
|
||
```
|
||
|
||
注解鉴权示例：
|
||
``` java
|
||
/**
|
||
* API Key 资源 相关接口
|
||
*/
|
||
@RestController
|
||
public class ApiKeyResourcesController {
|
||
|
||
// 必须携带有效的 ApiKey 才能访问
|
||
@SaCheckApiKey
|
||
@RequestMapping("/akRes1")
|
||
public SaResult akRes1() {
|
||
ApiKeyModel akModel = SaApiKeyUtil.currentApiKey();
|
||
System.out.println("当前 ApiKey: " + akModel);
|
||
return SaResult.ok("调用成功");
|
||
}
|
||
|
||
// 必须携带有效的 ApiKey ，且具有 userinfo 权限
|
||
@SaCheckApiKey(scope = "userinfo")
|
||
@RequestMapping("/akRes2")
|
||
public SaResult akRes2() {
|
||
ApiKeyModel akModel = SaApiKeyUtil.currentApiKey();
|
||
System.out.println("当前 ApiKey: " + akModel);
|
||
return SaResult.ok("调用成功");
|
||
}
|
||
|
||
// 必须携带有效的 ApiKey ，且同时具有 userinfo、chat 权限
|
||
@SaCheckApiKey(scope = {"userinfo", "chat"})
|
||
@RequestMapping("/akRes3")
|
||
public SaResult akRes3() {
|
||
ApiKeyModel akModel = SaApiKeyUtil.currentApiKey();
|
||
System.out.println("当前 ApiKey: " + akModel);
|
||
return SaResult.ok("调用成功");
|
||
}
|
||
|
||
// 必须携带有效的 ApiKey ，且具有 userinfo、chat 其中之一权限
|
||
@SaCheckApiKey(scope = {"userinfo", "chat"}, mode = SaMode.OR)
|
||
@RequestMapping("/akRes4")
|
||
public SaResult akRes4() {
|
||
ApiKeyModel akModel = SaApiKeyUtil.currentApiKey();
|
||
System.out.println("当前 ApiKey: " + akModel);
|
||
return SaResult.ok("调用成功");
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
|
||
### 5、前端如何提交 API Key？
|
||
默认情况下，前端可以从任意途径提交 API Key 字符串，只要后端能接受到。
|
||
|
||
但是如果后端是通过 `SaApiKeyUtil.currentApiKey()` 方法获取，或者 `@SaCheckApiKey` 注解校验，则需要前端按照一定的格式来提交了：
|
||
|
||
方式一：通过请求参数或请求头，参数名为 `apikey`（全小写）
|
||
|
||
``` url
|
||
/user/getInfo?apikey=AK-NAO6u57zbOWCmLaiVQuVW2tyt3rHpZrXkaQp
|
||
```
|
||
|
||
|
||
方式二：通过 Basic 参数提交
|
||
|
||
``` url
|
||
http://AK-NAO6u57zbOWCmLaiVQuVW2tyt3rHpZrXkaQp@localhost:8081/user/getInfo
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
### 6、打开数据库模式
|
||
|
||
框架默认将所有 API Key 信息保存在缓存中，这可以称之为“缓存模式”，这种模式下，重启缓存库后，数据将丢失。
|
||
|
||
如果你想改为“数据库模式”，可以通过 `implements SaApiKeyDataLoader` 实现从数据库加载的逻辑。
|
||
|
||
``` java
|
||
/**
|
||
* API Key 数据加载器实现类 （从数据库查询）
|
||
*/
|
||
@Component
|
||
public class SaApiKeyDataLoaderImpl implements SaApiKeyDataLoader {
|
||
|
||
@Autowired
|
||
SaApiKeyMapper apiKeyMapper;
|
||
|
||
// 指定框架不再维护 API Key 索引信息，而是由我们手动从数据库维护
|
||
@Override
|
||
public Boolean getIsRecordIndex() {
|
||
return false;
|
||
}
|
||
|
||
// 根据 apiKey 从数据库获取 ApiKeyModel 信息 （实现此方法无需为数据做缓存处理，框架内部已包含缓存逻辑）
|
||
@Override
|
||
public ApiKeyModel getApiKeyModelFromDatabase(String namespace, String apiKey) {
|
||
return apiKeyMapper.getApiKeyModel(apiKey);
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
参考上述代码实现后，框架内部逻辑将会做出一些改变，请注意以下事项：
|
||
|
||
- 1、调用 `SaApiKeyUtil.getApiKey("ApiKey")` 时，会先从缓存中查询，查询不到时调用 `getApiKeyModelFromDatabase` 从数据库加载。
|
||
- 2、框架不再维护 API Key 索引数据，这意味着无法再调用 `SaApiKeyUtil.getApiKeyList(10001)` 来获取一个用户的所有的 API Key 数据，请自行从数据库查询。
|
||
- 3、调用 `SaApiKeyUtil.saveApiKey(akModel)` 保存时，只会把 API Key 数据保存到缓存中，请自行补充额外代码向数据库保存数据。
|
||
- 4、调用 `SaApiKeyUtil.deleteApiKey("ApiKey")` 时，只会删除这个 API Key 在缓存中的数据，不会删除数据库的数据，请自行补充相关代码保证数据双删。
|
||
- 5、其它诸如查询 `SaApiKeyUtil.getApiKey("ApiKey")` 或校验 `SaApiKeyUtil.checkApiKeyScope("ApiKey", "userinfo")` 等方法，依旧可以正常调用。
|
||
|
||
|
||
|
||
### 7、多账号模式使用
|
||
|
||
如果系统有多套账号表，比如 Admin 和 User，只需要指定不同的命名空间即可：
|
||
|
||
例如 User 账号的 API Key，我们使用原生 `SaApiKeyUtil` 进行创建与校验。
|
||
|
||
对于 Admin 账号的 API Key，我们则新建一个 `SaApiKeyTemplate` 实例
|
||
|
||
``` java
|
||
// 新建 Admin 账号的 apiKeyTemplate 对象，命名空间为 "admin-apikey"
|
||
public static SaApiKeyTemplate adminApiKeyTemplate = new SaApiKeyTemplate("admin-apikey");
|
||
|
||
// 创建一个新的 ApiKey，并返回
|
||
@RequestMapping("/createApiKey")
|
||
public SaResult createApiKey() {
|
||
ApiKeyModel akModel = adminApiKeyTemplate.createApiKeyModel(StpUtil.getLoginId()).setTitle("test");
|
||
adminApiKeyTemplate.saveApiKey(akModel);
|
||
return SaResult.data(akModel);
|
||
}
|
||
|
||
// ...校验、查询等操作，均使用新创建的 adminApiKeyTemplate，而非原生 `SaApiKeyUtil`
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|