OpenFGA HTTP API 使用指南：权限管理系统实战

前言

OpenFGA 是一个现代化的细粒度权限管理系统，基于 Google 的 Zanzibar 论文设计。本文将详细介绍 OpenFGA 的 HTTP API 使用方法，帮助开发者快速掌握如何通过 API 管理权限模型、执行权限检查等核心功能。

环境准备

在开始之前，请确保已经部署了 OpenFGA 服务，默认情况下 API 服务运行在 http://localhost:8080。本文所有示例都将基于这个基础 URL 进行演示。

存储管理

创建存储空间

OpenFGA 使用存储空间(Store)来隔离不同的权限系统。每个存储空间包含自己的授权模型和关系数据。

POST /stores
Content-Type: application/json

{
    "name": "openfga-demo"
}

响应将包含新创建的存储空间 ID，后续所有操作都需要使用这个 ID。

管理存储空间

• 获取所有存储空间列表：GET /stores
• 获取特定存储空间详情：GET /stores/{store_id}
• 删除存储空间：DELETE /stores/{store_id}

授权模型管理

创建授权模型

授权模型定义了系统中的实体类型(Type)和它们之间的关系(Relation)。以下是一个包含用户(user)、文件夹(folder)和文档(document)的完整模型示例：

POST /stores/{store_id}/authorization-models
Content-Type: application/json

{
  "schema_version":"1.1",
  "type_definitions": [
    {
      "type":"user"
    },
    {
      "type":"folder",
      "relations": {
        "owner": {"this": {}},
        "parent": {"this": {}}
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [{"type":"user"}]
          },
          "parent": {
            "directly_related_user_types": [{"type":"folder"}]
          }
        }
      }
    },
    {
      "type":"document",
      "relations": {
        "can_view": {
          "union": {
            "child": [
              {"this": {}},
              {"computedUserset": {"relation":"owner"}}
            ]
          }
        },
        "owner": {"this": {}},
        "parent": {"this": {}}
      },
      "metadata": {
        "relations": {
          "can_view": {
            "directly_related_user_types": [{"type":"user"}]
          },
          "owner": {
            "directly_related_user_types": [{"type":"user"}]
          },
          "parent": {
            "directly_related_user_types": [{"type":"folder"}]
          }
        }
      }
    }
  ]
}

这个模型定义了：

1. 用户(user)类型
2. 文件夹(folder)类型，具有owner(所有者)和parent(父文件夹)关系
3. 文档(document)类型，具有can_view(查看权限)、owner和parent关系

查询授权模型

• 获取所有授权模型：GET /stores/{store_id}/authorization-models
• 获取特定模型详情：GET /stores/{store_id}/authorization-models/{model_id}

关系数据操作

写入关系数据

使用/write端点可以添加或删除关系数据：

POST /stores/{store_id}/write
Content-Type: application/json

{
  "writes": {
    "tuple_keys": [
      {
        "user": "user:anne",
        "relation": "owner",
        "object": "document:test"
      }
    ]
  },
  "deletes": {
    "tuple_keys": [
      {
        "user": "user:anne",
        "relation": "owner",
        "object": "document:duplicate"
      }
    ]
  }
}

查询关系数据

/read端点提供了多种查询方式：

1. 检查特定关系是否存在：

POST /stores/{store_id}/read
Content-Type: application/json

{
  "tuple_key": {
    "user": "user:anne",
    "relation": "owner",
    "object": "document:test"
  }
}

2. 查询特定类型的所有对象：

POST /stores/{store_id}/read
Content-Type: application/json

{
  "tuple_key": {
    "user": "user:anne",
    "relation": "owner",
    "object": "document:"
  }
}

3. 查询特定对象的所有关系：

POST /stores/{store_id}/read
Content-Type: application/json

{
  "tuple_key": {
    "object": "document:test"
  }
}

权限检查

单次权限检查

POST /stores/{store_id}/check
Content-Type: application/json

{
  "tuple_key": {
    "user": "user:anne",
    "relation": "owner",
    "object": "document:test"
  }
}

批量权限检查

POST /stores/{store_id}/batch-check
Content-Type: application/json

{
  "checks": [
    {
      "tuple_key": {
        "user": "user:anne",
        "relation": "owner",
        "object": "document:test"
      },
      "correlation_id": "1"
    },
    {
      "tuple_key": {
        "user": "user:bob",
        "relation": "owner",
        "object": "document:test"
      },
      "correlation_id": "2"
    }
  ]
}

带上下文关系的检查

POST /stores/{store_id}/check
Content-Type: application/json

{
  "tuple_key": {
    "user": "user:bob",
    "relation": "can_view",
    "object": "document:test"
  },
  "contextual_tuples": {
    "tuple_keys": [
      {
        "user": "user:bob",
        "relation": "can_view",
        "object": "document:test"
      }
    ]
  }
}

高级功能

扩展权限树

/expand端点可以展示特定关系的完整展开树：

POST /stores/{store_id}/expand
Content-Type: application/json

{
  "tuple_key": {
    "relation": "owner",
    "object": "document:test"
  }
}

列出可访问对象

POST /stores/{store_id}/list-objects
Content-Type: application/json

{
  "type": "document",
  "relation": "can_view",
  "user": "user:anne"
}

列出有权限的用户

POST /stores/{store_id}/list-users
Content-Type: application/json

{
  "object": {
    "type": "document",
    "id": "test"
  },
  "relation": "can_view",
  "user_filters": [
    {
      "type": "user"
    }
  ]
}

变更追踪

OpenFGA 提供了变更追踪功能，可以获取关系数据的历史变更：

GET /stores/{store_id}/changes?page_size=50
Content-Type: application/json

响应中包含continuation_token，可用于获取后续变更记录。

最佳实践

1. 模型设计：在设计授权模型时，先明确业务实体和它们之间的关系
2. 批量操作：当需要处理大量关系数据时，使用批量写入和批量检查API
3. 变更追踪：定期检查变更记录，可用于审计和同步外部系统
4. 一致性级别：对关键权限检查使用HIGHER_CONSISTENCY确保数据最新

总结

本文全面介绍了 OpenFGA 的 HTTP API 使用方法，从基础的存储管理到复杂的权限检查操作。通过合理使用这些 API，开发者可以构建出灵活、高效的权限管理系统，满足各种复杂的业务场景需求。