authz-keycloak

authz-keycloak 插件支持与 Keycloak 集成以对用户进行身份验证和授权。有关此插件中可用配置选项的更多信息，请参阅 Keycloak 的授权服务指南。

虽然该插件是为 Keycloak 开发的，但理论上它可以与其他符合 OAuth/OIDC 和 UMA 标准的身份提供商一起使用。

示例

以下示例演示了如何在不同场景下配置 authz-keycloak。

在开始之前，请完成 Keycloak 的初步设置。

设置 Keycloak

启动 Keycloak

在 Docker 中以开发模式启动一个名为 apisix-quickstart-keycloak 的 Keycloak 实例，管理员用户名为 quickstart-admin，密码为 quickstart-admin-pass：

docker run -d --name "apisix-quickstart-keycloak" \
  -e 'KEYCLOAK_ADMIN=quickstart-admin' \
  -e 'KEYCLOAK_ADMIN_PASSWORD=quickstart-admin-pass' \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:18.0.2 start-dev

将 Keycloak IP 保存到环境变量中，以便在后续配置中引用：

KEYCLOAK_IP=192.168.42.145    # 替换为你的主机 IP

在浏览器中访问 http://localhost:8080 并点击 Administration Console：

admin-console

输入管理员用户名 quickstart-admin 和密码 quickstart-admin-pass 登录：

admin-signin

创建 Realm

在左侧菜单中，将鼠标悬停在 Master 上，然后在下拉菜单中选择 Add realm：

create-realm

输入 Realm 名称 quickstart-realm 并点击 Create 创建它：

add-realm

创建 Client

点击 Clients > Create 打开 Add Client 页面：

create-client

输入 Client ID 为 apisix-quickstart-client，保持 Client Protocol 为 openid-connect 并点击 Save：

add-client

客户端 apisix-quickstart-client 已创建。跳转到详细页面后，将 Access Type 选择为 confidential：

client-access-type-confidential

当用户在 SSO 期间登录成功后，Keycloak 将携带 state 和 code 将客户端重定向到 Valid Redirect URIs 中的地址。为了演示方便，输入通配符 * 以接受任何重定向 URI：

client-redirect

为客户端启用授权（Authorization），这应该会自动启用分配了 uma_protection 角色的服务账户：

enable-authorization

选择 Save 应用自定义配置。

保存 Client ID 和 Secret

点击 Clients > apisix-quickstart-client > Credentials，并从 Secret 中复制客户端密钥：

client-secret

将 OIDC Client ID 和 Secret 保存到环境变量：

OIDC_CLIENT_ID=apisix-quickstart-client
OIDC_CLIENT_SECRET=bSaIN3MV1YynmtXvU8lKkfeY0iwpr9cH  # 替换为你的值

请求访问令牌 (Access Token)

从 Keycloak 请求访问令牌：

curl -i "http://$KEYCLOAK_IP:8080/realms/quickstart-realm/protocol/openid-connect/token" -X POST \
  -d 'grant_type=client_credentials' \
  -d 'client_id='$OIDC_CLIENT_ID'' \
  -d 'client_secret='$OIDC_CLIENT_SECRET''

你应该会看到类似于以下的响应：

{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJoT3ludlBPY2d6Y3VWWnYtTU42bXZKMUczb0dOX2d6MFo3WFl6S2FSa1NBIn0.eyJleHAiOjE3MDM4MjU1NjQsImlhdCI6MTcwMzgyNTI2NCwianRpIjoiMWQ4NWE4N2UtZDFhMC00NThmLThiMTItNGZiYWM2ODA5YmYwIiwiaXNzIjoiaHR0cDovLzE5Mi4xNjguMS44Mzo4MDgwL3JlYWxtcy9xdWlja3N0YXJ0LXJlYWxtIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjE1OGUzOWFlLTk0YjAtNDI3Zi04ZGU3LTU3MTRhYWYwOGYzOSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwaXNpeC1xdWlja3N0YXJ0LWNsaWVudCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1xdWlja3N0YXJ0LXJlYWxtIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SG9zdCI6IjE3Mi4xNy4wLjEiLCJjbGllbnRJZCI6ImFwaXNpeC1xdWlja3N0YXJ0LWNsaWVudCIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1hcGlzaXgtcXVpY2tzdGFydC1jbGllbnQiLCJjbGllbnRBZGRyZXNzIjoiMTcyLjE3LjAuMSJ9.TltzSXqrJuVID7aGrb35jn-oc07U_-jugSn-3jKz4A44LwtAsME_8b3qkmR4boMOIht_5pF6bnnp70MFAlg6JKu4_yIQDxF_GAHjnZXEO8OCKhtIKwXm2w-hnnJVIhIdGkIVkbPP0HfILuar_m0hpa53VpPBGYR-OS4pyh0KTUs8MB22xAEqyz9zjCm6SX9vXCqgeVkSpRW2E8NaGEbAdY25uY-ZC4dI_pON87Ey5e8GdD6HQLXQlGIOdCDi3N7k0HDoD9TZRv2bMRPfy4zVYm1ZlClIuF79A-ZBwr0c-XYuq7t6EY0gPGEXB-s0SaKlrIU5S9JBeVXRzYvqAih41g","expires_in":300,"refresh_expires_in":0,"token_type":"Bearer","not-before-policy":0,"scope":"email profile"}

将令牌保存到环境变量：

# 替换为你的访问令牌
ACCESS_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJoT3ludlBPY2d6Y3VWWnYtTU42bXZKMUczb0dOX2d6MFo3WFl6S2FSa1NBIn0.eyJleHAiOjE3MDM4MjU1NjQsImlhdCI6MTcwMzgyNTI2NCwianRpIjoiMWQ4NWE4N2UtZDFhMC00NThmLThiMTItNGZiYWM2ODA5YmYwIiwiaXNzIjoiaHR0cDovLzE5Mi4xNjguMS44Mzo4MDgwL3JlYWxtcy9xdWlja3N0YXJ0LXJlYWxtIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6IjE1OGUzOWFlLTk0YjAtNDI3Zi04ZGU3LTU3MTRhYWYwOGYzOSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFwaXNpeC1xdWlja3N0YXJ0LWNsaWVudCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1xdWlja3N0YXJ0LXJlYWxtIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SG9zdCI6IjE3Mi4xNy4wLjEiLCJjbGllbnRJZCI6ImFwaXNpeC1xdWlja3N0YXJ0LWNsaWVudCIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1hcGlzaXgtcXVpY2tzdGFydC1jbGllbnQiLCJjbGllbnRBZGRyZXNzIjoiMTcyLjE3LjAuMSJ9.TltzSXqrJuVID7aGrb35jn-oc07U_-jugSn-3jKz4A44LwtAsME_8b3qkmR4boMOIht_5pF6bnnp70MFAlg6JKu4_yIQDxF_GAHjnZXEO8OCKhtIKwXm2w-hnnJVIhIdGkIVkbPP0HfILuar_m0hpa53VpPBGYR-OS4pyh0KTUs8MB22xAEqyz9zjCm6SX9vXCqgeVkSpRW2E8NaGEbAdY25uY-ZC4dI_pON87Ey5e8GdD6HQLXQlGIOdCDi3N7k0HDoD9TZRv2bMRPfy4zVYm1ZlClIuF79A-ZBwr0c-XYuq7t6EY0gPGEXB-s0SaKlrIU5S9JBeVXRzYvqAih41g

使用延迟加载路径和资源注册端点

以下示例演示了如何配置插件使用资源注册端点（resource registration endpoint）动态解析请求 URI 到资源，而不是使用静态权限。

创建一个路由 authz-keycloak-route 如下：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "authz-keycloak-route",
    "uri": "/anything",
    "plugins": {
      "authz-keycloak": {
        "lazy_load_paths": true,
        "resource_registration_endpoint": "http://'"$KEYCLOAK_IP"':8080/realms/quickstart-realm/authz/protection/resource_set",
        "discovery": "http://'"$KEYCLOAK_IP"':8080/realms/quickstart-realm/.well-known/uma2-configuration",
        "client_id": "'"$OIDC_CLIENT_ID"'",
        "client_secret": "'"$OIDC_CLIENT_SECRET"'"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

❶ 将 lazy_load_paths 设置为 true。

❷ 将 resource_registration_endpoint 设置为 Keycloak 的 UMA 兼容资源注册端点。当 lazy_load_paths 为 true 时必填。

❸ 将 discovery 设置为 Keycloak 授权服务的发现文档端点。

❹ 将 client_id 设置为之前创建的 Client ID。

❺ 将 client_secret 设置为之前创建的 Client Secret。当 lazy_load_paths 为 true 时必填。

向路由发送请求：

curl "http://127.0.0.1:9080/anything" -H "Authorization: Bearer $ACCESS_TOKEN"

你应该会看到类似于以下的 HTTP/1.1 200 OK 响应：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer eyJhbGciOiJSU...",
    ...
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 108.180.51.111",
  "url": "http://127.0.0.1/anything"
}

使用静态权限

以下示例演示了如何在 Keycloak 中为关联了 Client Scope 策略的权限配置 Scope，并配置 authz-keycloak 插件使用静态权限。

在 Keycloak 中创建 Scope

转到 Clients > apisix-quickstart-client > Authorization > Authorization Scopes，然后点击 Create 打开 Add Scope 页面：

add-scope

输入 Scope 名称为 access 并点击 Save：

create-new-scope

在 Keycloak 中创建资源

转到 Clients > apisix-quickstart-client > Authorization > Resources 并点击 Create 打开 Add Resource 页面：

create-resource

输入资源名称 httpbin-anything，URI /anything，Scope access，然后点击 Save：

save-resource

在 Keycloak 中创建 Client Scope

转到 Client Scopes 并点击 Create 打开 Add client scope 页面：

create-client-scope

输入 Scope 名称 httpbin-access 并点击 Save：

save-client-scope

在 Keycloak 中创建 Policy

转到 Clients > apisix-quickstart-client > Authorization > Policies > Create Policies，并从下拉列表中选择 Client Scope 打开 Add Client Scope Policy 页面：

create-policy

为 Client Scope httpbin-access 输入 Policy 名称 access-client-scope-policy，勾选 Required，然后点击 Save：

save-policy

在 Keycloak 中创建 Permission

转到 Clients > apisix-quickstart-client > Authorization > Permissions > Create Permissions，并从下拉列表中选择 Scope-Based 打开 Add Scope Permission 页面：

create-permission

输入 Permission 名称 access-scope-perm，选择 access Scope，应用策略 access-client-scope-policy，然后点击 Save：

add-scope-permission

分配 Client Scope

转到 Clients > apisix-quickstart-client > Client Scopes，将 httpbin-access 添加到默认的 Client Scopes 中：

add-client-scope

配置 APISIX

创建一个路由 authz-keycloak-route 如下：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "authz-keycloak-route",
    "uri": "/anything",
    "plugins": {
      "authz-keycloak": {
        "lazy_load_paths": false,
        "discovery": "http://'"$KEYCLOAK_IP"':8080/realms/quickstart-realm/.well-known/uma2-configuration",
        "permissions": ["httpbin-anything#access"],
        "client_id": "apisix-quickstart-client"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

❶ 将 lazy_load_paths 设置为 false。

❷ 将 discovery 设置为 Keycloak 授权服务的发现文档端点。

❸ 将 permissions 设置为资源 httpbin-anything 和 Scope access。

向路由发送请求：

curl "http://127.0.0.1:9080/anything" -H "Authorization: Bearer $ACCESS_TOKEN"

你应该会看到类似于以下的 HTTP/1.1 200 OK 响应：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer eyJhbGciOiJSU...",
    ...
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 108.180.51.111",
  "url": "http://127.0.0.1/anything"
}

如果你移除了 apisix-quickstart-client 的 Client Scope httpbin-access，请求该资源时你应该会收到 401 Unauthorized 响应。

在自定义令牌端点使用密码模式生成令牌

以下示例演示了如何在自定义端点使用密码模式（Password Grant）生成令牌。

在 Keycloak 中创建用户

要使用密码模式，你需要先创建一个用户。

转到 Users > Add user 并点击 Add user：

add-user

输入 Username 为 quickstart-user 并选择 Save：

save-user

点击 Credentials，然后将 Password 设置为 quickstart-user-pass。将 Temporary 切换为 OFF，这样首次登录时不需要更改密码：

set-password

配置 APISIX

创建一个路由 authz-keycloak-route 如下：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "authz-keycloak-route",
    "uri": "/api/*",
    "plugins": {
      "authz-keycloak": {
        "lazy_load_paths": true,
        "resource_registration_endpoint": "http://'"$KEYCLOAK_IP"':8080/realms/quickstart-realm/authz/protection/resource_set",
        "client_id": "'"$OIDC_CLIENT_ID"'",
        "client_secret": "'"$OIDC_CLIENT_SECRET"'",
        "token_endpoint": "http://'"$KEYCLOAK_IP"':8080/realms/quickstart-realm/protocol/openid-connect/token",
        "password_grant_token_generation_incoming_uri": "/api/token"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

❶ 将 token_endpoint 设置为 Keycloak 令牌端点。当未提供发现文档时必填。

❷ 将 password_grant_token_generation_incoming_uri 设置为用户可以获取令牌的自定义 URI 路径。

向配置的令牌端点发送请求。注意请求应使用 POST 方法，并且 Content-Type 为 application/x-www-form-urlencoded：

OIDC_USER=quickstart-user
OIDC_PASSWORD=quickstart-user-pass

curl "http://127.0.0.1:9080/api/token" -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d 'username='$OIDC_USER'' \
  -d 'password='$OIDC_PASSWORD''

你应该会看到包含访问令牌的 JSON 响应，类似于以下内容：

{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6U3FFaXN6VlpuYi1sRWMzZkp0UHNpU1ZZcGs4RGN3dXI1Mkx5V05aQTR3In0.eyJleHAiOjE2ODAxNjA5NjgsImlhdCI6MTY4MDE2MDY2OCwianRpIjoiMzQ5MTc4YjQtYmExZC00ZWZjLWFlYTUtZGY2MzJiMDJhNWY5IiwiaXNzIjoiaHR0cDovLzE5Mi4xNjguNDIuMTQ1OjgwODAvcmVhbG1zL3F1aWNrc3RhcnQtcmVhbG0iLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiMTg4MTVjM2EtNmQwNy00YTY2LWJjZjItYWQ5NjdmMmIwMTFmIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYXBpc2l4LXF1aWNrc3RhcnQtY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6ImIxNmIyNjJlLTEwNTYtNDUxNS1hNDU1LWYyNWUwNzdjY2I3NiIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1xdWlja3N0YXJ0LXJlYWxtIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsInNpZCI6ImIxNmIyNjJlLTEwNTYtNDUxNS1hNDU1LWYyNWUwNzdjY2I3NiIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoicXVpY2tzdGFydC11c2VyIn0.uD_7zfZv5182aLXu9-YBzBDK0nr2mE4FWb_4saTog2JTqFTPZZa99Gm8AIDJx2ZUcZ_ElkATqNUZ4OpWmL2Se5NecMw3slJReewjD6xgpZ3-WvQuTGpoHdW5wN9-Rjy8ungilrnAsnDA3tzctsxm2w6i9KISxvZrzn5Rbk-GN6fxH01VC5eekkPUQJcJgwuJiEiu70SjGnm21xDN4VGkNRC6jrURoclv3j6AeOqDDIV95kA_MTfBswDFMCr2PQlj5U0RTndZqgSoxwFklpjGV09Azp_jnU7L32_Sq-8coZd0nj5mSdbkJLJ8ZDQDV_PP3HjCP7EHdy4P6TyZ7oGvjw","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0YjFiNTQ3Yi0zZmZjLTQ5YzQtYjE2Ni03YjdhNzIxMjk1ODcifQ.eyJleHAiOjE2ODAxNjI0NjgsImlhdCI6MTY4MDE2MDY2OCwianRpIjoiYzRjNjNlMTEtZTdlZS00ZmEzLWJlNGYtNDMyZWQ4ZmY5OTQwIiwiaXNzIjoiaHR0cDovLzE5Mi4xNjguNDIuMTQ1OjgwODAvcmVhbG1zL3F1aWNrc3RhcnQtcmVhbG0iLCJhdWQiOiJodHRwOi8vMTkyLjE2OC40Mi4xNDU6ODA4MC9yZWFsbXMvcXVpY2tzdGFydC1yZWFsbSIsInN1YiI6IjE4ODE1YzNhLTZkMDctNGE2Ni1iY2YyLWFkOTY3ZjJiMDExZiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJhcGlzaXgtcXVpY2tzdGFydC1jbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiYjE2YjI2MmUtMTA1Ni00NTE1LWE0NTUtZjI1ZTA3N2NjYjc2Iiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwic2lkIjoiYjE2YjI2...

示例​

设置 Keycloak​

启动 Keycloak​

创建 Realm​

创建 Client​

保存 Client ID 和 Secret​

请求访问令牌 (Access Token)​

使用延迟加载路径和资源注册端点​

使用静态权限​

在 Keycloak 中创建 Scope​

在 Keycloak 中创建资源​

在 Keycloak 中创建 Client Scope​

在 Keycloak 中创建 Policy​

在 Keycloak 中创建 Permission​

分配 Client Scope​

配置 APISIX​

在自定义令牌端点使用密码模式生成令牌​

在 Keycloak 中创建用户​

配置 APISIX​

示例

设置 Keycloak

启动 Keycloak

创建 Realm

创建 Client

保存 Client ID 和 Secret

请求访问令牌 (Access Token)

使用延迟加载路径和资源注册端点

使用静态权限

在 Keycloak 中创建 Scope

在 Keycloak 中创建资源

在 Keycloak 中创建 Client Scope

在 Keycloak 中创建 Policy

在 Keycloak 中创建 Permission

分配 Client Scope

配置 APISIX

在自定义令牌端点使用密码模式生成令牌

在 Keycloak 中创建用户

配置 APISIX