authentication-patterns

身份验证模式

概述

与外部服务集成时的常见身份验证模式。提供一致的凭据管理、验证和错误处理方式。

适用场景

• 与外部 API 集成
• 需要验证凭据
• 管理多种身份验证方式
• 妥善处理身份验证失败

不适用场景

• 项目未使用 leyline 基础设施模式
• 无需服务架构的简单脚本

身份验证方式

方式	最适合	环境变量
API Key	简单集成	{SERVICE}_API_KEY
OAuth	用户身份验证	基于浏览器的流程
Token	基于会话的身份验证	{SERVICE}_TOKEN
无	公共 API	N/A

快速开始

验证身份验证

from leyline.auth import verify_auth, AuthMethod

# API Key verification
status = verify_auth(
    service="gemini", method=AuthMethod.API_KEY, env_var="GEMINI_API_KEY"
)

if not status.authenticated:
    print(f"Auth failed: {status.message}")
    print(f"Action: {status.suggested_action}")

验证： 使用 --help 标志运行命令，以确认其可用。

冒烟测试

def verify_with_smoke_test(service: str) -> bool:
    """Verify auth with simple request."""
    result = execute_simple_request(service, "ping")
    return result.success

验证： 运行 pytest -v，以确认测试通过。

标准流程

步骤 1：检查环境

def check_credentials(service: str, env_var: str) -> bool:
    value = os.getenv(env_var)
    if not value:
        print(f"Missing {env_var}")
        return False
    return True

验证： 使用 --help 标志运行命令，以确认其可用。

步骤 2：向服务验证

def verify_with_service(service: str) -> AuthStatus:
    result = subprocess.run([service, "auth", "status"], capture_output=True)
    return AuthStatus(
        authenticated=(result.returncode == 0), message=result.stdout.decode()
    )

验证： 使用 --help 标志运行命令，以确认其可用。

步骤 3：处理失败

def handle_auth_failure(service: str, method: AuthMethod) -> str:
    actions = {
        AuthMethod.API_KEY: f"Set {service.upper()}_API_KEY environment variable",
        AuthMethod.OAUTH: f"Run '{service} auth login' for browser auth",
        AuthMethod.TOKEN: f"Refresh token with '{service} token refresh'",
    }
    return actions[method]

验证： 使用 --help 标志运行命令，以确认其可用。

集成模式

# In your skill's frontmatter
dependencies: [leyline:authentication-patterns]

验证： 使用 --help 标志运行命令，以确认其可用。

交互式身份验证（Shell）

对于需要交互式身份验证、令牌缓存和会话管理的工作流：

# Source the interactive auth script
source plugins/leyline/scripts/interactive_auth.sh

# Ensure authentication before proceeding
ensure_auth github || exit 1
ensure_auth gitlab || exit 1
ensure_auth aws || exit 1

# Continue with authenticated operations
gh pr view 123
glab issue list
aws s3 ls

功能：

• ✅ 支持 GitHub、GitLab、AWS 等平台的交互式 OAuth 流程
• ✅ 令牌缓存（5 分钟 TTL）
• ✅ 会话持久化（24 小时 TTL）
• ✅ 兼容 CI/CD（自动检测非交互式环境）
• ✅ 支持多种服务

完整文档请参阅 modules/interactive-auth.md。

详细资源

• 身份验证方式：请参阅 modules/auth-methods.md，了解方式详情
• 验证：请参阅 modules/verification-patterns.md，了解测试模式
• 交互式：请参阅 modules/interactive-auth.md，了解基于 Shell 的身份验证流程

完成标准

• 凭据已验证，或提供了清晰的失败消息
• 为身份验证失败提供建议的操作
• 冒烟测试确认身份验证正常工作