# @govtechsg/singpass-myinfo-oidc-helper 中文文档

规范地址：https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/

版本：9\.1\.0
npm 元数据更新时间：2026-07-03T07:14:58.735Z
中文译文更新时间：2026-11-17T03:45:54.442Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40govtechsg/singpass-myinfo-oidc-helper
原文对照：https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/?lang=original
项目主页：https://github.com/GovTechSG/singpass-myinfo-oidc-helper#readme
源码仓库：https://github.com/GovTechSG/singpass-myinfo-oidc-helper

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，724 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2020-04-08T10:29:51.608Z
- 最新版本发布：2026-07-01T00:27:34.896Z
- 近 30 天下载量：7239（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 5 个）

## 中文简介

帮助建立赖克党与Singpass OIDC和MyInfo个人基本API融合

## 安装

```sh
npm install @govtechsg/singpass-myinfo-oidc-helper
```

也可以使用：`pnpm add @govtechsg/singpass-myinfo-oidc-helper`、`yarn add @govtechsg/singpass-myinfo-oidc-helper`、`bun add @govtechsg/singpass-myinfo-oidc-helper`

## README

# Singpass MyInfo OIDC 帮助器

使用此模块构建客户端应用程序,可以:

-   通过 Singpass/Corppass OIDC 供应商认证用户
-   通过 MyInfo Person- Basic API 和 Person API 检索用户的 MyInfo 数据

* * *

## 安装

`npm i @govtechsg/singpass-myinfo-oidc-helper`

* * *

## 测试您的 SingPass / MyInfo 客户端设置和秘密

-   这些测试将允许您检查您的ID / key / certs / JWK 端点/对象 设置正确
-   使用 `singpass-helper-ndi-ext.spec.ts` 以测试登录和取回令牌
-   使用中记录后 `myinfo.ext.spec.ts` 以测试 myinfo 数据的检索

## MyInfo 资讯

* * *

### MyInfo帮助器

帮助获得一个V3 MyInfo个人.

`import { MyInfo } from "singpass-myinfo-oidc-helper"`

MyInfo (英语). 帮助

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 属性 | 字符串 \[\] | 要从 MyInfo 检索的用户属性矩阵 。 属性完整列表参见 [这里](https://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html) |
| 客户端ID | 字符串 | 你和MyInfo上机时的客户端身份 |
| 个人基本情况 | 字符串 | MyInfo个人基本终点的完整URL 。 显示 lib 用户可在中继器、 prod 和任何模拟服务器中选择 |
| singpass 服务ID | 字符串 | 你登上Singpass时的应用程序身份证明 MyInfo 用于检查您是否试图获取 MyInfo 数据, 最近通过 Singpass 登录到您的应用程序 |
| 密钥解密JWE | 字符串 | 你解密MyInfo的JWE有效载荷的私钥. 在登入时, 公共密钥已交给 MyInfo, 让他们加密包含个人数据的 JWE |
| 验证JWS | 字符串 | MyInfo的公众证书作为MyInfo有效载荷,既与JWE加密,也与JWS签约 |
| 私人 Keyto 签名请求 | 字符串 | 用于在 MyInfo 服务器上签名请求 。 需要加密的 PKCS8 私人密钥 |
| 私钥口令 | 字符串 | 您用于加密私密密密钥的密码 |

-   `getPersonBasic(uinfin: string, attributes: string[]) => MyInfoComponents.Schemas.PersonBasic` - 获得基本概况数据,其中不包括森林合作伙伴关系和IRAS数据,其形式如下: `MyInfoComponents.Schemas.PersonBasic`
-   `constructAuthorizationUrl(state: string, purpose: string, attributes: string[]) => string` - 用必要的参数构建授权url,以授权用户检索完整的人文数据
-   `getToken(authCode: string, state?: string): => TokenResponse` - 使用从授权API获取的有效认证码提交访问令牌
-   `getPerson(accessToken: string, attributes: string[]) => MyInfoComponents.Schemas.Person` - 获得完整的个人数据,形状如下: `MyInfoComponents.Schemas.Person`,需要从 getToken 获取的有效访问令牌

* * *

### MyInfo 请求

通常不需要, 是因为要向 MyInfo 提出我们 MyInfo 帮助器未覆盖的任何其他自定义请求 .

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 应用 | 字符串 | 你和MyInfo上机时的客户端身份 |
| 私人 Keyto 签名请求 | 字符串 | 用于在 MyInfo 服务器上签名请求 。 需要加密的 PKCS8 私人密钥 |
| 私钥口令 | 字符串 | 您用于加密私密密密钥的密码 |

-   `get(uri: string, queryParams?: { [key: string]: any }, accessToken?: string)` - 请求到定义的 myinfo gov 端点
    
    -   `queryParams` 引用获取请求的查询参数
    -   `accessToken` 将使用“ Bearer” 前缀, 并包含在授权页眉中, 用于获取Person api, 它需要从 Token API 获取访问符
-   `post(uri: string, params: { [key: string]: any })` - 向已定义的 myinfo gov 端点发送邮件请求
    

* * *

### 假话

MyInfo (英语). 假的。 假的我的信息助手

使用 `getPersonBasic` 以获取假 MyInfo 基本配置。 使用 `getPerson` 包括来自CPF和IRAS的财务数据.

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 属性 | 弦乐? | 此助手将返回的 MyInfo 属性列表 |

```ts
getPersonBasic({
  archetype: ProfileArchetype;
  userdisplayname?: string;
  race?: MyInfoRaceCode:
  marital?: MyInfoMaritalStatusCode;
  marriagedate?: string;
  divorcedate?: string;
  marriagecertno?: string;
  countryofmarriage?: MyInfoCountryPlaceCode;
  childrenbirthrecords?: ChildrenBirthRecord[];
  childrenoverridemode?: ChildrenOverrideMode;
  residentialstatus?: MyinfoResidentialCode;
  occupationfreeform?: string;
  dob?: string;
  gstvyear?: number;
  gvs?: GVS;
  merdekageneligible?: boolean;
  merdekagenquantum?: number;
  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;
  hdbtype?: MyinfoHDBTypeCode;
  housingtype?: MyinfoHousingTypeCode;
  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;
  vehicles?: VehicleDetails[];
  employment?: string;
}) => MyInfoComponents.Schemas.PersonBasic

getPerson({
  archetype: ProfileArchetype;
  userdisplayname?: string;
  race?: MyInfoRaceCode:
  marital?: MyInfoMaritalStatusCode;
  marriagedate?: string;
  divorcedate?: string;
  marriagecertno?: string;
  countryofmarriage?: MyInfoCountryPlaceCode;
  childrenbirthrecords?: ChildrenBirthRecord[];
  childrenoverridemode?: ChildrenOverrideMode;
  residentialstatus?: MyinfoResidentialCode;
  occupationfreeform?: string;
  dob?: string;
  gstvyear?: number;
  gvs?: GVS;
  merdekageneligible?: boolean;
  merdekagenquantum?: number;
  merdekagenmessagecode?: MyinfoMerdekaGenerationMessageCode;
  hdbtype?: MyinfoHDBTypeCode;
  housingtype?: MyinfoHousingTypeCode;
  drivingqdlvalidity?: MyinfoDrivingLicenceValidityCode;
  vehicles?: VehicleDetails[];
  employment?: string;
  cpfcontributionhistoryoverridemode?: OverrideMode;
  cpfcontributions?: CpfContributionHistory[];
  cpfbalances?: CpfBalance;
  noabasic?: NoaBasic;
}) => MyInfoComponents.Schemas.Person
```

-   获取假人数据.
    
-   enum MyInfo. (原始内容存档于2018-09-29). 假相为相. 配置文件类型 适当命名的剖面类型生成不同类型的假 MyInfo 人物
    

* * *

## 更新 Myinfo 域

-   Myinfo 域包括 `MyinfoComponents` 和各种enum是自动生成的 `npm run generate-myinfo-typings '<swagger file>'`
-   Swagger 文件需要从 [https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v4.0.html 页面存档备份,存于互联网档案馆](https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v4.0.html)
    -   注:有不同的变体,这是政府数字服务公司使用的,它具有人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人-人
-   脚本也会从 [https://api.singpass.gov.sg/assets/api-lib/myinfo/downloads/myinfo-api-code-tables.xlsx 页面存档备份,存于互联网档案馆](https://api.singpass.gov.sg/assets/api-lib/myinfo/downloads/myinfo-api-code-tables.xlsx)

### 文件夹/ 文件结构 `src/types`

| 路径 | 做什麽 |
| --- | --- |
| 自定义/数字 | 自定义的 json 语句 |
| 自定义/ 人- 常见 | 进入 `PersonCommon` 对象 |
| 生成 | 从 `generate-myinfo-typings` 脚本, 在此不要添加文件 ! |

### 帮帮我! 缺少了 swagger 文件 `<insert data item name>`

-   Myinfo REST API 不发布每个数据项
-   您需要手动将其 OpenAPI 规格添加到 `custom/person-common` 然后运行 `npm run generate-myinfo-typings '<swagger file>'`
-   将创建一个接口,并将相应的数据项添加到 `PersonCommon` 对象

### 帮帮我! `myinfo-api-code-tables.xlsx` 缺少 `<insert code name>`

-   `myinfo-api-code-tables.xlsx` 只列出一般代码
-   更详细的名单可在以下网址查阅: [https://www.singstat.gov.sg/standards/standards-and-classizations (中文(简体) )](https://www.singstat.gov.sg/standards/standards-and-classifications)
-   如果在 SingStat 中找到缺失的代码列表, 请更新 `generate-myinfo-typings` 要导入的脚本
-   否则
    1.  手动添加 enum 定义 (json) 为 `custom/enums` 文件夹
        -   _提示: 参考现有文件格式_
    2.  运行 `npm run generate-myinfo-typings '<swagger file>'`

### 帮帮我! `myinfo-api-code-tables.xlsx's <insert code name>` 不匹配 swagger 定义

-   遵循上面的解决方案, 手动添加定义
-   Enum 将覆盖生成的自动 enum

* * *

## Singpass (前NDI) (英语)

与 Pre-NDI Singpass 集成的助手 OIDC

`import { Singpass } from "singpass-myinfo-oidc-helper"`

Singpass (英语). Oidc帮助工具

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 授权Url | 字符串 | Singpass / 授权端点的 URL |
| 登录Url | 字符串 | Singpass/日志端点的 URL |
| 符号Url | 字符串 | Singpass / ken 端点的 URL |
| 客户端ID | 字符串 | 你登上Singpass时的应用程序身份证明. |
| 客户端加密 | 字符串 | 客户秘密 与客户端ID一起发送到符号端点 |
| 重定向乌里 | 字符串 | singpass 的重定向 URL 在用户登录后重定向 。 上船时必须被SP白列 |
| jweDecryptKey 密码 | 字符串 | 用于解密包裹符号的 JWT 的私钥 |
| jws 验证键 | 字符串 | 用于校验包裹符号的 JWT 的公钥 |

### 登录

-   `constructAuthorizationUrl = (state: string, nonce?: string) => string` - 以必要的参数构筑批准文件,包括:
    
-   状态( 后以重定向返回)
    
-   无( 后从符号端点返回 JWT 内部)
    
-   `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 把标语从SP标语端点拿回来 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 从 SP 代号端点取出新的代币 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `getIdTokenPayload(tokens: TokenResponse) => Promise<TokenPayload>` - 解密和验证JWT。 输出 TokenPayload, 是提取 NricAndUuid FromPayload 的输入
    
-   `extractNricAndUuidFromPayload(payload: TokenPayload) => { nric: string, uuid: string }` - 最后,从ID Token TokenPayload中获取用户的nric和WOG(全政府)UUID
    

#### 登录 Singpass SSO 会话

-   `logoutOfSession(sessionId: string) => Promise<SessionLogoutResult>`\- 使用有效的会话代号(即从Singpass域 cookie检索),将 Singpass 会话的用户日志退出

* * *

## Singpass (后NDI) (英语)

与后NDI Singpass 集成的助手 OIDC

`import { Singpass } from "singpass-myinfo-oidc-helper"`

Singpass (英语). NdiOidc帮助程序

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 平面纤维 | 字符串 | Singpass 的 URL OIDC 配置细节 |
| 客户端ID | 字符串 | 你登上Singpass时的应用程序身份证明. |
| 重定向乌里 | 字符串 | singpass 的重定向 URL 在用户登录后重定向 。 上船时必须被SP白列 |
| jweDecryptKey 密码 | [密钥对象](https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/#readme-key-object) | 用于解密包裹符号的 JWT 的私钥对象 |
| 客户端 Assertion SignKey | [密钥对象](https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/#readme-key-object) | 签名端点请求中提供的客户端断言时的私钥对象满足 |

### 登录( V3) _已贬值_

-   `constructAuthorizationUrl = (params: { state: string; userInfoScope: string[]; nonce?: string; codeVerifier?: string; }) => Promise<string>` - 以必要的参数构筑批准文件,包括:
    
    -   状态( 后以重定向返回)
    -   无( 后从符号端点返回 JWT 内部)
-   `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 把标语从SP标语端点拿回来 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) => Promise<TokenPayload>` - 解密和验证JWT。 输出 TokenPayload, 是提取 NricAndUuid FromPayload 的输入
    
-   `extractNricAndUuidFromPayload(payload: TokenPayload) => { nric: string, uuid: string }` - 最后,从ID Token TokenPayload中获取用户的nric和WOG(全政府)UUID
    

### 登录( V4)

-   `constructAuthorizationUrlV2 = (params: { state: string; userInfoScope: string[]; nonce?: string; codeVerifier?: string; }) => Promise<string>` - 以必要的参数构筑批准文件,包括:
    
    -   状态( 后以重定向返回)
    -   无( 后从符号端点返回 JWT 内部)
    -   范围(确定要从 MyInfo 获取的属性/用户数据)
-   `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 把标语从SP标语端点拿回来 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `getUserInfo (token: string) => Promise<string>` - 用这个 `access_token` 从 `getTokens`,检索用户数据,答复为 JWE 符号
    
-   `verifyUserInfo (jwe: string) => Promise<object>` - 解密用户Info JWE以返回用户数据
    

* * *

## Corppass( 预NDI) :

与预NDI Corppass 集成的助手 OIDC

`import { Corppass } from "singpass-myinfo-oidc-helper"`

Corppass (英语). Oidc帮助工具

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 授权Url | 字符串 | Corppass / 授权端点的 URL |
| 符号Url | 字符串 | Corppass/token 端点的 URL |
| 客户端ID | 字符串 | 你登上Corppass时的应用软件身份. |
| 客户端加密 | 字符串 | 客户秘密 与客户端ID一起发送到符号端点 |
| 重定向乌里 | 字符串 | corppass在用户登录后重定向的 URL 。 上船时必须被SP白列 |
| jweDecryptKey 密码 | 字符串 | 用于解密包裹符号的 JWT 的私钥 |
| jws 验证键 | 字符串 | 用于校验包裹符号的 JWT 的公钥 |

### 登录

-   `constructAuthorizationUrl = (state: string, nonce?: string) => string` - 以必要的参数构筑批准文件,包括:
    
-   状态( 后以重定向返回)
    
-   无( 后从符号端点返回 JWT 内部)
    
-   `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 把信物从信物端点拿回来 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `refreshTokens (refreshToken: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 从 SP 代号端点取出新的代币 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `getAccessTokenPayload(tokens: TokenResponse) => Promise<AccessTokenPayload>` - 解码和验证JWT。 输出 AccessTokenPayload, 包含 `EntityInfo`, (中文(简体) ), `AuthInfo` 财务报告和审定财务报表 `TPAccessInfo` 索赔
    
-   `getIdTokenPayload(tokens: TokenResponse, overrideDecryptKey?: Key) => Promise<IdTokenPayload>` - 解密和验证JWT。 输出 IdTokenPayload, 是提取InfoFromIdTokenSubject 的输入
    
-   `extractInfoFromIdTokenSubject(payload: TokenPayload) => { nric: string, uuid: string, countryCode: string }` - 最后,从 ID Token TokenPayload 中获取 nric,系统定义的UUID和用户的国家代码
    

* * *

## Corppass (后NDI) (英语)

与后NDI Corppass 集成的助手 OIDC

`import { Corppass } from "singpass-myinfo-oidc-helper"`

Corppass (英语). NdiOidc帮助程序

-   `constructor`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 平面纤维 | 字符串 | Corpass OIDC 配置的 URL 细节 |
| 客户端ID | 字符串 | 你登上Corppass时的应用软件身份. |
| 重定向乌里 | 字符串 | corppass在用户登录后重定向的 URL 。 上船时必须被SP白列 |
| jweDecryptKey 密码 | [密钥对象](https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/#readme-key-object) | 用于解密包裹符号的 JWT 的私钥对象 |
| 客户端 Assertion SignKey | [密钥对象](https://npmcn.com/package/%40govtechsg/singpass-myinfo-oidc-helper/#readme-key-object) | 签名端点请求中提供的客户端断言时的私钥对象满足 |

### 登录

-   `constructAuthorizationUrl = (state: string, nonce?: string) => Promise<string>` - 以必要的参数构筑批准文件,包括:
    
-   状态( 后以重定向返回)
    
-   无( 后从符号端点返回 JWT 内部)
    
-   `getTokens (authCode: string, axiosRequestConfig?: AxiosRequestConfig) => Promise<TokenResponse>` - 把信物从信物端点拿回来 输出 TokenResponse, 这是获取IdTokenPayload 的输入
    
-   `getAccessTokenPayload(tokens: TokenResponse) => Promise<AccessTokenPayload>` - 解码和验证JWT。 输出 AccessTokenPayload, 包含 `EntityInfo`, (中文(简体) ), `AuthInfo` 财务报告和审定财务报表 `TPAccessInfo` 索赔
    
-   `getIdTokenPayload(tokens: TokenResponse) => Promise<IdTokenPayload>` - 解密和验证JWT。 输出 IdTokenPayload, 是提取InfoFromIdTokenSubject 的输入
    
-   `extractInfoFromIdTokenSubject(payload: TokenPayload) => { nric: string, uuid: string, countryCode: string }` - 最后,从 ID Token TokenPayload 中获取 nric,系统定义的UUID和用户的国家代码
    
-   `getAuthorisationInfoTokenPayload(tokens: TokenResponse) => Promise<AuthInfoTokenPayload>` - 从授权信息端点获得授权信息。 输出 AuthInfoKenPayload, 包含用户的角色和参数信息
    
-   `extractActiveAuthResultFromAuthInfoToken(authInfoToken: AuthInfoTokenPayload): Record<string, EserviceAuthResultRow[]>` - 从授权信息代号有效载荷中获取用户当前有效的授权信息
    

* * *

## 密钥对象

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 键 | 字符串 | 密钥的内容 |
| 格式 | 字符串 | 提供的密钥格式 |
| 备选案文 | 字符串 | 密钥算法 |

## 常见问题

### @govtechsg/singpass-myinfo-oidc-helper 是什么？

帮助建立赖克党与Singpass OIDC和MyInfo个人基本API融合

### 如何安装 @govtechsg/singpass-myinfo-oidc-helper？

在项目目录运行 npm install @govtechsg/singpass-myinfo-oidc-helper，或使用 pnpm add / yarn add / bun add。

### @govtechsg/singpass-myinfo-oidc-helper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @govtechsg/singpass-myinfo-oidc-helper 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @govtechsg/singpass-myinfo-oidc-helper 可以商用吗？

@govtechsg/singpass-myinfo-oidc-helper 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @govtechsg/singpass-myinfo-oidc-helper 的下载量有多少？

根据 npm 官方下载统计，@govtechsg/singpass-myinfo-oidc-helper 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,239 次，日均约 241 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @govtechsg/singpass-myinfo-oidc-helper 还在维护吗？

最新版本 9\.1\.0 发布于 2026/07/01（4 个月前）；至今共发布 70 个版本，其中过去 12 个月发布了 5 个；首次发布于 2020/04/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

