認証機能の実装準備
ここからハンズオンに入ります。プロジェクトフォルダの初期化、依存パッケージの導入、データベースとモデルの用意までを行います。
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には含めない構成が一般的です。 |