内置数据库 认证/访问控制

EMQX 客服发表于:2022年05月16日 14:23:10

内置数据库 认证/访问控制

内置数据库认证使用 EMQX 内置 Mnesia 数据库存储客户端 Clientid/Username 与密码,支持通过 HTTP API 管理认证数据。

内置数据库认证不依赖外部数据源,使用上足够简单轻量。

Dashboard 管理

内置数据库认证可以通过 EMQX Dashboard 的 “模块” 进行开关以及管理

创建模块

打开 EMQX Dashboard,点击左侧的 “模块” 选项卡,选择添加:

image.png

点击"选择",然后选择内置数据库认证模块

image.png

配置相关参数

image.png

最后点击“添加”按钮模块即可添加成功。

image.png

管理数据

内置数据库可以通过 dashboard 管理认证与访问控制数据

image.png

认证数据

可以通过 dashboard 对认证数据进行管理

image.png

当客户端连接 EMQX 时,内置数据库认证会获取 CONNENT 报文中的 Clientid 与 Username,然后数据库中记录的密码进行匹配,一旦匹配成功则认证成功。

image.png

image.png

访问控制数据

可以通过 dashboard 对访问控制数据进行管理

image.png

image.png

HTTP API

内置数据库 认证/访问控制 还提供了 HTTP API

Mnesia 认证

Mnesia 认证使用 EMQX 内置 Mnesia 数据库存储客户端 Client ID/Username 与密码,支持通过 HTTP API 管理认证数据。

Mnesia 认证不依赖外部数据源,使用上足够简单轻量,Mnesia 支持使用 Client ID 或 Username 进行认证。

POST api/v4/auth_clientid

创建基于 Client ID 的认证规则。

Parameters (json):

NameTypeRequiredDescription
clientidStringTrueClient ID
passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X POST \
 -d '{"clientid": "emqx_c", "password": "emqx_p"}' \
  http://localhost:8081/api/v4/auth_clientid

## Return
{"code":0}

POST api/v4/auth_username

创建基于 Username 的认证规则。

Parameters (json):

NameTypeRequiredDescription
usernameStringTrueUsername
passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X POST \
 -d '{"username": "emqx_u", "password": "emqx_p"}' \
  http://localhost:8081/api/v4/auth_username

## Return
{"code":0}

POST api/v4/auth_clientid

批量创建基于 Client ID 的认证规则。

Path Parameters:

Parameters (json):

NameTypeRequiredDescription
[].clientidStringTrueClient ID
[].passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X POST \
 -d '[{"clientid": "emqx_c_1", "password": "emqx_p"}, {"clientid": "emqx_c_2", "password": "emqx_p"}]' \
  http://localhost:8081/api/v4/auth_clientid

## Return
{
    "data":{
        "emqx_c_2":"ok",
        "emqx_c_1":"ok"
    },
    "code":0
}

POST api/v4/auth_username

批量创建基于 Username 的认证规则。

Path Parameters:

Parameters (json):

NameTypeRequiredDescription
[].usernameStringTrueUsername
[].passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X POST \
 -d '[{"username": "emqx_u_1", "password": "emqx_p"}, {"username": "emqx_u_2", "password": "emqx_p"}]' \
  http://localhost:8081/api/v4/auth_username

## Return
{
  "data":{
    "emqx_u_2":"ok",
    "emqx_u_1":"ok"
  },
  "code":0
}

GET api/v4/auth_clientid

查看已经添加的认证数据。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
metaObject规则对象
dataObject规则对象
- data.[].clinetidStringClient ID

Example

## Return
$ curl -i \
  --basic \
  -u admin:public \
  -X GET \
  http://localhost:8081/api/v4/auth_clientid

## Request
{
    "meta":{
        "page":1,
        "limit":10,
        "count":3
    },
    "data":[
        {
            "clientid":"emqx_c_1"
        },
        {
            "clientid":"emqx_c_2"
        },
        {
            "clientid":"emqx_c"
        }
    ],
    "code":0
}

GET api/v4/auth_username

查看已经添加的认证数据。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
metaObject规则对象
dataObject规则对象
- data.[].usernameStringClient ID

Example

## Return
curl -i \
  --basic \
  -u admin:public \
  -X GET \
  http://localhost:8081/api/v4/auth_username

## Request
{
    "meta":{
        "page":1,
        "limit":10,
        "count":3
    },
    "data":[
        {
            "username":"emqx_u"
        },
        {
            "username":"emqx_u_2"
        },
        {
            "username":"emqx_u_1"
        }
    ],
    "code":0
}

GET api/v4/auth_clientid/{clientid}

获取指定的资源的详细信息。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClient ID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.clientidStringClient ID
- data.passwordString注意此处返回的密码是使用配置文件指定哈希方式加密后的密码

Example

## Request
curl -i \
  --basic \
  -u admin:public \
  -X GET \
  http://localhost:8081/api/v4/auth_clientid/emqx_c

## Return
{
  "data":{
    "password":"bb7bb456355aaeb55a4eb26ea286314fc360138720cfca2c852d4dfb8cd834",
    "clientid":"emqx_c"
  },
  "code":0
}

GET api/v4/auth_username/{username}

获取指定的资源的详细信息。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.usernameStringUsername
- data.passwordString注意此处返回的密码是使用配置文件指定哈希方式加密后的密码

Example

## Request
curl -i \
  --basic \
  -u admin:public \
  -X GET \
  http://localhost:8081/api/v4/auth_username/emqx_u

## Return
{
  "data":{
    "password":"bb7bb456355aaeb55a4eb26ea286314fc360138720cfca2c852d4dfb8cd834",
    "clientid":"emqx_u"
  },
  "code":0
}

PUT api/v4/auth_clientid/{clientid}

更新已添加的认证数据。

Parameters (json):

NameTypeRequiredDescription
clientidStringTrueClient ID

Parameters (json):

NameTypeRequiredDescription
passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X PUT \
 -d '{"password": "emqx_new_p"}' \
  http://localhost:8081/api/v4/auth_clientid/emqx_c

## Return
{"code":0}

PUT api/v4/auth_username/{username}

更新已添加的认证数据。

Parameters (json):

NameTypeRequiredDescription
usernameStringTrueUsername

Parameters (json):

NameTypeRequiredDescription
passwordStringTrue密码

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X PUT \
 -d '{"password": "emqx_new_p"}' \
  http://localhost:8081/api/v4/auth_username/emqx_u

## Return
{"code":0}

DELETE /api/v4/auth_clientid/{clientid}

删除认证规则。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClient ID

Parameters:

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X Delete\
  http://localhost:8081/api/v4/auth_clientid/emqx_c

## Return
{"code":0}

DELETE /api/v4/auth_username/{username}

删除认证规则。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Parameters:

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X Delete\
  http://localhost:8081/api/v4/auth_username/emqx_u

## Return
{"code":0}

Mnesia 访问控制

Mnesia ACL 使用 EMQX 内置的 Mnesia 数据库存储 ACL 规则,可以存储数据、动态管理 ACL,方便与外部设备管理系统集成

POST api/v4/acl

添加 ACL 规则。

  • Clientid ACL

    Parameters (json):

    NameTypeRequiredDescription
    clientidStringTrueClient ID
    topicStringTrue主题
    actionsub/pub/pubsubTrue动作
    accessallow/denyTrue是否允许

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObject规则对象
    - data.clientidStringClientid
    - data.topicString主题
    - data.actionString动作
    - data.accessString是否允许

    Examples

    ## Request
    curl -i \
    --basic \
    -u admin:public \
    -X POST \
    -d '{"clientid":"emqx_c", "topic":"Topic/A", "action":"pub", "access": "allow"}' \
    http://localhost:8081/api/v4/acl
    
    ## Return
    {
      "data":{
          "topic":"Topic/A",
          "result":"ok",
          "clientid":"emqx_c",
          "action":"pub",
          "access":"allow"
      },
      "code":0
    }
  • Username ACL

    Parameters (json):

    NameTypeRequiredDescription
    usernameStringTrueUsername
    topicStringTrue主题
    actionsub/pub/pubsubTrue动作
    accessallow/denyTrue是否允许

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObject规则对象
    - data.usernameStringUsername
    - data.topicString主题
    - data.actionString动作
    - data.accessString是否允许

    Examples

    ## Request
    curl -i \
    --basic \
    -u admin:public \
    -X POST \
    -d '{"username":"emqx_u", "topic":"Topic/A", "action":"pub", "access": "allow"}' \
    http://localhost:8081/api/v4/acl
    
    ## Return
    {
      "data":{
          "topic":"Topic/A",
          "result":"ok",
          "username":"emqx_u",
          "action":"pub",
          "access":"allow"
      },
      "code":0
    }
  • $all ACL

    Parameters (json):

    NameTypeRequiredDescription
    topicStringTrue主题
    actionsub/pub/pubsubTrue动作
    accessallow/denyTrue是否允许

    Success Response Body (JSON):

    nametypedescription
    codeinteger0
    dataobject规则对象
    - data.allstring$all
    - data.topicstring主题
    - data.actionstring动作
    - data.accessstring是否允许

    Examples

    ## Request
    curl -i \
    --basic \
    -u admin:public \
    -X POST \
    -d '{"topic":"Topic/A", "action":"pub", "access": "allow"}' \
    http://localhost:8081/api/v4/acl
    
    ## Return
    {
      "data":{
          "topic":"Topic/A",
          "result":"ok",
          "all":"$all",
          "action":"pub",
          "access":"allow"
      },
      "code":0
    }

POST api/v4/acl

批量添加 ACL 规则。

Parameters (json):

NameTypeRequiredDescription
[0].clientidStringTrueClientid
[0].topicStringTrue主题
[0].actionsub/pub/pubsubTrue动作
[0].accessallow/denyTrue是否允许
[1].usernameStringTrueUsername
[1].topicStringTrue主题
[1].actionsub/pub/pubsubTrue动作
[1].accessallow/denyTrue是否允许
[2].topicStringTrue主题
[2].actionsub/pub/pubsubTrue动作
[2].accessallow/denyTrue是否允许

Success Response Body (JSON):

nametypedescription
codeinteger0
dataobject规则对象
- data.[0].clientidstringClient ID
- data.[0].topicstring主题
- data.[0].actionstring动作
- data.[0].accessstring是否允许
- data.[1].usernamestringUsername
- data.[1].topicstring主题
- data.[1].actionstring动作
- data.[1].accessstring是否允许
- data.[2].allstring$all
- data.[2].topicstring主题
- data.[2].actionstring动作
- data.[2].accessstring是否允许

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X POST \
 -d '[
        {
          "clientid":"emqx_c_1",
          "topic":"Topic/A",
          "action":"pub",
          "access": "allow"
        },
        {
          "username":"emqx_u_1",
          "topic":"Topic/A",
          "action":"sub",
          "access": "allow"
        },
        {
          "topic":"Topic/+",
          "action":"pubsub",
          "access": "deny"
        }
      ]' \
  http://localhost:8081/api/v4/auth_clientid

## Return
{
  "data": [
    {
      "clientid":"emqx_c_1",
      "topic":"Topic/A",
      "action":"pub",
      "access": "allow",
      "result": "ok"
    },
    {
      "username":"emqx_u_1",
      "topic":"Topic/A",
      "action":"pub",
      "access": "allow"
      "result": "ok"
    },
    {
      "all": "$all",
      "topic":"Topic/+",
      "action":"pubsub",
      "access": "deny"
    },
  ],
  "code": 0
}

GET api/v4/acl/clinetid

查看已经添加的 ACL 规则

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.[].clientidStringClientid
- data.[].topicString主题
- data.[].actionString动作
- data.[].accessString是否允许

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X GET \
  http://localhost:8081/api/v4/acl/clientid

## Return
{
    "meta": {
      "page": 1,
      "limit": 10,
      "count": 1
    },
    "data": [
      {
        "clientid": "emqx_c",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      },
      {
        "clientid": "emqx_c_1",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      },
      {
        "clientid": "emqx_c_2",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      }
    ],
    "code": 0
  }

GET api/v4/acl/username

查看已经添加的 ACL 规则

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.[].usernameStringUsername
- data.[].topicString主题
- data.[].actionString动作
- data.[].accessString是否允许

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X GET \
  http://localhost:8081/api/v4/acl/username

## Return
{
    "meta": {
      "page": 1,
      "limit": 10,
      "count": 1
    },
    "data": [
      {
        "clientid": "emqx_u",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      },
      {
        "clientid": "emqx_u_1",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      },
      {
        "clientid": "emqx_u_2",
        "topic": "Topic/A",
        "action": "pub",
        "access": "allow"
      }
    ],
    "code": 0
  }

GET api/v4/acl/$all

查看已经添加的 ACL 规则

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject规则对象
- data.[].allString$all
- data.[].topicString主题
- data.[].actionString动作
- data.[].accessString是否允许

Examples

## Request
curl -i \
 --basic \
 -u admin:public \
 -X GET \
  http://localhost:8081/api/v4/acl/\$all

## Return
{
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 1
  },
  "data": [
    {
      "all": "$all",
      "topic": "Topic/A",
      "action": "pub",
      "access": "allow"
    },
    {
      "all": "$all",
      "topic": "Topic/+",
      "action": "pubsub",
      "access": "deny"
    }
  ],
  "code": 0
}

GET /api/v4/acl/clientid/{clientid}

查看指定的 ACL 规则。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Parameters:

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataobject规则对象
- data.clientidstringClientID
- data.topicstring主题
- data.actionstring动作
- data.accessstring是否允许

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X GET \
  http://localhost:8081/api/v4/acl/clientid/emqx_c

## Return
{
  "data": {
    "topic": "Topic/A",
    "clientid": "emqx_c",
    "allow": true,
    "action": "pub"
  },
  "code": 0
}

GET /api/v4/acl/username/{username}

查看指定的 ACL 规则。

Path Parameters:

NameTypeRequiredDescription
usernmaeStringTrueUsername

Parameters:

Success response body (json):

nametypedescription
codeinteger0
dataobject规则对象
- data.usernamestringUsername
- data.topicstring主题
- data.actionstring动作
- data.accessstring是否允许

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X GET \
  http://localhost:8081/api/v4/acl/usernmae/emqx_u

## Return
{
  "data": {
    "topic": "Topic/A",
    "username": "emqx_u",
    "allow": true,
    "action": "pub"
  },
  "code": 0
}

DELETE /api/v4/acl/clientid/{clientid}/topic/{topic}

删除指定的 ACL 规则。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID
topicStringTrue主题,可能需要使用 UrlEncode 编码

Parameters:

Success response body (json):

nametypedescription
codeinteger0

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X DELETE \
  http://localhost:8081/api/v4/acl/clientid/emqx_c/topic/Topic%2fA

## Return
{"code": 0}

DELETE /api/v4/acl/username/{usernmae}/topic/{topic}

删除指定的 ACL 规则。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername
topicStringTrue主题,可能需要使用 UrlEncode 编码

Parameters:

Success response body (json):

nametypedescription
codeinteger0

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X DELETE \
  http://localhost:8081/api/v4/acl/username/emqx_u/topic/Topic%2fA

## Return
{"code": 0}

DELETE /api/v4/acl/all/$all/topic/{topic}

删除指定的 ACL 规则。

Path Parameters:

NameTypeRequiredDescription
topicStringTrue主题,可能需要使用 UrlEncode 编码

Parameters:

Success response body (json):

nametypedescription
codeinteger0

Examples:

## Request
curl -i \
 --basic \
 -u admin:public \
 -X DELETE \
  http://localhost:8081/api/v4/acl/all/\$all/topic/Topic%2fA

## Return
{"code": 0}

CLI

内置数据库 认证/访问控制 还提供了 ./bin/emqx_ctl 的管理命令行。

clientid 命令

clientid 命令查询管理内置数据库的 clientid 认证。

命令描述
clientid list列出 clientid 身份验证规则
clientid add <ClientID> <Password>添加 clientid 身份验证规则
clientid update <ClientID> <NewPassword>更新 clientid 身份验证规则
clientid del <ClientID>删除 clientid 身份验证规则

clientid list

列出 clientid 身份验证规则

$ ./bin/emqx_ctl clientid list
emqx_clientid

clientid add <ClientID> <Password>

添加 clientid 身份验证规则

./bin/emqx_ctl clientid add emqx_clientid password
ok

clientid update <ClientID> <NewPassword>

更新 clientid 身份验证规则

$ ./bin/emqx_ctl clientid update emqx_clientid new_password
ok

clientid del <ClientID>

删除 clientid 身份验证规则

$ ./bin/emqx_ctl clientid del emqx_clientid
ok

user 命令

user 命令查询管理内置数据库的 username 认证。

命令描述
user list列出 user 身份验证规则
user add <Username> <Password>添加 user 身份验证规则
user update <Username> <NewPassword>更新 user 身份验证规则
user del <Username>删除 user 身份验证规则

user list

列出 username 身份验证规则

$ ./bin/emqx_ctl user list
emqx_username

user add <Username> <Password>

添加 username 身份验证规则

./bin/emqx_ctl user add emqx_username password
ok

user update <Username> <NewPassword>

更新 username 身份验证规则

$ ./bin/emqx_ctl user update emqx_username new_password
ok

user del <Username>

删除 username 身份验证规则

$ ./bin/emqx_ctl user del emqx_username
ok

acl 命令

user 命令查询管理内置数据库的访问控制。

命令描述
acl list clientid列出 clientid 访问控制规则
acl list username列出 username 访问控制规则
acl list _all列出 $all访问控制规则
acl show clientid <Clientid>查看 clientid 访问控制详情
acl show username <Username>查看 username 访问控制详情
acl aad clientid <Clientid> <Topic> <Action> <Access>增加 clientid 访问控制规则
acl add Username <Username> <Topic> <Action> <Access>增加 username访问控制规则
acl add _all <Topic> <Action> <Access>增加 $all 访问控制规则
acl del clientid <Clientid> <Topic>删除 clientid 访问控制规则
acl del username <Username> <Topic>删除 username 访问控制规则
acl del _all <Topic>删除 $all 访问控制规则

acl list clientid

列出 clientid 访问控制规则

$ ./bin/emqx_ctl acl list clientid             
Acl(clientid = <<"emqx_clientid">> topic = <<"Topic/A">> action = pub access = allow)

acl list username

列出 username 访问控制规则

$ ./bin/emqx_ctl acl list username             
Acl(username = <<"emqx_username">> topic = <<"Topic/A">> action = pub access = allow)

acl list _all

列出 $all 访问控制规则

$ ./bin/emqx_ctl acl list _all 
Acl($all topic = <<"Topic/A">> action = pub access = allow)

acl show clientid <Clientid>

查看 clientid 访问控制详情

$ ./bin/emqx_ctl acl show clientid emqx_clientid
Acl(clientid = <<"emqx_clientid">> topic = <<"Topic/A">> action = pub access = allow)

acl show username <Username>

查看 username 访问控制详情

$ ./bin/emqx_ctl acl show username emqx_username
Acl(username = <<"emqx_username">> topic = <<"Topic/A">> action = pub access = allow)

acl aad clientid <Clientid> <Topic> <Action> <Access>

增加 clientid 访问控制规则

$ ./bin/emqx_ctl acl add clientid emqx_clientid Topic/A pub allow
ok

acl aad username <Username> <Topic> <Action> <Access>

增加 username 访问控制规则

$ ./bin/emqx_ctl acl add username emqx_username Topic/A pub allow
ok

acl aad _all <Topic> <Action> <Access>

增加 $all 访问控制规则

$ ./bin/emqx_ctl acl add _all Topic/A pub allow
ok

acl del clientid <Clientid> <Topic>

删除 clientid 访问控制规则

$ ./bin/emqx_ctl acl del clientid emqx_clientid Topic/A
ok

acl del username <Username> <Topic>

删除 username 访问控制规则

$ ./bin/emqx_ctl acl del username emqx_username Topic/A
ok

acl del _all <Topic

删除 $all 访问控制规则

$ ./bin/emqx_ctl acl del _all Topic/A
ok


    您需要登录后才可以回复