Skip to main content

keycloak

开源身份识别与访问管理系统keycloak

前言​

Keycloak是一种面向现代应用和服务的开源IAM（身份识别与访问管理）解决方案，Keycloak提供了单点登录（SSO）功能，支持OpenID Connect、OAuth 2.0、SAML 2.0标准协议，拥有简单易用的管理控制台，并提供对LDAP、Active Directory以及Github、Google等社交账号登录的支持，做到了非常简单的开箱即用。

快速开始​

基本概念​

realm​

realm是最小项目单元，有独立的资源。

在Keycloak中，Access Type分为三种：

  1. Confidential：用于需要进行浏览器登录的应用，客户端会通过 client secret 获取 access token ，多用于服务器渲染的 Web 系统中。
  2. Public: 针对需要进行浏览器登录的应用，多用于使用vue和react实现的前端项目。
  3. Bearer-only: 对于不需要浏览器登录的应用，只允许通过 bearer token 访问，多用于 RESTful API 场景。

准备工作​

部署dev版

docker run -d --name keycloak -p 18080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.0 start-dev

进入后台创建quickstart realm

image-20240307164132847

创建用户

image-20240308164257966

用户行为可以配置一些信息，例如绑定OTP之类的操作，测试可以默认不选择

SPA应用集成​

按以下文档运行spa demo

https://github.com/keycloak/keycloak-quickstarts/tree/latest/js/spa

访问如图所示

image-20240306164123833

js初始化客户端

  const keycloak = new Keycloak();
  await keycloak.init({ scope: "phone", onLoad: "login-required" });

可以使用userinfo endpoints来验证token

curl http://127.0.0.1:18080/realms/quickstart/protocol/openid-connect/userinfo -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json"

返回

{
    "sub": "7e72c240-ee74-439d-948e-6e3e1080bc1b",
    "email_verified": false,
    "preferred_username": "admin",
    "email": "admin@test.com"
}

apisix集成​

image-20240307165324141

Admin Rest Api​

使用keyloak-python来进行admin api的管理

生产环境配置​

使用docker-compose来部署

version: "3"
services:
  keycloak:
    image: keycloak/keycloak:23.0.0
    command:
      - start
      - --hostname=auth.xxx.com
      - --http-enabled=true
      - --https-port=443
      - --hostname-strict-backchannel=true
      - --hostname-admin-url=https://auth-dashboard.xxx.com
    environment:
      KC_DB: mysql
      KC_DB_URL_HOST: mysql-host
      KC_DB_PASSWORD: 123456
      KC_DB_USERNAME: root
      KC_DB_SCHEMA: keycloak
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "28080:8080"

授权机制Authentication​

AuthorizationSettings配置​

Policy enforcement mode

Policy enforcement mode规定在评估授权请求时如何执行策略。 “Enforcing ”意味着即使没有与给定资源关联的策略，默认情况下也会拒绝请求。 “Permissive”意味着即使没有与给定资源关联的策略，也允许请求。 “Disabled”完全禁用策略评估并允许访问任何资源。

Decision strategy

决策策略规定了如何评估权限以及如何获得最终决策。 “Affirmative”意味着至少一项权限必须评估为积极决策，才能授予对资源及其范围的访问权限。 “Unanimous”意味着所有权限必须评估为积极的决定，以便最终决定也是积极的。

Remote resource management

Should resources be managed remotely by the resource server? If false, resources can be managed only from this Admin UI.

策略​

logic​

在Keycloak中，logic字段用于指定策略的逻辑。logic字段可以是以下几个值之一：

  1. POSITIVE：表示只要有一个策略满足条件，就允许访问。这是默认的逻辑。
  2. NEGATIVE：表示只要有一个策略不满足条件，就拒绝访问。
  3. UNANIMOUS：表示所有策略都必须满足条件，才允许访问。

在这个配置文件中，logic字段的值为POSITIVE，表示只要有一个策略满足条件，就允许访问。这意味着，如果用户具有user角色并且具有访问Protected Resource的权限，那么用户就可以访问Protected Resource。同样，如果用户具有user_premium角色并且具有访问Premium Resource的权限，那么用户就可以访问Premium Resource。

DecisionStrategy​

在Keycloak中，decisionStrategy字段用于指定策略的决策策略。decisionStrategy字段可以是以下几个值之一：

  1. AFFIRMATIVE：表示只要满足config里的任何一个条件，访问就会被允许。换句话说，只要有一个策略允许访问，访问就会被授权，即使其他策略不同意。
  2. UNANIMOUS：表示所有策略都必须满足条件，才允许访问。
  3. CONSENSUS：表示大多数策略必须满足条件，才允许访问。

在这个配置文件中，decisionStrategy字段的值为UNANIMOUS，表示所有策略都必须满足条件，才允许访问。这意味着，如果用户具有user角色并且具有访问Protected Resource的权限，那么用户就可以访问Protected Resource。同样，如果用户具有user_premium角色并且具有访问Premium Resource的权限，那么用户就可以访问Premium Resource。

所有的条件都是在configs里体现出来的。

自定义主题开发​

https://www.keycloak.org/docs/latest/server_development/#_themes

Troubleshooting​

403报错​

https://xxx/realms/master/protocol/openid-connect/login-status-iframe.html/init?client_id=account-console&origin=httpsxxxx

遇到类似这种错误

image-20240312102341964

500报错​

2024/03/08 09:10:28 [error] 50#50: *3128451 [lua] openidc.lua:1098: authenticate(): unhandled request to the redirect_uri: /, client: 1.2.3.4, server: _, request: "GET / HTTP/2.0", host: "xxx.xxx.com"

根据报错信息查看源码https://github.com/zmartzone/lua-resty-openidc/blob/v1.7.6/lib/resty/openidc.lua

image-20240308174433946

redirect_url比较特殊，访问这个url时必须带上code或者state参数

https://github.com/casbin

【1】10 分钟理解什么是 OpenID Connect（OIDC）协议 https://deepzz.com/post/what-is-oidc-protocol.html

【2】js客户端文档 https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter

【3】Use Keycloak with API Gateway to secure APIs https://apisix.apache.org/blog/2022/07/06/use-keycloak-with-api-gateway-to-secure-apis/

【4】How to use Keycloak REST API https://www.mastertheboss.com/keycloak/how-to-use-keycloak-admin-rest-api/

【5】Using the Admin CLI https://www.keycloak.org/docs/23.0.1/server_admin/#using-the-admin-cli