如何给 Keycloak 用户加上“部门”、“电话”等自定义属性

Keycloak 是一款开源的用户认证和授权软件。在默认安装情况下，它只给新创建的用户提供了 email 属性，但是在许多应用场景中，客户都会要求给新创建的用户增加诸如“部门”、“电话”等自定义属性。

本文会介绍如何给 keycloak 中新创建的用户添加自定义属性，以及如何在前端中访问到这些属性。

给新用户添加自定义属性

首先通过类似下面的网址访问 keycloak

• https://your_keycloak_ip/auth

如下图所示，点击 users 菜单

系统会呈现用户列表。选择某个用户，点击 edit

下图中是点击了 admin 用户的 edit 后，系统呈现的画面。然后选择 attributes，增加自定义属性。

如下图所示，添加了自定义属性后，选择 add，然后点击 save 完成自定义属性的添加。

在 client 里做 mapper

给用户添加了自定义属性以后，默认情况下这些属性不会包含在用户的 access token 里。我们需要给 keycloak 的 client 增加自定义属性和 token 中的 claim 之间的映射，让 keycloak 的 token 中包含我们定义好的自定义属性。

如下图所示，选择指定的 client 然后点击 edit 进行编辑。在本例中，我们的 client 的名称是 emsclient。

系统会呈现 emsclient 的详情。点击 mapper。

系统展示映射列表，点击 create 添加映射。

如下图所示，在选择映射类型 (mapper type) 时选择 user attribute来添加我们定义好了的用户属性。

按照下图推荐的流程把我们的自定义属性映射到 JWT token 里。

添加成功后，我们就可以检验。JWT token 里是否有我们需要的字段了。

下面是一个keycloak返回的 JWT token 的示例。可以看到最后的部分包含了我们自定义的“姓名”、“角色”、“电话”等属性 (attributes)。现在前端就可以通过 JWT 显示我们想要的用户信息了。

{
    "exp": 1692109592,
    "iat": 1692091592,
    "auth_time": 1692091570,
    "jti": "98c603b8-638f-49bd-9756-4a087c31fdc6",
    "iss": "https://your_keycloak_ip:port/auth/realms/ems",
    "sub": "4a1d2352-5d42-45e1-843b-5ab31545aa94",
    "typ": "Bearer",
    "azp": "emsclient",
    "nonce": "2bb75e79-cd90-4fc0-8235-1425e69b6fa4",
    "session_state": "9397e3b2-f700-4eb1-8465-5c6dade0acd0",
    "acr": "0",
    
    "realm_access": {
      "roles": [
        "default-roles-ems",
        "offline_access",
        "admin",
        "energyManager",
        "uma_authorization"
      ]
    },
      "emsclient": {
        "roles": [
          "ems-admin",
          "ems-energy-manager",
          "ems-dashboard"
        ]
      },
      "broker": {
        "roles": [
          "read-token"
        ]
      },
      "account": {
        "roles": [
          "manage-account",
          "view-applications",
          "view-consent",
          "manage-account-links",
          "delete-account",
          "manage-consent",
          "view-profile"
        ]
      }
    },
    "scope": "openid profile email",
    "姓名": "能效管理员",
    "角色": "管理员角色",
    "email_verified": false,
    "电话": "13800138000",
    "preferred_username": "admin",
    "locale": "zh-CN"
  }

结论

本文详细介绍了如何通过 keycloak 的 user attribute 特性给 JWT token 增加自定义属性的功能。通过这个功能，我们就可以给 keycloak 用户添加我们想要的属性了。