gostone API完全手册：从基础调用到高级权限控制

gostone API完全手册：从基础调用到高级权限控制

【免费下载链接】gostoneThe cloud operating system security high-performance authentication component can be implemented as a high-performance replacement for OpenStack Keystone.项目地址: https://gitcode.com/openeuler/gostone

前往项目官网免费下载：https://ar.openeuler.org/ar/

gostone是openEuler社区开发的高性能云操作系统安全认证组件，作为OpenStack Keystone的完美替代品，提供强大的身份认证和权限管理能力。🎯 本手册将为您详细介绍gostone API的完整使用指南，从基础调用到高级权限控制，帮助您快速掌握这个强大的认证服务。

📋 为什么选择gostone？

gostone在性能、安全性和易用性方面都有显著优势：

• 高性能设计：专为云原生环境优化，响应速度快
• 完全兼容：完美替代OpenStack Keystone，迁移成本低
• 安全可靠：支持多种认证方式和权限控制策略
• 易于集成：提供简洁的RESTful API接口

🚀 快速开始：安装与配置

环境要求

• Go 1.16+ 环境
• MySQL 5.7+ 数据库
• 至少2GB可用内存

安装步骤

# 克隆项目仓库 git clone https://gitcode.com/openeuler/gostone # 进入项目目录 cd gostone # 配置数据库 # 修改 etc/application.yaml 中的数据库连接信息

配置文件详解

核心配置文件位于 etc/application.yaml，主要配置项包括：

GoStone: Database: Url: root:123456@tcp(172.28.8.248:13306)/gostone?charset=utf8&parseTime=true&timeout=1s Port: - 8100 - 8101 Secret: jwtas%123s SignMethod: HS256 ExpiresTime: 30 TokenType: jwt SkipAuth: false

🔐 认证与令牌管理

获取访问令牌

API端点：POST /v3/auth/tokens

这是gostone API的核心入口点，所有操作都需要有效的访问令牌。令牌支持JWT和Fernet两种格式，可通过配置文件灵活切换。

请求示例：

{ "auth": { "identity": { "methods": ["password"], "password": { "user": { "name": "admin", "domain": { "id": "default" }, "password": "admin_password" } } }, "scope": { "project": { "id": "project_id" } } } }

响应示例：

{ "token": { "issued_at": "2024-01-01T00:00:00.000000Z", "expires_at": "2024-01-01T01:00:00.000000Z", "user": { "id": "user_id", "name": "admin", "domain": { "id": "default", "name": "Default" } }, "roles": [...], "project": { "id": "project_id", "name": "project_name" }, "catalog": [...] } }

验证令牌

API端点：

• GET /v3/auth/tokens- 验证令牌并返回详细信息
• HEAD /v3/auth/tokens- 仅验证令牌有效性

管理员令牌管理

API端点：POST /v3/admin/tokens

管理员可以为其他用户生成令牌，这在自动化脚本和系统集成中非常有用。

👥 用户管理API

用户操作接口

gostone提供了完整的用户管理功能，所有接口都位于/v3/users路径下：

创建用户示例

{ "user": { "name": "new_user", "domain_id": "default", "enabled": true, "description": "新用户描述", "email": "user@example.com" } }

🏢 域(Domain)管理

域操作接口

域是gostone中的顶级组织单元，所有资源都属于某个域：

创建域示例

{ "domain": { "name": "new_domain", "enabled": true, "description": "新域描述" } }

📊 项目管理API

项目操作接口

项目是资源分配和权限控制的基本单位：

项目数据结构

项目信息存储在 model/keystone.go 中定义的结构体中，包含以下关键字段：

• id- 项目唯一标识
• name- 项目名称
• domain_id- 所属域ID
• enabled- 是否启用
• description- 项目描述

👑 角色管理API

角色操作接口

角色定义了用户在项目或域中的权限：

角色数据结构

角色信息包含：

• id- 角色唯一标识
• name- 角色名称
• domain_id- 所属域ID
• extra- 额外信息（JSON格式）

🔗 权限分配API

权限分配接口

将角色分配给用户或组：

🌐 服务与端点管理

服务管理接口

服务代表云平台中的各种服务（如计算、存储、网络等）：

端点管理接口

端点是服务的访问地址：

🗺️ 区域管理API

区域操作接口

区域代表数据中心的地理位置：

🛡️ 权限策略控制

策略检查接口

gostone提供了强大的策略检查机制，位于 policy/ 目录：

API端点：POST /v3/policies/:policy_id

策略文件默认位于 etc/policy.yaml，支持复杂的权限规则定义。

策略规则示例

"identity:get_user": "role:admin or user_id:%(target.user.id)s" "identity:list_users": "role:admin" "identity:create_user": "role:admin"

策略检查类型

gostone支持多种策略检查类型：

• 基础检查- 简单的权限验证
• 相等检查- 值相等性验证
• 包含检查- 值包含关系验证
• 逻辑组合- AND/OR逻辑组合

🔍 高级查询功能

分页查询

所有列表查询接口都支持分页参数：

• limit- 每页记录数
• marker- 分页标记
• page- 页码

过滤查询

支持多种过滤条件：

• name- 按名称过滤
• enabled- 按启用状态过滤
• domain_id- 按域ID过滤
• project_id- 按项目ID过滤

排序功能

支持按指定字段排序：

• sort_key- 排序字段
• sort_dir- 排序方向（asc/desc）

⚙️ 错误处理与状态码

常见HTTP状态码

错误响应格式

{ "error": { "code": 404, "title": "Not Found", "message": "The requested resource could not be found." } }

🔧 性能优化建议

1. 令牌缓存

建议客户端缓存令牌以减少认证请求频率。gostone令牌默认有效期为30分钟，可在 etc/application.yaml 中配置。

2. 批量操作

对于大量数据操作，建议使用分页查询，避免一次性加载过多数据。

3. 连接池配置

调整数据库连接池参数以获得最佳性能：

MaxIdleConns: 100 MaxOpenConns: 100

4. 日志级别

根据环境调整日志级别，生产环境建议使用info级别：

LogLevel: info

🚨 安全最佳实践

1. 密钥管理

• 定期更换JWT签名密钥
• 使用安全的密钥存储方案
• 避免在代码中硬编码密钥

2. 权限最小化

• 遵循最小权限原则分配角色
• 定期审计权限分配
• 及时回收不再需要的权限

3. 审计日志

• 启用完整的操作日志记录
• 定期检查异常访问模式
• 建立安全事件响应机制

📚 扩展与自定义

自定义认证方式

gostone支持插件式认证扩展，您可以：

1. 实现自定义认证后端
2. 集成第三方身份提供商
3. 添加多因素认证支持

策略引擎扩展

通过扩展 policy/check/ 目录下的检查器，可以实现自定义策略规则。

数据库适配

gostone使用GORM作为ORM框架，支持多种数据库后端，可根据需要适配其他数据库。

🎯 总结

gostone作为openEuler社区的高性能认证组件，提供了完整、安全、易用的API接口。通过本手册，您应该已经掌握了：

1. ✅基础认证- 令牌获取与验证
2. ✅用户管理- 完整的用户生命周期管理
3. ✅权限控制- 基于角色的精细权限管理
4. ✅资源管理- 域、项目、服务等资源管理
5. ✅高级功能- 策略控制、查询优化、安全最佳实践

无论是构建新的云平台，还是迁移现有的OpenStack环境，gostone都能为您提供稳定可靠的认证服务。🚀

下一步行动

1. 动手实践- 按照本手册的示例代码开始集成
2. 深入定制- 根据业务需求调整配置和策略
3. 性能测试- 在生产环境中进行压力测试
4. 社区贡献- 参与openEuler gostone项目的开发与改进

记住，良好的认证系统是云平台安全的基石。gostone为您提供了坚实的基础，让您可以专注于业务逻辑的开发！💪

【免费下载链接】gostoneThe cloud operating system security high-performance authentication component can be implemented as a high-performance replacement for OpenStack Keystone.项目地址: https://gitcode.com/openeuler/gostone