Ory Kratos NodeJS/ExpressJS 用户界面参考实现

镜像概述和主要用途

本镜像包含Ory Kratos在NodeJS/ExpressJS/Handlebars/NextJS环境中的用户界面参考实现。它完整实现了Ory Kratos的所有核心流程，包括登录、注册、账户设置、账户恢复及账户验证。

若仅需为应用添加认证功能，无需自定义登录、注册等界面，建议参考Ory Kratos快速入门。

核心功能和特性

• 完整流程支持：实现Ory Kratos的全部身份认证流程（登录、注册、账户设置、账户恢复、账户验证）
• 灵活配置：通过环境变量配置Kratos API地址、Cookie设置、TLS等关键参数
• OAuth2集成：支持Ory Hydra的OAuth2 consent流程，可配置信任客户端ID以跳过 consent 界面
• 多环境适配：支持本地开发（非HTTPS环境）和生产环境（HTTPS配置）
• 基础路径自定义：支持通过环境变量或反向代理设置应用的基础路径

使用场景和适用范围

• 自定义认证界面开发：需要为Ory Kratos构建定制化用户界面的开发者
• 身份服务集成：作为NodeJS/ExpressJS应用与Ory Kratos集成的参考示例
• OAuth2 consent流程实现：需要处理Ory Hydra授权决策的场景

使用方法和配置说明

环境变量配置

以下环境变量用于配置Express.js服务，部分变量在本地开发（npm run start）时会由nodemon通过nodemon.json自动设置。使用Ory Network项目时，可通过ORY_SDK_URL替代KRATOS_PUBLIC_URL和HYDRA_ADMIN_URL。

Ory Identities 必要配置

• ORY_SDK_URL 或 KRATOS_PUBLIC_URL（必填）：Ory Kratos公共API的URL。若应用与Kratos在同一私有网络，建议使用私有网络地址（如kratos-public.svc.cluster.local）
• KRATOS_BROWSER_URL（可选）：Kratos公共API的浏览器可访问URL，仅当与KRATOS_PUBLIC_URL不同时需要设置
• KRATOS_ADMIN_URL（可选）：Ory Kratos管理API的URL（如[***]）

Ory OAuth2 配置

• ORY_SDK_URL 或 HYDRA_ADMIN_URL（可选）：Ory Hydra管理API的URL。若应用与Hydra在同一私有网络，建议使用私有网络地址（如hydra-admin.svc.cluster.local）
• COOKIE_SECRET（必填）：用于签名Cookie的密钥，需至少8位字母数字字符
• CSRF_COOKIE_NAME（必填）：CSRF Cookie名称，建议使用__HOST-example.com-x-csrf-token格式以匹配域名
• CSRF_COOKIE_SECRET（可选）：Consent路由设置CSRF Cookie哈希值的密钥，需至少8位字母数字字符
• REMEMBER_CONSENT_SESSION_FOR_SECONDS（可选）：设置consent请求的remember_for值（秒），默认3600秒
• ORY_ADMIN_API_TOKEN（可选）：使用Ory Network项目时，OAuth2 Consent流程需配置此管理API令牌
• DANGEROUSLY_DISABLE_SECURE_CSRF_COOKIES（可选）：仅本地开发无HTTPS时使用，设置CSRF Cookie为secure: false；使用时需将CSRF_COOKIE_NAME设置为不含__Host-前缀的名称
• TRUSTED_CLIENT_IDS（可选）：可信客户端ID列表，可跳过consent界面

TLS配置

• TLS_CERT_PATH（可选）：证书文件路径，需与TLS_KEY_PATH同时设置以启用HTTPS
• TLS_KEY_PATH（可选）：密钥文件路径，需与TLS_CERT_PATH同时设置以启用HTTPS

基础路径设置

可通过以下两种方式为应用设置基础路径：

1. Express.js路由处理：设置BASE_PATH环境变量为子路径（如/myapp）
2. 反向代理/API网关：通过反向代理或API网关剥离路径前缀（在无服务器环境建议使用第一种方式）

本地开发

无Kratos连接的模拟运行

使用模拟数据运行，无需连接真实Kratos服务：

shell
NODE_ENV=stub npm start

如需为id_token生成模拟数据，额外设置：

shell
export CONFORMITY_FAKE_CLAIMS=1

与本地Kratos测试

1. 按照Ory Kratos快速入门启动Kratos：

   shell
   # 在Kratos项目中执行
   make quickstart-dev
   

2. 停止Kratos默认启动的UI容器以释放端口：

   shell
   docker kill kratos_kratos-selfservice-ui-node_1
   

3. 配置环境变量并启动应用：

   shell
   export KRATOS_PUBLIC_URL=[***]
   export PORT=4455
   npm start
   

TypeScript SDK管理

更新SDK

若修改了Ory Kratos API，需手动生成TypeScript SDK（需安装openapi-generator）：

shell
# 设置Kratos项目路径
export KRATOS_DIR=/path/to/kratos
make build-sdk

构建Docker镜像

shell
# 设置Kratos项目路径
export KRATOS_DIR=/path/to/kratos
make build-sdk-docker

清理SDK

shell
make clean-sdk