goauthentik/authentik 表达式函数详解与应用指南

goauthentik/authentik 表达式函数详解与应用指南

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik

前言

goauthentik/authentik 是一个功能强大的身份验证和授权系统，它提供了丰富的表达式函数来帮助开发者实现复杂的业务逻辑。本文将深入解析这些核心函数的使用方法和实际应用场景，帮助开发者更好地利用这些工具构建安全可靠的身份验证流程。

正则表达式相关函数

regex_match 函数

regex_match 函数用于检查给定值是否匹配指定的正则表达式模式。这个函数在用户权限验证、输入校验等场景非常有用。

# 检查用户名是否包含"admin"字符串
return regex_match(request.user.username, '.*admin.*')

技术要点：

• 第一个参数可以是任意类型，但通常应为字符串
• 正则表达式使用Python标准语法
• 返回布尔值表示匹配结果

regex_replace 函数

regex_replace 函数用于执行正则表达式替换操作，可以方便地处理字符串格式转换。

# 提取电子邮件地址的本地部分（@之前的内容）
user_email_local = regex_replace(request.user.email, '(.+)@.+', '')

应用场景：

• 数据标准化处理
• 敏感信息脱敏
• 格式转换

列表处理函数

list_flatten 函数

list_flatten 函数用于简化列表结构，特别适合处理可能返回单元素列表的API调用结果。

user = list_flatten(["foo"])  # 返回 "foo"
empty = list_flatten([])      # 返回 None
non_list = list_flatten("bar") # 返回 "bar"

设计考虑：

• 处理空列表时返回None避免异常
• 非列表输入直接返回，提高函数容错性
• 简化单元素列表的访问操作

策略调用函数

ak_call_policy 函数

ak_call_policy 是系统核心功能之一，允许在当前策略执行过程中调用其他策略，实现策略的组合和复用。

result = ak_call_policy("test-policy", foo="bar")
return result.passing

关键特性：

• 支持传递上下文参数
• 返回PolicyResult对象，包含执行结果和消息
• 2023.4版本后支持访问原始返回值(raw_result)

最佳实践：

• 将常用验证逻辑封装为独立策略
• 通过参数传递实现策略的灵活配置
• 合理设计策略间的调用层级，避免循环调用

用户与组管理函数

ak_is_group_member 函数

检查用户是否属于特定组，支持灵活的组属性过滤条件。

# 检查用户是否属于名为"test_group"的组
return ak_is_group_member(request.user, name="test_group")

高级用法：

• 支持多条件组合查询
• 可以检查嵌套组成员关系
• 性能优化：系统会缓存组成员关系

ak_user_by 函数

根据条件查询用户信息，返回User对象或None。

other_user = ak_user_by(username="other_user")

注意事项：

• 查询条件应与用户模型字段对应
• 无结果时返回None，调用方需处理
• 敏感字段访问可能受权限控制

ak_user_has_authenticator 函数

检查用户是否配置了特定类型的认证设备。

# 检查用户是否配置了TOTP设备
has_totp = ak_user_has_authenticator(request.user, device_type="totp")

支持的设备类型：

• totp: 基于时间的一次性密码
• duo: Duo安全设备
• static: 静态恢复代码
• webauthn: Web认证标准设备

事件与JWT相关函数

ak_create_event 函数

创建系统事件记录，用于审计跟踪。

ak_create_event("user_action", action_detail="login_attempt", target=request.user)

特性：

• 自动处理敏感信息
• 支持复杂数据结构(自动JSON序列化)
• 自动保存，无需额外操作

ak_create_jwt 函数

创建JWT令牌，支持灵活的时效配置。

jwt = ak_create_jwt(
    request.user, 
    "my-provider",
    ["openid", "profile"],
    validity="hours=1,minutes=30"
)

时效配置语法：

• 支持多时间单位组合
• 支持浮点数值
• 单位包括：Microseconds, Milliseconds, Seconds, Minutes, Hours, Days, Weeks

网络相关操作

IP地址处理

系统集成了Python ipaddress模块的功能，可以方便地进行IP地址比较和子网验证。

# 检查IP是否在特定子网内
ip_address('192.0.2.1') in ip_network('192.0.2.0/24')

应用场景：

• 基于IP的访问控制
• 地理位置验证
• 网络环境检测

DNS解析功能

提供正向和反向DNS解析能力，内置缓存优化性能。

# 解析域名IP地址
ips = resolve_dns("example.com", 4)  # 仅IPv4

# 反向DNS查询
hostname = reverse_dns("192.0.2.1")

缓存机制：

• 最近32个查询缓存
• 缓存有效期3分钟
• 按IP版本区分缓存

总结

goauthentik/authentik 提供的这些表达式函数构成了系统强大的扩展能力基础。通过合理组合这些函数，开发者可以实现复杂的业务逻辑而无需编写大量自定义代码。理解每个函数的特性和适用场景，将帮助您构建更安全、更灵活的身份验证解决方案。

authentik The authentication glue you need. 项目地址: https://gitcode.com/gh_mirrors/au/authentik