authentication-patterns

認証パターン

概要

外部サービスと連携するための一般的な認証パターンです。認証情報の管理、検証、エラー処理に一貫した手法を提供します。

使用する場合

• 外部 API と連携する場合
• 認証情報の検証が必要な場合
• 複数の認証方式を管理する場合
• 認証エラーを適切に処理する場合

使用しない場合

• プロジェクトで leyline のインフラストラクチャパターンを使用していない場合
• サービスアーキテクチャが不要な単純なスクリプトの場合

認証方式

方式	最適な用途	環境変数
API キー	シンプルな連携	{SERVICE}_API_KEY
OAuth	ユーザー認証	ブラウザーベースのフロー
トークン	セッションベース	{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 フラグを付けてコマンドを実行し、利用可能であることを確認します。

対話型認証（シェル）

トークンのキャッシュとセッション管理を伴う対話型認証が必要なワークフローの場合：

# 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 を参照してください

完了条件

• 認証情報が検証されている、または明確な失敗メッセージが表示される
• 認証失敗時に推奨アクションが示される
• スモークテストで認証が機能することを確認できる