iam

版本信息

项目	内容
组件版本	1.20.3
首发版本	1.0.0
文档作者	Larry_Li_006
最后更新	2026-08-01

1. 组件概述

1.1 组件简介

iam（Identity and Access Management）是 openUBMC 系统中负责认证鉴权与会话管理的组件。该组件统一管理各个接口和组件需要用到的认证并建立对应的会话，达到访问控制的目的。

1.2 解决什么问题

iam 组件解决了 BMC 系统中的以下问题：

未认证的主体需要认证（登录）
已认证的主体跳转到其它应用时自动认证（SSO）
已认证的主体访问敏感资源时需要二次认证（MFA）

1.3 核心功能

核心功能一：本地认证，支持通过Linux shadow形式认证、HTTPS双向证书认证（MFA）
核心功能二：LDAP配置管理，支持最多6个域控制器，每个域控制器支持设置5个LDAP组
核心功能三：LDAP远程认证登录WebUI和SSH登录命令行，支持指定域认证和自动匹配域认证
核心功能四：会话管理，支持GUI、Redfish、CLI、KVM、VNC、VIDEO、SSO、板间通信8种会话类型的创建、验证、删除、超时控制
核心功能五：账号锁定配置，支持可配置的锁定阈值和时长

1.4 关键术语表

术语	解释
PAM tally	Linux可插拔认证模块的失败计数机制，libiam在 `/dev/shm/tallylog/` 下维护每个用户的认证失败次数和锁定状态
LDAP	Lightweight Directory Access Protocol（轻量级目录访问协议）是一种用于访问和维护分布式目录信息服务的应用协议。
MFA	Multi-Factor Authentication（多因素身份验证）是一种安全机制，要求用户在登录或访问系统时，必须提供两种或两种以上不同维度的身份证明，才能获准访问
SSO	Single Sign-On（单点登录）是一种身份验证服务，允许用户仅使用一组凭据（如用户名和密码），即可登录并访问多个互相信任的独立应用或系统
CSRF	Cross-Site Request Forgery（跨站请求伪造）是一种常见的 Web 安全漏洞

1.5 外部交互边界图

2. API 使用说明与示例

2.1 LDAP域控制器

bash

NAME                                TYPE      SIGNATURE             RESULT/VALUE           FLAGS
.SetBindDnPassword                  method    a{ss}ay               -                      -

功能说明

设置LDAP域控制器绑定密码。

属性	内容
接口名	bmc.kepler.AccountService.LDAP.LDAPController
首发版本	1.0.11
废弃状态	正常可用

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
SetBindDnPassword	a{ss}ay	-	设置LDAP域控制器绑定密码	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 ay: 字节数组形式的密码

返回值与异常

返回值类型	含义	触发条件	处理建议
InvalidIndex	设置域控制器绑定密码失败	域控制器ID错误	使用正确的域控制器ID（1~6）
PropertyValueExceedsMaxLength	设置域控制器绑定密码失败	密码长度超过限制	使用的密码长度不超过20
PropertyValueFormatError	设置域控制器绑定密码失败	密码不是字节类型	传入字节类型的密码
-	设置域控制器绑定密码成功	NA	NA

应用场景

配置1~6号LDAP域控制器的代理用户的认证密码。

限制条件

接口仅支持在/bmc/kepler/AccountService/LDAP/LDAPController/<ID>使用，ID取值范围为1~6。
认证密码取值范围为1～20个字符，由数字、英文字母和特殊字符组成

调试示例

命令行调试

bash

busctl --user call bmc.kepler.iam \
 /bmc/kepler/AccountService/LDAP/LDAPController/1  bmc.kepler.AccountService.LDAP.LDAPController \
SetBindDnPassword a{ss}ay 3 Interface CLI UserName <当前登录管理员> ClientAddr 127.0.0.1  <密码长度>  <字节数组形式的认证密码>

响应示例：

成功：<无返回值>

失败：Call failed: {"name":"StringValueTooLong","format":"The string %s exceeds the length limit %s.","registry_prefix":"openUBMC","args_with_index":["%1:8K8K8K8K8K8K8K8K8K8KC",20],"params":["8K8K8K8K8K8K8K8K8K8KC",20]}


适用版本
    1.0.11 及以上

2.2 认证

通过从上下文中获取用户需要创建的会话类型（GUI、Redfish、CLI）进行用户登录认证。

bash

NAME                                      TYPE      SIGNATURE   RESULT/VALUE                             FLAGS
.Authenticate                             method    a{ss}says   iasya{ss}                                -

功能说明

属性	内容
接口名	bmc.kepler.AccountService.Authentication
首发版本	1.0.11
废弃状态	正常可用

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
Authenticate	a{ss}says	iasya{ss}	用户登录认证	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 s: 用户名, 不能是预置内部用户 ay: 密码, 长度满足最小密码长度（可修改）~512 s: 登录域名标识。（ "" - 空值等同于"AutomaticMatching"; "AutomaticMatching" - 自动匹配本地认证和LDAP远程认证; "LocaliBMC" - 本地认证; "RemoteAutoMatching": LDAP远程认证）出参： i: 用户id as: 用户权限集合 a{ss}：包含额外信息的对象。

返回值与异常

返回值类型	含义	触发条件	处理建议
AuthorizationFailed	认证失败	用户名不符合规则；密码不满足长度要求; 用户名或密码错误;用户未使能	检查用户名和密码是否正确且使能
UserLocked	认证失败	用户已锁定	等待用户解锁后重试
iasya{ss}	认证成功	NA	NA

应用场景

用户登录认证

限制条件

调试示例

命令行调试

bash

busctl --user call bmc.kepler.iam \
/bmc/kepler/AccountService/Authentication bmc.kepler.AccountService.Authentication \
Authenticate a{ss}says 3 Interface CLI UserName <用户名> ClientAddr 127.0.0.1 <用户名> <密码长度>  <字节数组形式的密码> ""

响应示例：

成功：iasya{ss} 3 2 "ConfigureSelf" "ReadOnly" 2 0
失败：Call failed: {"format":"Authorization failed because the user name or password is incorrect, or your account is locked.","name":"AuthorizationFailed","registry_prefix":"openUBMC"}

适用版本
    1.0.11 以上

2.3 会话管理

不同会话类型的创建、删除。

bash

NAME                                      TYPE      SIGNATURE   RESULT/VALUE                             FLAGS
.DeleteAllSessions                  method    a{ss}yy          -             -
.GetCLISessionList                  method    a{ss}            a(ssssass)    -
.GetSessionLogoutType               method    a{ss}s           y             -
.NewRemoteConsoleSession            method    a{ss}syy         ss            -
.NewSession                         method    a{ss}sayyssa{ss} sss           -

功能说明

属性	内容
接口名	bmc.kepler.SessionService.Sessions
首发版本	1.0.11
废弃状态	正常可用

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
GetCLISessionList	a{ss}	a(ssssass)	获取所有CLI会话	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等出参： a(ssssass): CLI会话列表, 会话信息依次为：会话id，用户名，请求地址，登录时间，权限集合，会话类型
DeleteAllSessions	a{ss}yy	-	删除所有会话	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 y: 会话类型, 枚举值见下方表格 y: 会话退出类型，枚举值见下方表格
GetSessionLogoutType	a{ss}s	y	获取会话登出类型	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 s: 会话id 出参： y: 会话退出类型，枚举值见下方表格
NewSession	a{ss}sayyssa{ss}	sss	创建本地会话	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 s: 用户名 ay: 密码, 长度满足最小密码长度（可修改）~512 y: GUI/Redfish/SSO/KVM会话枚举值 s: 登录域名标识。（ "" - 空值等同于"AutomaticMatching"; "AutomaticMatching" - 自动匹配本地认证和LDAP远程认证; "LocaliBMC" - 本地认证; "RemoteAutoMatching": LDAP远程认证） s: IP地址 a{ss}：包含额外信息的对象。出参： s: 会话token s: CSRF token s: 会话id
NewRemoteConsoleSession	a{ss}syy	ss	创建KVM/Video会话	入参： a{ss}: 请求上下文，包括请求接口，IP地址，用户名等 s: 本地会话token y: KVM/Video会话枚举值 y: 会话模式。（0 - 共享模式; 1 - 独占模式）出参： s: 会话token s: 会话id

会话类型：

类型	枚举值	描述
GUI	0	WebUI登录会话
Redfish	1	Redfish会话
CLI	2	SSH登录会话
SSO	3	SSO会话
KVM	4	KVM登录会话
VNC	5	VNC登录会话
KVM_VMM	6	KVM_VMM登录会话
VIDEO	7	VIDEO登录会话
InterChassis	8	板间通信会话

会话退出类型：

类型	枚举值	描述
SessionLogout	0	会话主动退出
SessionTimeout	1	会话超时退出
SessionKickout	2	会话被管理员踢出
SessionRelogin	3	会话被其他设备登录的相同用户挤出
AccountConfigChange	4	因用户信息更改会话被注销
BMCConfigChange	5	因BMC配置变更会话被注销

返回值与异常

返回值类型	含义	触发条件	处理建议
SessionStillAlive	会话依然在线	获取在线会话的登出类型	会话退出后再获取会话的登出类型
AuthorizationFailed	创建会话失败	用户名不符合规则；密码不满足长度要求; 用户名或密码错误;用户未使能	检查用户名和密码是否正确且使能
NoValidSession	会话不存在	通过不存在的本地会话创建KVM会话	使用正确的本地会话token

应用场景

创建、删除不同类型的会话
管理超时会话

限制条件

调试示例

命令行调试

bash

busctl --user call bmc.kepler.iam \
/bmc/kepler/SessionService/Sessions  bmc.kepler.SessionService.Sessions GetCLISessionList  a{ss} 0

响应示例：

成功：a(ssssass) 1 "cli52169" "Administrator" "127.0.0.1" "2026-08-01T03:43:05+00:00" 9 "ConfigureSelf" "DiagnoseMgmt" "PowerMgmt" "SecurityMgmt" "VMMMgmt" "ReadOnly" "KVMMgmt" "BasicSetting" "UserMgmt" "CLI"

失败：NA

适用版本
    1.0.11 以上


busctl --user call bmc.kepler.iam \
/bmc/kepler/SessionService/Sessions  bmc.kepler.SessionService.Sessions DeleteAllSessions  a{ss}yy 0 1 0

响应示例：

成功：<无返回值>

失败：NA

适用版本
    1.0.11 以上


busctl --user call bmc.kepler.iam \
/bmc/kepler/SessionService/Sessions  bmc.kepler.SessionService.Sessions GetSessionLogoutType  a{ss}s 0 cli23749

响应示例：

成功：y 2

失败：Call failed: {"format":"The session is still alive.","name":"kepler.iam.SessionStillAlive"}

适用版本
    1.0.11 以上


busctl --user call bmc.kepler.iam \
/bmc/kepler/SessionService/Sessions  bmc.kepler.SessionService.Sessions NewSession  a{ss}sayyssa{ss} \
3 Interface Redfish UserName <用户名> ClientAddr 127.0.0.1 <用户名> <密码长度>  <字节数组形式的密码> 1 "" "127.0.0.1" 0

响应示例：

成功：sss "xxxx" "xxxxx" "xxxxx"

失败：Call failed: {"format":"Authorization failed because the user name or password is incorrect, or your account is locked.","name":"AuthorizationFailed","registry_prefix":"openUBMC"}

适用版本
    1.0.11 以上


busctl --user call bmc.kepler.iam \
/bmc/kepler/SessionService/Sessions  bmc.kepler.SessionService.Sessions NewRemoteConsoleSession  a{ss}syy 0  <本地会话token> 4 0

响应示例：

成功：ss "xxxxxxxxx" "xxxxx"

失败：Call failed: {"format":"There is no valid session established with the implementation.","name":"NoValidSession","registry_prefix":"Base"}

适用版本
    1.0.11 以上

3. 组件扩展案例

3.1 扩展新的会话类型

在 domain/session_type/ 下新建 session_<type>.lua，继承基础 session 模板
在 domain/session_type_collection.lua 注册类型映射
在 service/session_service.lua 中新增 new_<type>_session 方法
在 interface/mdb/session_service_mdb.lua 添加 MDB 路径
添加对应 UT/IT 测试用例

4. 日志说明

4.1 一键日志收集

文件路径	内容说明
/var/log/app.log	iam 组件日志
/var/log/operation.log	iam 操作日志
/var/log/framework.log	iam 启动日志

4.2 关键日志信息

日志片段	日志级别	含义解读	建议处理动作
2026-08-01 07:23:05.390935 iam NOTICE: xxxxxx	NOTICE	iam 组件重要功能执行节点日志	用于判断重要功能执行到的节点状态
2026-08-01 07:23:05.390939 iam WARNING: xxxxxx	WARNING	iam 组件告警日志	用于记录功能执行告警的原因
2026-08-01 07:23:05.390939 iam ERROR: xxxxxx	ERROR	iam 组件错误日志	用于记录功能执行错误的原因
2026-08-01 07:44:20 Redfish,xxxxxx,iam,User xxx(x.x.x.x) login successfully/failed	OPERATION	用户登录成功或失败的操作日志	用于判断用户登录是否成功

5. 问题定界指南

5.1 典型问题定界

现象描述	是否为本组件问题	判断依据	关键证据收集方法
CLI登录失败	可能是	显示认证失败	查看SSH登录报错信息，是否进行到认证环节失败
浏览器BMC登录失败	是	认证登录归属于iam管理	查看app.log的报错日志
LDAP认证失败	可能是	ldap认证登录归属于iam管理	1. 查看app.log的ldap相关报错日志 2. 查看ldap域认证服务器是否正常

5.2 错误码速查表

错误码	含义	可能原因	排查建议
StringValueTooLong	字符串类型参数超长	传入的字符串参数长度超过限制	查看app.log的报错信息，根据报错日志信息找到对应的源码，查看参数长度限制
AuthorizationFailed	认证失败	1. 用户名和密码错误或者用户名不存在 2. 用户被锁定	1. 检查用户名是否存在，密码是否正确。2. 使用管理员通过安全日志查看用户是否锁定。 3. 让管理员修改密码重试。 4. 查看app.log的报错信息
NoValidSession	会话不存在	会话已退出或会话ID无效	telnet登录，执行`busctl --user tree bmc.kepler.iam \| grep Sessions`查看会话ID
AuthorizationUserLocked	用户已锁定	用户被管理员锁定（区分于认证失败多次的被动锁定）	1. 使用管理员通过日志查看是否被锁定。 2. 管理员解锁用户。 3. 查看app.log的报错信息

5.3 调试方法

开启调试日志

bash

# 开启 iam 详细日志
busctl --user call bmc.kepler.iam \
/bmc/kepler/iam/MicroComponent \
bmc.kepler.MicroComponent.Debug SetDlogLevel a{ss}sy 0 debug 1

# 查看实时日志
tail -f /var/log/app.log | grep iam

复现问题方法

前置条件设置：

确认网络服务正常运行
确保 iam 服务正常运行

操作步骤：

telnet连接环境，查询当前服务配置和状态
使用用户名和密码进行本地认证登录
观察是否认证成功

预期结果：

服务状态变化正确
本地认证登录成功

6. 常见问题解答

Q1：错误密码连续登录失败未提示锁定错误？

问题描述

使用错误密码连续登录5次以上触发锁定，提示信息和使用错误密码登录一样。

json

{
    "error": [
        {
            "code": "AuthorizationFailed",
            "message": "Authorization failed because the user name or password is incorrect, or your account is locked."
        }
    ]
}

一句话答案

因安全性要求和防止密码暴力破解，因错误认证信息而登录失败的，一律返回模糊的错误提示信息。

根因说明

因安全性要求和防止密码暴力破解，只返回了模糊的错误提示信息。

解决方案
1. 用另一个管理员账号登录，查看安全日志，查看用户是否是被主动锁定还是认证失败触发的被动锁定。
2. 根据业界通用安全实践，保持模糊的错误提示信息.
规避方案

无

适用版本

1.0.11 及以上

iam ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

1.2 解决什么问题 ​

1.3 核心功能 ​

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 LDAP域控制器 ​

功能说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.2 认证 ​

功能说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.3 会话管理 ​

功能说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

3. 组件扩展案例 ​

3.1 扩展新的会话类型 ​

4. 日志说明 ​

4.1 一键日志收集 ​

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

复现问题方法 ​

6. 常见问题解答 ​

Q1：错误密码连续登录失败未提示锁定错误？ ​

iam

版本信息

1. 组件概述

1.1 组件简介

1.2 解决什么问题

1.3 核心功能

1.4 关键术语表

1.5 外部交互边界图

2. API 使用说明与示例

2.1 LDAP域控制器

功能说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.2 认证

功能说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.3 会话管理

功能说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

3. 组件扩展案例

3.1 扩展新的会话类型

4. 日志说明

4.1 一键日志收集

4.2 关键日志信息

5. 问题定界指南

5.1 典型问题定界

5.2 错误码速查表

5.3 调试方法

开启调试日志

复现问题方法

6. 常见问题解答

Q1：错误密码连续登录失败未提示锁定错误？