【亲测免费】 Python Keycloak 使用指南

2026-01-25 05:40:21作者：冯梦姬Eddie

`python-keycloak`是一个Python库，专为访问Keycloak API设计。它简化了与Keycloak服务器交互的过程，无论是处理OAuth授权请求、获取代码或令牌，还是利用Token进行交换操作和管理用户信息。此库支持最新的Keycloak版本及前五个大版本，确保平稳迁移的同时提供对开放ID和管理员API的强大支持。无论你是需要快速集成身份验证功能，还是深入定制用户管理流程，`python-keycloak`都是你的得力助手。

项目地址：https://gitcode.com/gh_mirrors/py/python-keycloak

Python Keycloak 是一个用于访问 Keycloak API 的 Python 包，它简化了在 Python 应用程序中集成 Keycloak 安全服务的过程。

安装指南

您可以通过 Python Package Index (PyPI) 轻松地安装 python-keycloak。在您的命令行中执行以下命令：

pip install python-keycloak

这将下载并安装最新版本的库，使您能够立即开始使用 Keycloak 的功能。

项目使用说明

使用 Keycloak OpenID 进行认证

首先，确保配置好 Keycloak 客户端实例：

from keycloak import KeycloakOpenID

keycloak_openid = KeycloakOpenID(
    server_url="http://localhost:8080/auth/",
    client_id="your_client_id",
    realm_name="your_realm",
    client_secret_key="your_client_secret"
)

随后，您可以执行典型的 OpenID Connect 流程，如获取授权码、访问令牌等：

# 获取Well-Known配置
config_well_known = keycloak_openid.well_known()

# 获取授权URL以进行登录
auth_url = keycloak_openid.auth_url(redirect_uri="callback_url", scope="openid email")

# 获取访问令牌
access_token_response = keycloak_openid.token(code="received_code", redirect_uri="callback_url")
access_token = access_token_response['access_token']

# 用户信息查询
userinfo = keycloak_openid.userinfo(access_token)

利用 Keycloak Admin API 管理资源

对于管理员功能，使用 KeycloakAdmin 类来操作用户和其他管理任务：

from keycloak import KeycloakAdmin, KeycloakOpenIDConnection

# 创建与Keycloak服务器的连接
keycloak_connection = KeycloakOpenIDConnection(
    server_url="http://localhost:8080/auth/", 
    username="admin_username", 
    password="admin_password", 
    realm_name="master", 
    client_id="admin-cli"
)

keycloak_admin = KeycloakAdmin(connection=keycloak_connection)

# 添加新用户示例
new_user = keycloak_admin.create_user({
    "email": "newuser@example.com", 
    "username": "newuser", 
    "enabled": True, 
    "firstName": "New", 
    "lastName": "User"
})

API使用文档摘要

Token操作：
- token(username, password): 获取基于用户名和密码的访问令牌。
- refresh_token(refresh_token): 刷新访问令牌。
- logout(refresh_token): 注销用户会话。
OpenID Connect：
- 方法如上所示，用于处理认证流程。
Admin API：
- create_user(user_data[, exist_ok]): 创建新用户，可选参数exist_ok=False防止重复创建。
- 用户数据应包含必要字段如邮箱、用户名等，以及可选的密码凭据。

注意事项

请确保您的 Keycloak 服务器支持当前使用的库版本。
对于Python环境，选择有安全支持的版本。
查看官方文档以获取更多高级功能和错误处理细节。

通过以上步骤，您现在应该具备了使用 Python Keycloak 库来管理和认证用户的基本技能。详细操作和更复杂的案例请参考官方文档。

python-keycloak