在JumpServer中通过API获取MFA认证的Bearer Token

在JumpServer中通过API获取MFA认证的Bearer Token

【免费下载链接】JumpServer 广受欢迎的开源堡垒机 项目地址: https://gitcode.com/feizhiyun/jumpserver

背景介绍

JumpServer作为一款流行的开源堡垒机系统，提供了完善的多因素认证（MFA）机制来增强系统安全性。当管理员强制启用MFA后，用户需要通过额外的验证步骤才能获取访问令牌（Bearer Token），这对API自动化操作提出了新的挑战。

MFA认证流程解析

在JumpServer中，MFA认证采用两步验证机制：

1. 初始认证请求：用户首先通过标准认证接口提交凭据
2. MFA挑战响应：系统返回MFA验证要求，用户需提供验证码
3. 令牌获取：验证成功后获取最终的Bearer Token

API接口详解

1. 初始认证接口

使用POST方法访问认证端点：

POST /api/v1/authentication/auth/

请求体示例：

{
  "username": "your_username",
  "password": "your_password"
}

2. MFA挑战接口

当初始认证返回MFA要求时，调用挑战接口：

POST /api/v1/authentication/mfa/challenge/

请求体需要包含初始认证返回的MFA标识符和验证码：

{
  "mfa_id": "received_mfa_id",
  "code": "mfa_verification_code"
}

完整获取Token的流程

步骤1：发起初始认证

首先向认证接口发送用户凭据，此时系统会返回两种可能响应：

情况一：无需MFA验证 直接返回Bearer Token，流程结束。

情况二：需要MFA验证 返回包含MFA挑战信息的响应，需要继续下一步。

步骤2：处理MFA挑战

从初始响应中提取MFA相关信息：

• mfa_id：MFA挑战的唯一标识符
• mfa_type：验证类型（如TOTP）
• mfa_url：验证URL

步骤3：提交MFA验证码

使用获取到的MFA标识符和用户提供的验证码（如Google Authenticator生成的6位数字）向MFA挑战接口发起请求。

步骤4：获取最终Token

MFA验证成功后，系统返回完整的认证信息，包含：

• token：Bearer Token
• user：用户信息
• expired_at：令牌过期时间

代码实现示例

以下Python代码展示了完整的MFA认证流程：

import requests

def get_jumpserver_token(base_url, username, password, mfa_code=None):
    # 步骤1：初始认证
    auth_url = f"{base_url}/api/v1/authentication/auth/"
    auth_data = {
        "username": username,
        "password": password
    }
    
    response = requests.post(auth_url, json=auth_data)
    result = response.json()
    
    # 检查是否需要MFA
    if response.status_code == 200 and 'token' in result:
        return result['token']  # 直接返回token
    
    # 步骤2：处理MFA挑战
    if response.status_code == 300 and 'mfa_id' in result:
        mfa_id = result['mfa_id']
        
        # 步骤3：提交MFA验证码
        mfa_url = f"{base_url}/api/v1/authentication/mfa/challenge/"
        mfa_data = {
            "mfa_id": mfa_id,
            "code": mfa_code
        }
        
        mfa_response = requests.post(mfa_url, json=mfa_data)
        mfa_result = mfa_response.json()
        
        if mfa_response.status_code == 200 and 'token' in mfa_result:
            return mfa_result['token']  # 返回最终的token
    
    # 处理错误情况
    raise Exception(f"Authentication failed: {result}")

# 使用示例
try:
    token = get_jumpserver_token(
        "https://your-jumpserver-domain",
        "your_username",
        "your_password",
        "123456"  # MFA验证码
    )
    print(f"Successfully obtained token: {token}")
except Exception as e:
    print(f"Error: {e}")

注意事项

1. 验证码时效性：MFA验证码通常有时效限制（如30秒），需要及时使用
2. 错误处理：妥善处理各种错误情况，包括无效凭据、过期验证码等
3. 令牌管理：获取的Bearer Token需要妥善存储并在后续API请求的Authorization头中使用
4. 安全考虑：避免在代码中硬编码敏感信息，建议使用环境变量或安全配置管理

最佳实践建议

1. 实现重试机制：为MFA验证码过期等情况实现自动重试
2. 添加日志记录：记录认证过程的关键信息便于排查问题
3. 考虑令牌刷新：实现令牌过期前的自动刷新机制
4. 异常处理：针对网络超时、服务器错误等异常情况设计恢复策略

通过以上流程，开发者可以在启用MFA的JumpServer环境中实现自动化的API认证，为后续的批量操作和管理任务奠定基础。这种设计既保证了安全性，又提供了必要的自动化能力。

【免费下载链接】JumpServer 广受欢迎的开源堡垒机 项目地址: https://gitcode.com/feizhiyun/jumpserver