semtech/mu-authorization

mu-authorization（又名SEAS）

SPARQL端点授权服务（SEAS）是一个放置在SPARQL端点前的层，它基于用户的会话信息和数据访问权限重写该端点上的查询。

其核心思想是：数据被组织到图中，对这些图的访问被限制为特定角色集。每组角色与一个组相关联。当INSERT查询发送到SPARQL端点时，SEAS会拦截该查询。然后SEAS遍历其不同的组规范，根据规范，当三元组匹配图的约束时，将三元组分布到不同的图中。当服务后来尝试通过SEAS读取数据时，会检查会话并评估每个组的访问标准。如果用户有权访问该组，则允许服务从该组的图中读取数据。

教程

将mu-authorization添加到栈中

当前栈包含一个三元组存储（Virtuoso、Blazegraph等）。由于我们要将mu-authorization放在该三元组存储前面，请在docker-compose.yml文件中查找三元组存储服务的名称，并将其重命名为triplestore。

例如：

yml
services:
  database:
    image: tenforce/virtuoso
    ...

应更新为：

yml
services:
  triplestore:
    image: tenforce/virtuoso
    ...

接下来，通过添加以下代码片段将mu-authorization服务添加到docker-compose.yml文件中：

yml
services:
  database:
    image: semtech/mu-authorization:0.6.0-beta.5
    environment:
      MU_SPARQL_ENDPOINT: "http://triplestore:8890/sparql"
    volumes:
      - ./config/authorization:/config

此片段通常添加在triplestore服务的正上方。

创建文件./config/authorization/config.ex，内容如下：

elixir
alias Acl.Accessibility.Always, as: AlwaysAccessible
alias Acl.GraphSpec.Constraint.Resource, as: ResourceConstraint
alias Acl.GraphSpec, as: GraphSpec
alias Acl.GroupSpec, as: GroupSpec
alias Acl.GroupSpec.GraphCleanup, as: GraphCleanup

defmodule Acl.UserGroups.Config do
  def user_groups do
    # 这些元素从上到下处理。每个元素可能会改变当前查询适用的四元组。四元组以三个部分表示：current_source_quads、removed_source_quads、new_quads。四元组可以通过多种方式计算。GroupSpec和GraphCleanup的使用很常见。
    [
      # // 公开
      %GroupSpec{
        name: "public",
        useage: [:read],
        access: %AlwaysAccessible{},
        graphs: [ %GraphSpec{
                    graph: "http://mu.semte.ch/graphs/public",
                    constraint: %ResourceConstraint{
                      resource_types: [
                      ]
                    } } ] },

      # // 清理
      #
      %GraphCleanup{
        originating_graph: "http://mu.semte.ch/application",
        useage: [:write],
        name: "clean"
      }
    ]
  end
end

使用docker-compose up -d启动栈。授权服务将被创建。

请注意，在./config/authorization/config.ex中正确配置授权规则之前，应用程序中可能看不到任何数据。

操作指南

为未认证用户公开数据

本指南介绍如何为未认证用户（即会话中没有任何信息的用户）公开数据。

本指南假设已按照“教程：将mu-authorization添加到栈中”所述将mu-authorization添加到应用程序中，且数据当前存储在图http://mu.semte.ch/application中。

首先，打开./config/authorization/config.ex，确保user_groups函数中有一个名为public的%GroupSpec，如下所示：

elixir
%GroupSpec{
  name: "public",
  useage: [:read],
  access: %AlwaysAccessible{},
  graphs: [ %GraphSpec{
              graph: "http://mu.semte.ch/graphs/public",
              constraint: %ResourceConstraint{
                resource_types: [
                ]
              } } ] },

接下来，将要公开的所有资源类型（rdf:Class）添加到%ResourceConstraint的resource_types数组中。

例如：

elixir
%GroupSpec{
  name: "public",
  useage: [:read],
  access: %AlwaysAccessible{},
  graphs: [ %GraphSpec{
              graph: "http://mu.semte.ch/graphs/public",
              constraint: %ResourceConstraint{
                resource_types: [
                  "http://www.w3.org/ns/dcat#Catalog",
                  "http://www.w3.org/ns/dcat#Dataset",
                  "http://www.w3.org/ns/dcat#Distribution"
                ]
              } } ] },

重启授权服务以应用更新的配置：

bash
docker-compose restart database

接下来，将数据库中的数据从图http://mu.semte.ch/application移动到图http://mu.semte.ch/graphs/public。如果栈包含https://github.com/mu-semtech/mu-migrations-service%EF%BC%8C%E5%8F%AF%E4%BB%A5%E7%94%9F%E6%88%90%E5%A6%82%E4%B8%8B%E8%BF%81%E7%A7%BB%EF%BC%9A

sparql
DELETE {
  GRAPH  <http://mu.semte.ch/application> {
    ?s ?p ?o .
  }
} INSERT {
  GRAPH  <http://mu.semte.ch/graphs/public> {
    ?s ?p ?o .
  }
} WHERE {
  GRAPH  <http://mu.semte.ch/application> {
    ?s a ?type ; ?p ?o .
    VALUES ?type {
        <http://www.w3.org/ns/dcat#Catalog>
        <http://www.w3.org/ns/dcat#Dataset>
        <http://www.w3.org/ns/dcat#Distribution>
    }
  }
}

否则，可以直接在三元组存储的SPARQL端点（例如http://localhost:8890/sparql）上执行上述SPARQL查询。

现在数据已在三元组存储中移动，只需确保应用程序中的***用户与public组相关联。用户的默认组通过https://github.com/mu-semtech/mu-identifier%E4%B8%8A%E7%9A%84%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E9%85%8D%E7%BD%AE%E3%80%82

打开docker-compose.yml，将以下环境变量添加到identifier服务：

yml
services:
  identifier:
    image: semtech/mu-identifier
    environment:
      DEFAULT_MU_AUTH_ALLOWED_GROUPS_HEADER: "[{\"variables\":[],\"name\":\"public\"}]"

使用docker-compose up -d重启栈。

现在应该能够在应用程序中检索指定资源类型的资源。

参考

挂载的配置文件

mu-authorization可以接收用户组配置和Delta系统的配置文件。

标准的mu-semtech栈确保配置文件存储在./config/authorization/中。可以通过在docker-compose.yml中添加以下卷将它们挂载到mu-authorization服务中：

yml
services:
  database:
    image: semtech/mu-authorization
    volumes:
      - ./config/authorization:/config

配置文件的内容在授权配置和Delta系统部分有详细说明。

用户组配置

SEAS中的授权基于组访问规则。组基于对数据应用的约束对一个或多个图具有读和/或写访问权限。适用于用户的组访问规则基于其会话信息确定。

用户组应可在/config/user_groups.ex或/config/config.ex中访问。在标准的mu-semtech栈中，可能会将其保存在./config/authorization/user_groups.ex中。

SEAS配置文件中最重要的函数是user_groups函数。该函数返回SEAS已知的所有组配置。其返回类型的结构如下详细说明。

别名

为使配置更简洁易读，可以在配置文件顶部配置以下别名：

elixir
alias Acl.Accessibility.Always, as: AlwaysAccessible
alias Acl.Accessibility.ByQuery, as: AccessByQuery
alias Acl.GraphSpec.Constraint.Resource.AllPredicates, as: AllPredicates
alias Acl.GraphSpec.Constraint.Resource.NoPredicates, as: NoPredicates
alias Acl.GraphSpec.Constraint.ResourceFormat, as: ResourceFormatConstraint
alias Acl.GraphSpec.Constraint.Resource, as: ResourceConstraint
alias Acl.GraphSpec, as: GraphSpec
alias Acl.GroupSpec, as: GroupSpec
alias Acl.GroupSpec.GraphCleanup, as: GraphCleanup

GroupSpec

user_groups函数的结果是GroupSpec对象的列表。每个此类对象指定一个组访问规则。

GroupSpec的属性包括：

• name：组规范规则的名称。必须唯一。
• useage：使用限制列表，来自集合:read、:write、:read_for_write。:read和:write含义明显，:read_for_write表示仅在执行更新查询时可以读取数据。
• access：定义哪些用户属于该组。参见访问规则。
• graphs：图规范数组，描述组数据存储的图。

值得注意的是，组访问规则与传统用户组并非一对一映射。相反，一个组访问规则可能适用于多个用户组。例如，一个组访问规则可能指定公司管理员的访问规则，但每个公司都有一个管理员用户组（例如“公司X的管理员”、“公司Y的管理员”等）。

访问规则

访问规则确定用户是否符合组规范以及他属于哪些确切的用户组。

有两种访问规则：AlwaysAccessible和AccessByQuery。

AlwaysAccessible

一种简单的规则，允许所有用户访问，无论其会话信息如何。

AccessByQuery

根据特定SPARQL查询授予访问权限的规则。

AccessByQuery对象有两个属性：

• query：计算当前用户访问权限的SPARQL查询字符串。此查询通常基于附加到用户会话的信息。<SESSION_ID>可用作SPARQL查询中的占位符，在运行时替换为当前会话的URI。
• vars：指定SPARQL查询导出/返回的相关变量的字符串数组。名称应与查询SELECT块中返回的变量名称完全匹配。这些变量将被组访问规则的相应GraphSpecs使用。

授予所有具有SuperMegaAdmin角色的用户访问权限的访问规则如下所示：

elixir
%AccessByQuery{
  vars: ["session_group_id","session_role"],
  query: "PREFIX ext: <http://mu.semte.ch/vocabularies/ext/>
    PREFIX mu: <http://mu.semte.ch/vocabularies/core/>

    SELECT ?session_group ?session_role WHERE {
      <SESSION_ID> ext:sessionGroup/mu:uuid ?session_group_id;
                   ext:sessionRole ?session_role.
      FILTER( ?session_role = \"SuperMegaAdmin\" )
    }
" }

确保正确转义查询中的特殊字符。

如果查询返回任何结果，则用户有权访问。对于每组返回的变量，解析一个图URI以在组访问规则的GraphSpecs部分中使用。

GraphSpec

GraphSpec对象定义创建哪个图以及基于数据约束将哪些三元组添加到该图中。

每个GraphSpec对象包含以下属性：

• graph：要创建的图的（基础）URI。该URI附加有GroupSpec的访问规则的vars属性的结果。例如，如果图URI是http://myorganization.org/group，访问规则的vars数组是['group_id', 'group_name']，则创建的图可能类似于http://myorganization.org/group/9b2a5053-0967-425c-a1ee-c9b9bfe38b81/awesome_admins。
• constraint：确定哪些三元组应发送到图/从图读取的约束。

GroupSpec对象的graphs属性包含GraphSpec对象的数组。即，组可访问的数据可能分布在多个图中。constraint属性定义三元组存储在哪个图中。

约束

约束定义哪些三元组将被发送到图或从图读取。本节抽象了三元组是从图读取还是写入图，因为原理相同。这两种操作都称为“发送到图”。

有两种约束：ResourceFormatConstraint和ResourceConstraint。

ResourceFormatConstraint

ResourceFormatConstraint定义对三元组的主语URI格式的约束。它只有一个属性resource_prefix，包含一个URI。所有主语URI以此前缀开头的三元组将被发送到图。

在下面的示例中，所有主语以http://data.myorganization.org/开头的三元组将被发送到图http://mu.semte.ch/graphs/public：

elixir
%GraphSpec{
  graph: "http://mu.semte.ch/graphs/public",
  constraint: %ResourceFormatConstraint{
    resource_prefix: "http://data.myorganization.org/"
  } }

ResourceConstraint

ResourceConstraint允许对资源的类型（rdf:Class）和/或三元组的谓词施加约束。

ResourceConstraint具有以下属性：

• resource_types：类型URI列表。具有此类型的资源将被发送到图。
• predicates：对此类资源的谓词施加的附加约束。此属性是可选的。此约束可以是AllPredicates（默认）或NoPredicates对象，带有可选的except谓词URI数组。

在第一个示例中，foaf:Person的属性不会被写入图http://mu.semte.ch/graphs/public，除了人的foaf:name和foaf:accountName。在第二个示例中，人的所有属性将被写入图http://mu.semte.ch/graphs/public，除了人的foaf:birthday：

elixir
%GraphSpec{
  graph: "http://mu.semte.ch/graphs/public",
  constraint: %ResourceConstraint{
    resource_types: [
      "http://xmlns.com/foaf/0.1/Person" ],
    predicates: %NoPredicates{
      except: [
        "http://xmlns.com/foaf/0.1/name",
        "http://xmlns.com/foaf/0.1/accountName" ] }
  } }

elixir
%GraphSpec{
  graph: "http://mu.semte.ch/graphs/public",
  constraint: %ResourceConstraint{
    resource_types: [
      "http://xmlns.com/foaf/0.1/Person" ],
    predicates: %AllPredicates{
      except: [
        "http://xmlns.com/foaf/0.1/birthday" ] }
  } }

Delta系统

对于mu-authorization执行的每个更新查询，它都会计算增量，即添加了哪些三元组和删除了哪些三元组。这些增量消息可以发送给感兴趣的客户端。

Delta客户端配置

该服务允许配置哪些客户端将接收这些增量消息。此文件需要在docker容器内的/config/delta.ex中可访问。

增量配置文件指定要向其发送增量消息的目标服务列表。可以在URL中使用docker服务名称（mu-authorization服务已知的名称）。

elixir
defmodule Delta.Config do
  def targets do
    [ "http://delta-notifier" ]
  end
end

目前，最常用的增量消息客户端是https://github.com/mu-semtech/delta-notifier#delta-formats%EF%BC%8C%E5%AE%83%E5%85%81%E8%AE%B8%E5%9F%BA%E4%BA%8E%E6%A8%A1%E5%BC%8F%E5%8C%B9%E9%85%8D%E5%B0%86%E5%A2%9E%E9%87%8F%E8%AF%B7%E6%B1%82%E8%BD%AC%E5%8F%91%E5%88%B0%E5%85%B6%E4%BB%96%E6%9C%8D%E5%8A%A1%E3%80%82

Delta格式

增量消息的格式在https://github.com/mu-semtech/delta-notifier#delta-formats%E4%B8%AD%E8%AF%B4%E6%98%8E%E3%80%82

SPARQL端点和三元组存储

mu-authorization服务是放置在SPARQL端点前的层。该服务对SPARQL端点有一些假设，可以更改。可以配置三元组存储的位置以及支持特定三元组存储的修改。

SPARQL端点的位置

mu-authorization发送SPARQL查询的默认SPARQL端点可以通过MU_SPARQL_ENDPOINT环境变量配置。在标准容器中运行时，默认配置为http://database:8890/sparql，但可以在docker-compose.yml文件中覆盖它。如果未设置此变量（如在标准开发设置中），将使用http://localhost:8890/sparql作为默认设置。

数据库兼容性

兼容性层可以重写SPARQL查询以符合三元组存储的预期。使用DATABASE_COMPATIBILITY环境变量。

有时三元组存储可能有些“挑剔”。mu-authorization尝试创建合理且有效的SPARQL查询来表达其意图。尽管仍在开发中，但其目标是生成清晰的SPARQL查询。三元组存储可能对某个查询报错，但对重写后的版本有效。兼容性层解决了这个问题。

DATABASE_COMPATIBILITY的