認証機能の実装準備

ここからハンズオンに入ります。プロジェクトフォルダの初期化、依存パッケージの導入、データベースとモデルの用意までを行います。

1. プロジェクトの準備

任意の場所にjwt-auth-hands-onフォルダを作成し、Visual Studio Codeの「ファイル」→「フォルダーを開く」から作成したjwt-auth-hands-onフォルダを開きます。以降の操作は、Visual Studio Codeのターミナルから行います。

jwt-auth-hands-on/  ← このフォルダを作成

以下のコマンドで、Goがインストールされていることを確認します。

go version

以下のようにGoのバージョンが表示されれば、インストールは確認できています。

go version go1.x.x darwin/arm64

バージョンが表示されない場合は、Goのインストールを先に実施してください。

インストールが確認できたら、モジュールを初期化します。

go mod init jwt-auth-hands-on

以下のような実行結果が表示されます。

go: creating new go.mod: module jwt-auth-hands-on

続いて、必要なパッケージを順に導入します。まず、GinとGORMを取得します。

go get github.com/gin-gonic/gin
go get gorm.io/gorm
go get gorm.io/driver/mysql

次に、JWT操作用のgolang-jwt/jwtと、パスワードハッシュ用のgolang.org/x/crypto/bcryptを取得します。

go get github.com/golang-jwt/jwt/v5
go get golang.org/x/crypto/bcrypt

最後に、.envファイルから接続情報や署名鍵を読み込むためのgodotenvパッケージを導入します。DB接続用のユーザ名・パスワードやJWTの署名鍵といった秘匿情報をコードに直接書かず、.envファイルから環境変数として読み込むために使います。

go get github.com/joho/godotenv

以下のような実行結果が最後のコマンドで表示されます(バージョンは環境により変わります)。

go: added github.com/joho/godotenv v1.5.1

go.modにすべての依存関係が追記されていれば、パッケージの準備は完了です。

2. データベースとモデルの用意

2.1 データベースの作成

認証APIから接続するデータベースを先に作成します。ユーザとリフレッシュトークンの2種類のテーブルを扱うため、それらを保存するauth_hands_onデータベースを作ります。テーブル自体はGORMのAutoMigrateで作成するため、ここではデータベースだけ用意します。

まず、rootユーザでMySQLにログインします。

mysql -u root -p

パスワードを入力してMySQLのプロンプトに切り替わったら、以下のSQLを実行してデータベースを作成します。

CREATE DATABASE auth_hands_on;

以下のような実行結果が表示されます。

Query OK, 1 row affected (0.00 sec)

Query OKが返れば、データベースの作成コマンドは成功しています。念のため、SHOW DATABASES;でauth_hands_onデータベースが一覧に含まれていることを確認します。

SHOW DATABASES;

以下のような実行結果が表示されます(既存のデータベース一覧は環境により変わります)。

+--------------------+
| Database           |
+--------------------+
| auth_hands_on      |
| information_schema |
| mysql              |
| performance_schema |
| sys                |
+--------------------+

auth_hands_onが一覧に含まれていれば、データベースが作成できています。確認できたら、exit;でMySQLのプロンプトを抜けます。

exit;

2.2 .env ファイルの作成

main.goの中にDB接続用のユーザ名・パスワードやJWTの署名鍵を直接書くと、コードを変更するたびに書き換える必要があり、うっかりGitに含めてしまうリスクもあります。ここでは、接続情報と署名鍵を.envファイルにまとめて、Goのコードからは環境変数として読み込む形にします。

Visual Studio Codeのエクスプローラーでjwt-auth-hands-onフォルダを右クリックし、「新しいファイル」を選択して.envファイルを作成します。

jwt-auth-hands-on/
├── go.mod
├── go.sum
└── .env  ← このファイルを作成

作成した.envファイルに以下の内容を記述して保存します。各項目の意味は下記のとおりです。

項目 説明
MYSQL_USER 接続先MySQLのユーザ名を指定する。ここではrootを使う
MYSQL_PASSWORD 上記ユーザのパスワードを指定する。先ほどmysql -u root -pで入力した自分のMySQLパスワードに書き換える
MYSQL_HOST 接続先MySQLのホスト名またはIPアドレスを指定する。ローカルで動作しているMySQLに接続するため127.0.0.1を使う
MYSQL_PORT 接続先MySQLの待ち受けポートを指定する。MySQLのデフォルトである3306を使う
MYSQL_DATABASE 接続先のデータベース名を指定する。先ほど作成したauth_hands_onを指定する
JWT_SECRET JWTの署名に使う秘密鍵を指定する。本番環境では十分な長さのランダム文字列に置き換える
MYSQL_USER=root
MYSQL_PASSWORD=あなたのパスワード
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=auth_hands_on
JWT_SECRET=dev-secret-please-change

MYSQL_PASSWORD=あなたのパスワードの右辺は、必ず先ほどmysql -u root -pで入力した自分のMySQLパスワードに書き換えてください。書き換えを忘れるとGoからのDB接続に失敗し、次の起動時にエラーになります。

2.3 モデルの定義

続いて、ユーザとリフレッシュトークンを表すモデルを定義します。この後に作るmain.go(db.AutoMigrate(&User{}, &RefreshToken{})でテーブルを自動作成)や、後続で追加するヘルパー・ハンドラがUser・RefreshToken構造体を参照するため、参照される側の型を先に用意しておきます。

Visual Studio Codeのエクスプローラーでjwt-auth-hands-onフォルダを右クリックし、「新しいファイル」を選択してmodel.goを作成します。

jwt-auth-hands-on/
├── .env
├── go.mod
├── go.sum
└── model.go  ← このファイルを作成

作成したmodel.goに以下の内容を記述して保存します。これは、ユーザとリフレッシュトークンの2種類のモデル定義です。

package main

import "time"

type User struct {
	ID           uint      `gorm:"primaryKey" json:"id"`
	Email        string    `gorm:"size:255;uniqueIndex;not null" json:"email"`
	PasswordHash string    `gorm:"size:255;not null" json:"-"`
	CreatedAt    time.Time `json:"created_at"`
}

type RefreshToken struct {
	ID        uint       `gorm:"primaryKey" json:"-"`
	UserID    uint       `gorm:"index;not null" json:"-"`
	Token     string     `gorm:"size:255;uniqueIndex;not null" json:"-"`
	ExpiresAt time.Time  `json:"-"`
	RevokedAt *time.Time `json:"-"`
	CreatedAt time.Time  `json:"-"`
}

コードを解説します。

Email        string    `gorm:"size:255;uniqueIndex;not null" json:"email"`

UserモデルのEmailにはuniqueIndexを付けて重複登録を防いでいます。

PasswordHash string    `gorm:"size:255;not null" json:"-"`

PasswordHashにはJSONタグ-を付けて、レスポンスに含まれないようにしています。パスワード関連の値は、ハッシュ化されていてもレスポンスに乗せない構成が基本です。

Token     string     `gorm:"size:255;uniqueIndex;not null" json:"-"`

RefreshTokenモデルのTokenカラムに、発行済みのトークン文字列を保存します。uniqueIndexを付けて同じ値の重複を防いでいます。

ExpiresAt time.Time  `json:"-"`

リフレッシュトークンの有効期限を保持します。/refreshのときに現在時刻と比較して期限切れを判定します。

RevokedAt *time.Time `json:"-"`

リフレッシュトークンの失効時刻を保持します。ポインタ型(*time.Time)にすることで、「まだ失効していない状態(NULL)」と「失効済み(時刻あり)」を区別できます。

2.4 main.go の初期実装

続いて、エントリポイントとなるmain.goを作成します。データベース接続・.env読み込み・テーブルの自動作成・Ginサーバの起動までを実装します。エンドポイントは以降の節で少しずつ追加します。

jwt-auth-hands-onフォルダにmain.goを作成します。

jwt-auth-hands-on/
├── .env
├── go.mod
├── go.sum
├── main.go   ← このファイルを作成
└── model.go

作成したmain.goに以下の内容を記述して保存します。DB接続とサーバ起動をまとめて実装します。

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/gin-gonic/gin"
	"github.com/joho/godotenv"
	"gorm.io/driver/mysql"
	"gorm.io/gorm"
)

var (
	db        *gorm.DB
	jwtSecret []byte
)

func main() {
	if err := godotenv.Load(); err != nil {
		fmt.Println(".envファイル読み込み失敗:", err)
		return
	}

	dsn := fmt.Sprintf(
		"%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
		os.Getenv("MYSQL_USER"),
		os.Getenv("MYSQL_PASSWORD"),
		os.Getenv("MYSQL_HOST"),
		os.Getenv("MYSQL_PORT"),
		os.Getenv("MYSQL_DATABASE"),
	)

	secret := os.Getenv("JWT_SECRET")
	if secret == "" {
		log.Fatal("JWT_SECRET が設定されていません")
	}
	jwtSecret = []byte(secret)

	var err error
	db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
	if err != nil {
		log.Fatal("DB接続失敗:", err)
	}
	if err := db.AutoMigrate(&User{}, &RefreshToken{}); err != nil {
		log.Fatal("AutoMigrate失敗:", err)
	}

	r := gin.Default()
	r.Run(":8080")
}

main.goはmodel.goと同じmainパッケージなので、model.goで定義したUser・RefreshToken型はそのままmain.goから参照できます。パッケージレベルの変数dbとjwtSecretもここで宣言し、以降で追加するヘルパー・ハンドラから共通で使えるようにしています。

コードを解説します。

if err := godotenv.Load(); err != nil {
    fmt.Println(".envファイル読み込み失敗:", err)
    return
}

godotenv.Load()で、カレントディレクトリの.envを読み込んで、それぞれのキーをプロセスの環境変数として登録します。以降のos.Getenv("MYSQL_USER")やos.Getenv("JWT_SECRET")で各値を取り出せるようになります。.envが見つからない場合は、エラーメッセージを表示してmain関数を早期returnで抜けます。DB接続情報を読めない状態で先に進んでも失敗するため、その時点で終了させる構成にしています。

dsn := fmt.Sprintf(
    "%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
    os.Getenv("MYSQL_USER"),
    os.Getenv("MYSQL_PASSWORD"),
    os.Getenv("MYSQL_HOST"),
    os.Getenv("MYSQL_PORT"),
    os.Getenv("MYSQL_DATABASE"),
)

.envから読み込んだ環境変数を組み合わせて、MySQLへの接続文字列(DSN)をfmt.Sprintfで作ります。パスワードなどの秘匿情報を直接コードに書かないため、Gitに含めるファイル(main.go)と含めないファイル(.env)を分けて管理できます。末尾のcharset=utf8mb4&parseTime=True&loc=LocalはGORMが日本語文字列と日時を扱う際の推奨設定です。

secret := os.Getenv("JWT_SECRET")
if secret == "" {
    log.Fatal("JWT_SECRET が設定されていません")
}

JWTの署名鍵を環境変数JWT_SECRETから読み込みます。ここをコードにハードコードすると、リポジトリを見られた時点でトークンの偽造が可能になるため、.envや本番環境の環境変数として外部から注入します。未設定時にlog.Fatalで即座に停止させることで、鍵が空のまま起動してしまう事故を防ぎます。

jwtSecret = []byte(secret)

読み込んだ文字列を[]byteに変換して、パッケージレベルの変数jwtSecretに代入します。JWTライブラリの署名関数は[]byteで秘密鍵を受け取るため、この形にしておくことで、以降のトークン発行・検証で毎回変換せずにそのまま渡せます。

if err := db.AutoMigrate(&User{}, &RefreshToken{}); err != nil {
    log.Fatal("AutoMigrate失敗:", err)
}

GORMのAutoMigrateで、UserとRefreshTokenのモデル定義からusersとrefresh_tokensテーブルを自動的に作成・更新します。既に存在する場合は差分だけが適用されます。マイグレーションに失敗すると以降のDB操作が全て失敗するため、log.Fatalで即座に停止させます。

2.5 起動とテーブル作成の確認

サーバを一度起動してテーブルが作成されることを確認します。以下のコマンドは、カレントディレクトリのGoパッケージ全体(main.goとmodel.go)をまとめてコンパイルして実行します。

go run .

以下のような実行結果が表示されます。

[GIN-debug] Listening and serving HTTP on :8080
⚠️ ./main.go:XX:XX: undefined: User というエラーが出る場合
go run main.goのようにファイル名を指定して実行している可能性が高いです。本章はマルチファイル構成(main.goとmodel.go、以降のセクションでhelper.go・handler.go・middleware.goが追加されます)で、main.goからmodel.goのUser・RefreshToken型を参照しているため、単一ファイル指定ではコンパイルが通りません。go run .としてカレントディレクトリのGoパッケージ全体をまとめてコンパイル・実行してください。
⚠️ Access denied for user 'root'@'localhost'と表示される場合
.envのMYSQL_PASSWORDが実際のMySQLパスワードと一致していない可能性が高いです。.envを、mysql -u root -pでログインできたパスワードに書き換えてから、再度go run .を実行してください。

AutoMigrateによって、この起動のタイミングでusersテーブルとrefresh_tokensテーブルが自動作成されています。MySQL CLIから実際にテーブルが作られていることを確認します。別のターミナルを開き、rootユーザでMySQLにログインします。

mysql -u root -p

ログイン後、auth_hands_onデータベースを使用します。

USE auth_hands_on;

続いて、テーブル一覧を表示します。

SHOW TABLES;

以下のような実行結果が表示されます。

+-------------------------+
| Tables_in_auth_hands_on |
+-------------------------+
| refresh_tokens          |
| users                   |
+-------------------------+

usersとrefresh_tokensが並んでいれば、モデルからのテーブル作成は成功しています。確認できたら、GinサーバをCtrl + Cで停止しておきます。

💡 ポイント
本章では開発用に.envファイルから環境変数を読み込んでいますが、本番環境ではDocker・ECS・Kubernetesなど、それぞれのプラットフォームが提供する環境変数の注入機能を使うのが基本です。.envは開発中の手元でだけ使い、Gitには含めない構成が一般的です。