🔐 OpenAPIのセキュリティスキームなるもの

API開発においてセキュリティは最重要課題の一つです。最近、OpenAPIのセキュリティスキームについて勉強したので、学んだことを整理してみます。

OpenAPIでは、様々な認証・認可の仕組みを体系的に定義できることを知り、その柔軟性に驚きました。

📖セキュリティスキームの基本概念

OpenAPIでは、components.securitySchemesでAPIの認証方式を定義します。主な認証タイプは以下の通りです：

HTTP認証 (Basic, Bearer)
APIキー認証
OAuth 2.0
OpenID Connect

それぞれの特徴と使い所を見ていきましょう。

🛡️各認証方式の定義方法

HTTP認証 (Basic, Bearer)

Basic認証

最もシンプルな認証方式で、ユーザー名とパスワードをBase64エンコードして送信します：

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

特徴：
- 実装が簡単
- HTTPSでの使用が必須（平文に近い形で送信されるため）
- 主に開発環境や内部APIで使用
- セッション管理が不要

使用例： Authorization: Basic dXNlcjpwYXNzd29yZA==

Bearer認証（JWT）

トークンベースの認証方式で、現在最も広く使われています：

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Authorizationヘッダーに 'Bearer {token}' 形式で送信

特徴：
- ステートレスな認証が可能
- トークンに有効期限を設定できる
- ユーザー情報やスコープをトークンに含められる
- サーバー側でセッション管理が不要

使用例： Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

APIキー認証

事前に発行されたキーを使用する認証方式です：

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header  # または query, cookie
      name: X-API-Key

特徴：
- パートナー企業や外部サービス連携に最適
- キーごとにレート制限や権限を設定可能
- 実装がシンプル
- ヘッダー、クエリパラメータ、Cookieのいずれかで送信可能

使用例：
- ヘッダー: X-API-Key: abcdef123456
- クエリ: ?api_key=abcdef123456

OAuth 2.0

業界標準の認可フレームワークで、きめ細かいアクセス制御が可能です：

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: 読み取り権限
            write: 書き込み権限
            admin: 管理者権限

特徴：
- 第三者アプリケーションへの認可に最適
- スコープによる細かい権限制御
- 複数の認可フロー（Authorization Code、Client Credentials等）
- リフレッシュトークンによる長期的なアクセス

主なフロー：
- Authorization Code: ユーザー認証が必要なWebアプリ向け
- Client Credentials: サーバー間通信向け
- Implicit: SPAなどのブラウザアプリ向け（非推奨）

OpenID Connect

OAuth 2.0の上に構築された認証レイヤーです：

components:
  securitySchemes:
    OpenIDConnect:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

特徴：
- シングルサインオン（SSO）の実現
- 標準化されたユーザー情報の取得
- IDトークンによる認証情報の提供
- 企業向けの統合認証に最適

メリット：
- ユーザー情報の標準化（名前、メール、プロフィール画像等）
- 複数サービス間でのユーザー認証の統一
- セキュリティトークンの検証が標準化されている

💭 実装時の考慮点

1. エラーレスポンスの統一

認証エラーは適切に定義することが重要だと学びました：

components:
  responses:
    UnauthorizedError:
      description: 認証エラー
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum: [invalid_token, expired_token, missing_token]
              message:
                type: string

2. スコープベースの認可

OAuth2のスコープを使った細かい権限制御：

security:
  - OAuth2:
      - users:read
      - users:write

3. 公開エンドポイントの定義

認証不要なエンドポイントは明示的に定義：

/public/health:
  get:
    security: []  # 空配列で認証不要を表現

🚂Railsでの実装パターン

勉強中に見つけた実装パターンの一例：

# 認証用のConcern
module ApiAuthentication
  extend ActiveSupport::Concern

  included do
    before_action :authenticate_request
  end

  private

  def authenticate_request
    # Authorizationヘッダーから認証方式を判定
    auth_header = request.headers['Authorization']

    if auth_header&.start_with?('Bearer ')
      authenticate_jwt(auth_header.sub('Bearer ', ''))
    elsif request.headers['X-API-Key']
      authenticate_api_key(request.headers['X-API-Key'])
    else
      render_unauthorized_error
    end
  end
end

✨学んだベストプラクティス

最小権限の原則
- 必要最小限のスコープのみ要求する
- デフォルトは認証必須にする
トークンの有効期限
- JWTは短めに設定（15分〜1時間）
- リフレッシュトークンで更新
セキュリティヘッダー
- WWW-Authenticateヘッダーで認証方式を明示
- エラー時は詳細を隠蔽
監査ログ
- 認証の成功/失敗を記録
- 異常なアクセスパターンの検知

🌊 まとめ：セキュリティスキームは奥が深い

OpenAPIのセキュリティスキームについて勉強して、以下のことが分かりました：

学んだこと：

様々な認証方式を統一的に定義できる
複数の認証方式を柔軟に組み合わせられる
ドキュメントとして明確に仕様化できる

セキュリティ要件も欠かさず定義して、AIに読み込ませるぞー！