제7장: 보안과 인증

7.1 개요

보안 메커니즘은 프로토콜의 중요한 구성 요소로, 스킬 제공자가 누가 자신의 스킬을 발견하고 호출할 수 있는지 제어할 수 있도록 보장합니다. 프로토콜은 다양한 인증 방식과 접근 제어 정책을 지원하여 개방성과 보안 사이의 균형을 유지합니다.

7.2 접근 제어 정책

3단계 접근 제어

수준	발견 가시성	호출 권한	적용 시나리오
public	모든 사람에게 가시	인증 없이 호출 가능	오픈 API, 공개 지식 베이스
restricted	모든 사람에게 가시	인증 후 호출 가능	상용 API, 유료 서비스
private	인증 후에만 가시	인증 후 호출 가능	내부 도구, 프라이빗 서비스

접근 제어와 발견의 관계

• 미인증 요청이 Well-Known URI에 접근할 때:
  • 모든 public 및 restricted 스킬을 반환
  • private 스킬은 반환하지 않음
• 인증된 요청이 Well-Known URI에 접근할 때:
  • 모든 스킬을 반환(private 포함)

7.3 인증 방식

API Key 인증

가장 간단한 인증 방식으로, HTTP Header를 통해 키를 전달합니다.

Descriptor 선언:

{
  "type": "api_key",
  "description": "HTTP Header를 통해 API Key 전달",
  "header": "X-API-Key"
}

호출 시 Header 첨부:

POST /invoke HTTP/1.1
Host: api.example.com
X-API-Key: sk-your-api-key-here
Content-Type: application/json

OAuth 2.0 인증

세밀한 권한 제어가 필요한 시나리오에 적합합니다.

Descriptor 선언:

{
  "type": "oauth2",
  "oauth2": {
    "authorization_url": "https://example.com/oauth/authorize",
    "token_url": "https://example.com/oauth/token",
    "scopes": {
      "skill:invoke": "스킬 호출",
      "skill:read": "스킬 정보 읽기",
      "skill:admin": "스킬 설정 관리"
    }
  }
}

호출 시 Bearer Token 첨부:

POST /invoke HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

커스텀 인증

비표준 인증 시나리오에 적합합니다. 제공자는 instructions 필드를 통해 인증 방식을 설명합니다.

Descriptor 선언:

{
  "type": "custom",
  "custom": {
    "instructions": "HMAC-SHA256으로 요청 본문에 서명하고, 서명을 X-Signature header에 배치",
    "parameters": [
      {
        "name": "secret_key",
        "type": "string",
        "description": "HMAC 서명용 비밀 키",
        "required": true
      }
    ]
  }
}

인증 없음

공개 스킬은 인증이 필요 없습니다:

{
  "type": "none"
}

7.4 인증 오류 처리

인증 실패(401)

유효한 자격 증명이 제공되지 않은 경우:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required to invoke this skill",
    "details": {
      "required_auth_type": "oauth2",
      "authorization_url": "https://example.com/oauth/authorize"
    }
  }
}

권한 부족(403)

자격 증명은 유효하지만 접근 권한이 없는 경우:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions to invoke this skill",
    "details": {
      "required_scopes": ["skill:invoke"],
      "current_scopes": ["skill:read"]
    }
  }
}

7.5 보안 모범 사례

1. 모든 통신은 HTTPS를 사용해야 함
2. API Key는 Header를 통해 전달하고, URL에 노출되지 않도록 함
3. OAuth 2.0 Token에는 적절한 만료 시간을 설정
4. 스킬 제공자는 남용 방지를 위해 속도 제한을 구현해야 함
5. 민감한 스킬은 private 접근 정책을 사용하여 미인가자의 발견을 방지