租户令牌有效负载参考

    Meilisearch 的租户令牌是 JSON Web 令牌 (JWT)。它们的有效负载由三个元素组成:搜索规则、一个 API 密钥 UID 和一个可选的过期日期

    有效负载示例

    {
      "exp": 1646756934,
      "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab",
      "searchRules": {
        "INDEX_NAME": {
          "filter": "attribute = value"
        }
      }
    }
    

    搜索规则

    搜索规则对象是一组指令,用于定义 Meilisearch 将在每次使用特定租户令牌进行的查询中强制执行的搜索参数。

    搜索规则对象

    searchRules 必须是一个 JSON 对象。每个键都必须对应一个或多个索引

    {
      "searchRules": {
        "*": {},
        "INDEX_*": {},
        "INDEX_NAME_A": {}
      }
    }
    

    每个搜索规则对象可能包含一个 filter 键。此 filter 的值必须是一个过滤器表达式

    {
      "*": {
        "filter": "attribute_A = value_X AND attribute_B = value_Y"
      }
    }
    

    Meilisearch 将过滤器应用于使用该租户令牌进行的所有搜索。令牌只能访问 searchRules 对象中存在的索引。

    一个令牌可能包含任意数量的索引规则。特定规则集优先并覆盖 * 规则。

    危险

    由于租户令牌是在您的应用程序中生成的,因此 Meilisearch 无法检查搜索规则过滤器是否有效。无效的搜索规则会在搜索时返回错误。

    有关 Meilisearch 过滤器语法的更多信息,请参阅搜索 API 参考。

    搜索规则也可能是一个空对象。在这种情况下,租户令牌将有权访问索引中的所有文档

    {
      "INDEX_NAME": {}
    }
    

    示例

    单个过滤器

    在此示例中,用户将仅接收 medical_records 文档,其 user_id 等于 1

    {
      "medical_records": {
        "filter": "user_id = 1"
      }
    }
    

    多个过滤器

    在此示例中,用户将仅接收 medical_records 文档,其 user_id 等于 1 且其 published 字段等于 true

    {
      "medical_records": {
        "filter": "user_id = 1 AND published = true"
      }
    }
    

    授予对索引中所有文档的访问权限

    在此示例中,用户可以访问 medical_records 中的所有文档

    {
      "medical_records": {}
    }
    

    使用部分通配符定位多个索引

    在此示例中,用户将收到任何以 medical 开头的索引中的文档。这包括诸如 medical_recordsmedical_patents 之类的索引

    {
      "medical*": {
        "filter": "user_id = 1"
      }
    }
    

    使用通配符定位所有索引

    在此示例中,用户将收到整个实例中任何索引中的文档

    {
      "*": {
        "filter": "user_id = 1"
      }
    }
    

    手动定位多个索引

    在此示例中,用户可以访问所有索引(除了一个索引)中 user_id = 1 的文档。查询 medical_records 时,用户将只能访问已发布的文档

    {
      "*": {
        "filter": "user_id = 1"
      },
      "medical_records": {
        "filter": "user_id = 1 AND published = true",
      }
    }
    

    API 密钥 UID

    租户令牌有效负载必须包含 API 密钥 UID 以验证请求。该 UID 是一个字母数字字符串,用于标识 API 密钥

    {
      "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab"
    }
    

    查询 获取一个 API 密钥端点以获取 API 密钥的 UID。

    该 UID 必须指示有权访问 搜索操作的 API 密钥。令牌可以访问与用于生成它的 API 密钥相同的索引和路由。

    由于主密钥不是 API 密钥,因此您不能使用主密钥来创建租户令牌。避免暴露 API 密钥,并始终在应用程序的后端生成令牌

    租户令牌和过期的 API 密钥

    如果 API 密钥过期,则使用它创建的任何租户令牌都将失效。如果 API 密钥因更改的主密钥而被删除或重新生成,则同样适用。

    过期日期

    过期日期必须是 UNIX 时间戳或 null

    {
      "exp": 1646756934
    }
    

    令牌的过期日期不能超过其父 API 密钥的过期日期。

    设置令牌过期日期是可选的,但强烈建议这样做。没有过期日期的令牌会无限期地保持有效,并且可能存在安全隐患。

    撤销没有过期日期的令牌

    撤销没有过期日期的令牌的唯一方法是删除其父 API 密钥。

    更改实例的主密钥会强制 Meilisearch 重新生成所有 API 密钥,并且还会使所有现有的租户令牌失效。