はじめに (対象読者・この記事でわかること)

この記事は、Go言語のEchoフレームワークを使ってWeb APIを開発している方、またはこれから開発を始める方を対象としています。特に、ユーザー認証や認可の仕組みにJSON Web Token (JWT) の導入を検討している方に役立つ内容です。

この記事を読むことで、以下の点がわかるようになります。

  • JWTの基本的な概念と、その中でも「クレーム」が果たす役割
  • EchoフレームワークにJWT認証ミドルウェアを組み込む方法
  • JWT内のクレーム情報を利用して、ユーザーの識別やアクセス権限の制御（認可）を実装する具体的な手順

Webアプリケーションにおいて、認証・認可はセキュリティの根幹をなす要素です。本記事を通じて、Echoでの堅牢な認証システム構築の一歩を踏み出しましょう。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - Go言語の基本的な構文と開発環境 - Echoフレームワークの基本的な使い方（ルーティング、ミドルウェアなど） - HTTPプロトコルとREST APIの基礎知識

JWTとEcho、そしてクレームの基本

Web APIにおける認証・認可の主要な手段の一つとして、JSON Web Token (JWT) が広く利用されています。JWTは、情報を安全に表現するためのコンパクトなURLセーフな方法であり、特にステートレスな認証メカニズムに適しています。

JWT (JSON Web Token) とは？

JWTは、以下の3つの部分が.で区切られて構成されています。

  1. Header (ヘッダー): トークンのタイプ（JWT）と使用されている署名アルゴリズム（例: HMAC SHA256）を定義します。
  2. Payload (ペイロード): 「クレーム (Claims)」と呼ばれる情報が格納される部分です。ユーザーID、ロール、トークンの有効期限など、様々なデータをJSON形式で保持します。
  3. Signature (署名): ヘッダーとペイロードをエンコードし、秘密鍵で署名することで生成されます。この署名により、トークンが改ざんされていないか検証することができます。

クレーム (Claims) とは？

JWTの核心となるのが「クレーム」です。クレームは、ペイロード部に含まれるJSONオブジェクトのキーと値のペアであり、エンティティ（通常はユーザー）に関するアサーション（主張）を表します。クレームは大きく分けて3種類あります。

  1. Registered Claims (登録済みクレーム): RFC7519で定義された標準的なクレーム。iss (発行者), exp (有効期限), sub (サブジェクト), aud (オーディエンス) などがあります。これらは任意ですが、推奨されています。
  2. Public Claims (公開クレーム): 衝突を避けるためにIANA JWT Registryに登録するか、URIとして定義すべきクレーム。カスタムの情報を追加する際に利用します。
  3. Private Claims (プライベートクレーム): 送信者と受信者が合意すればどのような情報でも格納できるクレーム。ユーザーIDやロール、アクセスレベルなど、アプリケーション固有のデータを格納するのに使われます。

Echoフレームワークでは、これらのクレーム情報に簡単にアクセスし、認証や認可のロジックに利用できます。次のセクションでは、具体的な実装方法を見ていきましょう。

EchoでJWTクレームを活用した認証・認可の実装

ここでは、Echoフレームワークを用いてJWTを生成し、その中のクレーム情報に基づいて保護されたAPIエンドポイントへのアクセスを制御する具体的な手順を解説します。

ステップ1: 環境構築とEchoプロジェクトの初期設定

まずは必要なパッケージをインストールし、Echoアプリケーションの基本的な構造を準備します。

Bash

# プロジェクトディレクトリを作成し、初期化
mkdir echo-jwt-claims-example
cd echo-jwt-claims-example
go mod init echo-jwt-claims-example

# EchoフレームワークとJWTライブラリをインストール
go get github.com/labstack/echo/v4
go get github.com/golang-jwt/jwt/v5
go get github.com/labstack/echo-jwt/v4

次に、簡単なEchoサーバーの起動コードを作成します。main.goというファイルを作成し、以下の内容を記述してください。

Go

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/golang-jwt/jwt/v5"
    echojwt "github.com/labstack/echo-jwt/v4"
    "github.com/labstack/echo/v4"
    "github.com/labstack/echo/v4/middleware"
)

// JWT署名に使う秘密鍵（本番環境では環境変数などから安全に取得すること）
const jwtSecret = "super-secret-key"

// カスタムクレーム構造体
type JwtCustomClaims struct {
    UserID string   `json:"user_id"`
    Role   []string `json:"role"` // ユーザーの役割（例: admin, editor, viewer）
    jwt.RegisteredClaims
}

func main() {
    e := echo.New()

    // ミドルウェア
    e.Use(middleware.Logger())  // リクエストログ出力
    e.Use(middleware.Recover()) // パニックからの回復

    // ルーティング
    e.POST("/login", login)
    e.GET("/", accessible) // 認証不要なエンドポイント

    // JWTミドルウェアを適用するグループ
    r := e.Group("/restricted")
    r.Use(echojwt.WithConfig(echojwt.Config{
        SigningKey: []byte(jwtSecret),
        NewClaimsFunc: func(c echo.Context) jwt.Claims {
            return new(JwtCustomClaims) // カスタムクレームを使用することを宣言
        },
        TokenLookup: "header:Authorization:Bearer", // トークンをAuthorizationヘッダーから取得
    }))
    r.GET("", restricted)
    r.GET("/admin", adminRestricted, checkRole("admin")) // ロールベースの認可を追加

    // サーバー起動
    log.Fatal(e.Start(":1323"))
}

// ... 続く関数定義 ...

ステップ2: JWTの生成とログインエンドポイントの実装

ユーザーがログインすると、JWTを発行します。このJWTには、ユーザーを識別するための情報（ユーザーID、ロールなど）をクレームとして含めます。

Go

// ログインリクエストのボディ
type LoginRequest struct {
    Username string `json:"username"`
    Password string `json:"password"`
}

// ログインハンドラー
func login(c echo.Context) error {
    req := new(LoginRequest)
    if err := c.Bind(req); err != nil {
        return echo.ErrBadRequest
    }

    // 実際の認証ロジック（ここではダミー）
    if req.Username != "testuser" || req.Password != "password" {
        if req.Username != "admin" || req.Password != "adminpass" {
            return echo.ErrUnauthorized
        }
    }

    // クレームの作成
    var claims *JwtCustomClaims
    if req.Username == "admin" {
        claims = &JwtCustomClaims{
            UserID: "admin_123",
            Role:   []string{"admin", "editor"}, // 管理者ロール
            RegisteredClaims: jwt.RegisteredClaims{
                ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour * 72)), // 72時間有効
            },
        }
    } else {
        claims = &JwtCustomClaims{
            UserID: "user_456",
            Role:   []string{"viewer"}, // 一般ユーザーロール
            RegisteredClaims: jwt.RegisteredClaims{
                ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour * 72)), // 72時間有効
            },
        }
    }

    // JWTの生成
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

    // 署名してトークン文字列を取得
    t, err := token.SignedString([]byte(jwtSecret))
    if err != nil {
        return err
    }

    return c.JSON(http.StatusOK, echo.Map{
        "token": t,
    })
}

// 認証不要なエンドポイント
func accessible(c echo.Context) error {
    return c.String(http.StatusOK, "認証不要なページです！")
}

このlogin関数では、ユーザー名とパスワードを検証し（今回はダミーロジック）、成功すればJwtCustomClaims構造体にユーザーIDとロール情報を格納し、JWTを生成して返しています。

ステップ3: JWTミドルウェアの導入とクレームの利用

main関数内のJWTミドルウェアの設定に注目してください。 echojwt.WithConfig を使用して、どの秘密鍵でトークンを検証するか、そしてカスタムクレーム構造体 (JwtCustomClaims) を使用することを指定しています。

NewClaimsFunc は、ミドルウェアがトークンをパースする際にどのクレーム構造体をインスタンス化するかを決定します。ここでnew(JwtCustomClaims)を返すことで、ミドルウェアがトークンのペイロードをJwtCustomClaimsにマッピングしようとします。

認証されたエンドポイント (/restricted グループ) のハンドラー内で、このクレーム情報にアクセスできます。

Go

// 認証が必要なエンドポイント
func restricted(c echo.Context) error {
    user := c.Get("user").(*jwt.Token) // JWTミドルウェアがトークンを"user"キーでコンテキストにセット
    claims := user.Claims.(*JwtCustomClaims) // カスタムクレームに型アサーション

    return c.JSON(http.StatusOK, echo.Map{
        "message": "認証されたページです！",
        "userID":  claims.UserID,
        "role":    claims.Role,
        "expires": claims.ExpiresAt.Time.Format(time.RFC3339),
    })
}

c.Get("user") で取得できるのは*jwt.Token型であり、そのClaimsフィールドがjwt.Claimsインターフェースを実装しています。これを先ほど定義した*JwtCustomClaims型にアサーションすることで、格納されたUserIDやRoleに直接アクセスできるようになります。

ステップ4: 認可ロジックの実装（ロールベースアクセス制御）

クレーム情報を使って、さらに細かなアクセス制御（認可）を実装できます。ここでは、特定のロール（例: "admin"）を持つユーザーのみがアクセスできるエンドポイントを作成します。

Go

// ロールベースの認可ミドルウェア
func checkRole(requiredRole string) echo.MiddlewareFunc {
    return func(next echo.HandlerFunc) echo.HandlerFunc {
        return func(c echo.Context) error {
            user := c.Get("user").(*jwt.Token)
            claims := user.Claims.(*JwtCustomClaims)

            // クレーム内のロールリストを確認
            for _, role := range claims.Role {
                if role == requiredRole {
                    return next(c) // 必要なロールがあれば次のハンドラーへ
                }
            }

            return echo.NewHTTPError(http.StatusForbidden, "アクセス権限がありません")
        }
    }
}

// 管理者のみアクセス可能なエンドポイント
func adminRestricted(c echo.Context) error {
    user := c.Get("user").(*jwt.Token)
    claims := user.Claims.(*JwtCustomClaims)
    return c.JSON(http.StatusOK, echo.Map{
        "message": "管理者のみアクセス可能なページです！",
        "userID":  claims.UserID,
        "role":    claims.Role,
    })
}

main関数で/restricted/adminルートに対し、checkRole("admin")ミドルウェアを適用しています。このミドルウェアは、JWTクレーム内のRoleスライスに"admin"が含まれているかをチェックし、含まれていなければ403 Forbiddenエラーを返します。これにより、特定の権限を持つユーザーのみがアクセスできるAPIエンドポイントを簡単に実現できます。

ハマった点やエラー解決

1. JWT署名キーの不一致

  • 問題: echojwt.WithConfigで指定したSigningKeyと、トークン生成時にtoken.SignedStringで使った秘密鍵が一致しない場合、トークンの検証に失敗し401 Unauthorizedエラーが発生します。
  • 解決策: JWT署名に使用する秘密鍵は、トークンの生成側と検証側で完全に一致している必要があります。本番環境では、環境変数やセキュアなキー管理サービスから取得するようにし、ハードコーディングは避けましょう。

2. クレームの型アサーションエラー

  • 問題: claims.UserID.(string) のように、interface{}から具体的な型へアサーションする際に、実際の型と異なるアサーションを行うとパニックが発生します。特に数値はJSONの仕様上float64として扱われることが多いです。
  • 解決策: value, ok := claims["key"].(Type) のように、カンマOKイディオムを使用して安全に型アサーションを行うか、パニックを防ぐためにエラーハンドリングをしっかり行いましょう。また、カスタムクレーム構造体を使用する場合は、JSONタグが正しく設定されていることを確認してください。例えば、UserIDが数値の場合はintやfloat64として定義するのが適切です。

3. トークンの有効期限切れ

  • 問題: expクレーム（有効期限）が過ぎたJWTを送信すると、echojwtミドルウェアが自動的に検証に失敗し401 Unauthorizedを返します。
  • 解決策: クライアント側でトークンの有効期限を管理し、期限切れが近づいたらリフレッシュトークンを使用して新しいアクセストークンを取得する仕組みを実装することが一般的です。

まとめ

本記事では、Go言語のEchoフレームワークにおいて、JSON Web Token (JWT) の「クレーム」を効果的に活用し、安全な認証・認可システムを実装する方法を解説しました。

  • JWTの基本: ヘッダー、ペイロード（クレーム）、署名から構成され、ステートレスな認証に適していることを理解しました。
  • クレームの役割: ユーザーIDやロールなど、アプリケーション固有の情報を安全に格納し、認証・認可の判断材料として利用できることを確認しました。
  • Echoでの実装: echo-jwt/v4ミドルウェアを導入し、カスタムクレーム構造体を定義することで、JWTの生成から検証、クレーム情報の抽出までを一貫して行えることを示しました。
  • 認可の実現: クレーム内のロール情報を用いたカスタムミドルウェアを作成し、ロールベースのアクセス制御を実装する具体的な手順を学びました。

この記事を通して、Echoアプリケーションにセキュアで柔軟な認証・認可機能を組み込むための実践的な知識と技術を習得できたことでしょう。

今後は、リフレッシュトークンによるトークン更新の仕組みや、より複雑な認可ルール（パーミッションベース認可など）の実装についても検討することで、さらに堅牢なWeb APIを構築できるようになります。

参考資料