InterSystems IRIS 2022.2 使用 JWT 保护 REST API 教程

InterSystems IRIS 2022.2及更新版本引入了使用JSON Web令牌（JWT）对REST API进行身份验证的功能。通过设置访问令牌的过期时间，并限制密码在网络上传输的频率和范围，该功能显著提升了API的安全性。

本文将以教程形式，演示如何使用InterSystems IRIS创建一个模拟REST API，并通过JWT对其进行保护。

什么是REST？

REST（Representational State Transfer）是一种架构风格，允许程序与Web应用程序进行通信并访问这些应用程序提供的功能。REST API通常基于HTTP协议，使用标准的HTTP方法（如GET、POST、PUT、DELETE）来操作资源。

什么是JWT？

JSON Web令牌（JWT）是一种紧凑且URL安全的方式，用于在双方之间传递声明。JWT可以进行数字签名、加密或两者兼备，从而确保数据的完整性和安全性。JWT在REST API的身份验证中非常常见，能够有效减少密码传输的风险。

生成REST API代码存根

InterSystems IRIS提供了一种便捷的方法来生成REST API的代码存根。通过使用OpenAPI 2.0规范，您可以快速生成API的基础代码结构。生成的代码通常包括以下三个文件：

impl.cls：主要实现API的业务逻辑。
disp.cls：处理API请求的调度逻辑。
spec.cls：定义API的规范。

在实际开发中，我们大部分时间会集中在impl.cls文件中。

实现REST API

定义对象模型

在数据库中，我们需要定义一个基础对象模型。例如，创建一个“角色”（Character）对象，该对象包含以下属性：

名称（必填）
类别（可选）
种族（可选）
等级（可选）

以下是对象模型的示例代码：

Class TTRPG.Character Extends %Persistent {
    Property Name As %String [Required];
    Property Race As %String;
    Property Class As %String;
    Property Level As %String;

    Index NameIndex On Name [IdKey];    ClassMethod GetCharByName(Name As %String) As TTRPG.Character {
        Set Character = ##Class(TTRPG.Character).%OpenId(Name)
        Quit Character
    }
}

通过继承%Persistent类，我们可以将“角色”对象存储到数据库中。IdKey属性确保角色名称的唯一性。

创建角色的API方法

以下是创建角色的PostCharacter方法实现：

ClassMethod PostCharacter(Name As %String, Class As %String, Race As %String, Level As %String) As %DynamicObject {
    Set results = {}
    Set char = ##Class(TTRPG.Character).%New()
    Set char.Name = Name
    Set char.Class = Class
    Set char.Race = Race
    Set char.Level = Level
    Set st = char.%Save()
    If st {
        Set charInfo = {}
        Set charInfo.Name = char.Name
        Set charInfo.Class = char.Class
        Set charInfo.Race = char.Race
        Set charInfo.Level = char.Level
        Set results.Character = charInfo
        Set results.Status = "Success"
    } Else {
        Set results.Status = "Error"
        Set results.Message = "无法创建角色"
    }
    Quit results
}

此方法接收角色的属性作为参数，创建一个新的角色对象并保存到数据库中。如果保存成功，将返回角色信息；否则返回错误消息。

获取角色的API方法

以下是按名称检索角色的GetCharacterByName方法实现：

ClassMethod GetCharacterByName(charName As %String) As %DynamicObject {
    Set results = {}
    Set char = ##Class(TTRPG.Character).GetCharByName(charName)
    If char {
        Set charInfo = {}
        Set charInfo.Name = char.Name
        Set charInfo.Class = char.Class
        Set charInfo.Race = char.Race
        Set charInfo.Level = char.Level
        Set results.Character = charInfo
        Set results.Status = "Success"
    } Else {
        Set results.Status = "Error"
        Set results.Message = "未找到角色"
    }
    Quit results
}

此方法根据角色名称检索数据库中的角色对象，并返回相应的信息。如果角色不存在，则返回错误消息。

获取角色列表的API方法

以下是获取所有角色列表的GetCharacterList方法实现：

ClassMethod GetCharacterList() As %DynamicObject {
    Set results = {}
    Set query = "SELECT Name, Class, Race, Level FROM TTRPG.Character"
    Set tStatement = ##Class(%SQL.Statement).%New()
    Set qstatus = tStatement.%Prepare(query)
    If qstatus '= 1 {
        Do ##Class(TTRPG.impl).%WriteResponse("错误：" _ $SYSTEM.Status.DisplayError(qstatus))
    }
    Set rset = tStatement.%Execute()
    Set characterList = []
    While rset.%Next() {
        Set charInfo = {}
        Set charInfo.Name = rset.Name
        Set charInfo.Class = rset.Class
        Set charInfo.Race = rset.Race
        Set charInfo.Level = rset.Level
        Do characterList.%Push(charInfo)
    }
    Set results.Status = "Success"
    Set results.TotalCount = rset.%ROWCOUNT
    Set results.CharacterList = characterList
    Quit results
}

此方法通过SQL查询获取所有角色信息，并返回包含角色列表的动态对象。

配置IRIS以支持JWT身份验证

配置Web应用程序

在管理门户中，导航到 系统管理 > 安全 > 应用程序 > Web应用程序。
创建一个新的Web应用程序，例如/api/TTRPG/。
选择REST单选按钮，并勾选“使用JWT身份认证”。
设置JWT访问令牌超时时间（建议3600秒）和刷新令牌超时时间（建议900秒）。

配置JWT身份验证

在管理门户中，导航到 系统管理 > 安全 > 系统安全 > 身份验证/Web会话选项。
配置JWT颁发者字段和签名算法。例如，将颁发者设置为InterSystems。

测试REST API

登录并获取JWT

通过/login端点进行登录，发送以下JSON结构的请求：

{
    "user": "{YOURUSER}",
    "password": "{YOURPASSWORD}"
}

成功登录后，将收到一个JWT令牌（access_token），可用于后续请求。

创建角色

使用/characters端点发送POST请求，创建角色。请求头需包含以下格式的授权信息：

Authorization: Bearer {JWTValue}

列出角色

使用/characters端点发送GET请求，获取所有角色列表。

按名称检索角色

使用/characters/{charName}端点发送GET请求，按名称检索角色信息。

总结

通过本文，您学习了如何使用InterSystems IRIS创建一个REST API，并通过JWT对其进行保护。该方法不仅提升了API的安全性，还简化了身份验证的实现流程。希望本文对您有所帮助！

原文链接: https://community.intersystems.com/post/creating-rest-api-jwt-authentication-objectscript