ORY Hydra を用いた OAuth2 / OpenID Connect 認可サーバーのしくみと実践

現代のWebアプリケーションやマイクロサービスアーキテクチャでは、「誰が」「何に」アクセスできるかを安全かつ柔軟に制御する仕組みが不可欠です。OAuth2 / OpenID Connect（OIDC）はそのデファクトスタンダードですが、これらのプロトコルを正しく実装するのは想像以上に複雑です。

OAuth2の世界における「認可サーバー（Authorization Server）」は、RFC 6749 で定義される役割であり、以下を担います。

– クライアントアプリケーションの認証・認可

– アクセストークン / リフレッシュトークンの発行と管理

– スコープの検証とトークンのイントロスペクション

– （OIDCの場合）IDトークンの発行とユーザー情報エンドポイントの提供

多くのエンジニアは「認可（Authorization）」と「認証（Authentication）」を混同しがちですが、厳密には異なります。

認証（Authentication）: あなたは誰ですか？    → Identity Provider が担う
認可（Authorization）: あなたは何ができますか？ → Authorization Server が担う

OIDCはOAuth2の上に認証レイヤーを追加したプロトコルであり、認可サーバーが認証サーバーも兼ねる形になります。ORY Hydra はこの認可サーバーの役割に特化したOSSです。

—

以下の Docker Compose で完全なローカル環境を構築できます。

# docker-compose.yml
version: "3.7"
services:
# ── 認可サーバー ──
hydra:
image: oryd/hydra:v2.1.1
ports:
- "4444:4444" # Public API
- "4445:4445" # Admin API
command: serve -c /etc/config/hydra/hydra.yml all --dev
volumes:
- ./hydra:/etc/config/hydra
environment:
- DSN=mysql://hydra:secret@tcp(db:3306)/hydra?parseTime=true
depends_on:
- hydra-migrate
networks:
- common_link


# ── DBマイグレーション ──
hydra-migrate:
image: oryd/hydra:v2.1.1
environment:
- DSN=mysql://hydra:secret@tcp(db:3306)/hydra?parseTime=true
command: migrate -c /etc/config/hydra/hydra.yml sql -e --yes
volumes:
- ./hydra:/etc/config/hydra
networks:
- common_link


# ── MySQL ──
db:
image: mysql:8.0.29
command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
- MYSQL_ROOT_PASSWORD=secret
- MYSQL_DATABASE=hydra
- MYSQL_USER=hydra
- MYSQL_PASSWORD=secret
ports:
- "3310:3306"
networks:
- common_link


networks:
common_link:
external: true

起動手順:

# 1. Docker ネットワーク作成（初回のみ）
docker network create common_link


# 2. コンテナ起動
docker-compose up -d


# 3. 起動確認
curl http://localhost:4444/.well-known/openid-configuration | jq .

# Hydra CLI でクライアントを登録
docker-compose exec hydra \
hydra create client \
--endpointhttp://127.0.0.1:4445\
--id YamatoCsvExport \
--secretsample-app-secret\
--grant-types authorization_code,refresh_token,client_credentials \
--response-typestoken,code,id_token\
--scope openid,offline,product_read,product_write,order_read,order_write \
--callbackshttp://127.0.0.1:5000/callback

登録したクライアントの確認:

docker-compose exec hydra \
hydra list clients --endpoint http://127.0.0.1:4445


# 特定クライアントの詳細
docker-compose exec hydra \
hydra get client YamatoCsvExport --endpoint http://127.0.0.1:4445

#### Step 1: 認可リクエストの構築

サンプルアプリ（Client）が構築する認可 URL:

// PKCE の code_verifier / code_challenge を生成
verifierBytes := make([]byte, 96)
rand.Read(verifierBytes)
codeVerifier := base64.RawURLEncoding.EncodeToString(verifierBytes)
h := sha256.Sum256([]byte(codeVerifier))
codeChallenge := base64.RawURLEncoding.EncodeToString(h[:])

query := url.Values{
    "client_id":             {"YamatoCsvExport"},
    "response_type":         {"code"},
    "scope":                 {"openid offline order_read order_write product_read product_write"},
    "max_age":               {"0"},
    "redirect_uri":          {"http://127.0.0.1:5000/callback"},
    "state":                 {uuid.New().String()},  // CSRF 防止
    "nonce":                 {uuid.New().String()},  // リプレイ攻撃防止
    "code_challenge":        {codeChallenge},        // PKCE
    "code_challenge_method": {"S256"},
}
authURL := "http://127.0.0.1:4444/oauth2/auth?" + query.Encode()

 

ブラウザからアクセスすると:

http://127.0.0.1:4444/oauth2/auth
?client_id=YamatoCsvExport
&response_type=code
&scope=openid%20offline%20order_read%20product_read
&redirect_uri=http://127.0.0.1:5000/callback
&state=550e8400-e29b-41d4-a716-446655440000
&nonce=6ba7b810-9dad-11d1-80b4-00c04fd430c8
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256

#### Step 2: ログイン → 同意 → コールバック

Hydra は Login App にリダイレクト → Login App で認証 → Consent App でスコープ許可 → Client にコールバック。

##### Login App: ログイン受付

Hydra から `login_challenge` 付きでリダイレクトされる。ショップ認証後、Hydra Admin API で accept する。

func loginHandler(w http.ResponseWriter, r *http.Request) {
ifr.Method == http.MethodGet {
challenge := r.URL.Query().Get("login_challenge")
renderLoginForm(w, challenge)
return
}


// POST: 認証処理
r.ParseForm()
email := r.FormValue("email")
password := r.FormValue("password")
challenge := r.FormValue("challenge")


// ショップ認証（実装は各環境に依存）
shopID, userID := authenticateShop(email, password)


// Hydra Admin API: accept login
// subject に "ShopId UserId" をスペース区切りで設定
body, _ := json.Marshal(map[string]interface{}{
"subject": fmt.Sprintf("%s%s", shopID, userID),
"remember": true,
"remember_for": 3600,
})
url := fmt.Sprintf("%s/oauth2/auth/requests/login/accept?login_challenge=%s",
hydraAdminURL, challenge)
req, _ := http.NewRequest(http.MethodPut, url, bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")


resp, _ := http.DefaultClient.Do(req)
deferresp.Body.Close()


varresultmap[string]string
json.NewDecoder(resp.Body).Decode(&result)
http.Redirect(w, r, result["redirect_to"], http.StatusFound)
}

ポイント: `subject` に `”ShopId UserId”` をスペース区切りで設定する。これが後続の Introspection で `sub` フィールドとして返却される。

##### Consent App: スコープ許可

Hydra から `consent_challenge` 付きでリダイレクトされる。スコープ確認後、`session.access_token` にテナント情報を埋め込む。

func consentHandler(w http.ResponseWriter, r *http.Request) {
ifr.Method == http.MethodGet {
challenge := r.URL.Query().Get("consent_challenge")
// Hydra Admin API: スコープ情報取得
url := fmt.Sprintf("%s/oauth2/auth/requests/consent?consent_challenge=%s",
hydraAdminURL, challenge)
resp, _ := http.Get(url)
deferresp.Body.Close()


varconsentInfomap[string]interface{}
json.NewDecoder(resp.Body).Decode(&consentInfo)
// requested_scope をユーザーに表示
renderConsentForm(w, challenge, consentInfo["requested_scope"])
return
}


// POST: スコープ許可
r.ParseForm()
challenge := r.FormValue("challenge")
grantScope := r.Form["grant_scope"]


// subject からテナント情報を取得（login で設定した値）
url := fmt.Sprintf("%s/oauth2/auth/requests/consent?consent_challenge=%s",
hydraAdminURL, challenge)
resp, _ := http.Get(url)
deferresp.Body.Close()


varconsentInfomap[string]interface{}
json.NewDecoder(resp.Body).Decode(&consentInfo)


subject := consentInfo["subject"].(string)
parts := strings.SplitN(subject, " ", 2)
shopID := parts[0]
userID := parts[0]
iflen(parts) > 1 {
userID = parts[1]
}
clientID := consentInfo["client"].(map[string]interface{})["client_id"].(string)


// Hydra Admin API: accept consent
// session.access_token に設定した値が Introspection の ext フィールドに返却される
body, _ := json.Marshal(map[string]interface{}{
"grant_scope": grantScope,
"session": map[string]interface{}{
"access_token": map[string]interface{}{
"shop_id": shopID,
"user_id": userID,
"app_id": getAppID(clientID),
"client_id": clientID,
"is_member": false,
},
},
})
acceptURL := fmt.Sprintf("%s/oauth2/auth/requests/consent/accept?consent_challenge=%s",
hydraAdminURL, challenge)
req, _ := http.NewRequest(http.MethodPut, acceptURL, bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")


acceptResp, _ := http.DefaultClient.Do(req)
deferacceptResp.Body.Close()


varresultmap[string]string
json.NewDecoder(acceptResp.Body).Decode(&result)
http.Redirect(w, r, result["redirect_to"], http.StatusFound)
}

ポイント: `session.access_token` に設定した `shop_id`, `user_id`, `app_id` 等は、Hydra の Token Introspection レスポンスで `ext` フィールドとして返却される。これが `api_facade` で参照される `accessTokenInfo.Ext.ShopId` の値になる。

##### 2-3. Client App: コールバック

認可コードと `state` を受け取り、`state` 検証後にトークン取得へ進む。

func callbackHandler(w http.ResponseWriter, r *http.Request) {
// state 検証（CSRF 対策）
savedState := getSessionValue(r, "state")
ifsavedState != r.URL.Query().Get("state") {
http.Error(w, "state が不正です", http.StatusBadRequest)
return
}


// エラーチェック
iferrParam := r.URL.Query().Get("error"); errParam != "" {
http.Error(w, "認証エラー: "+r.URL.Query().Get("error_description"), http.StatusBadRequest)
return
}


// 認可コードを取得 → Step 3 でトークンに交換
code := r.URL.Query().Get("code")
_ = code// → トークン取得処理へ（Step 3 参照）
}

#### Step 3: トークン取得

# コールバックで受け取った認可コードをトークンに交換
data = {
"client_id": "YamatoCsvExport",
"grant_type": "authorization_code",
"code": request.args.get("code"),
"redirect_uri": "http://127.0.0.1:5000/callback",
"code_verifier": session["code_verifier"], # PKCE 検証
}
response = requests.post(
"http://hydra:4444/oauth2/token",
data=data,
auth=HTTPBasicAuth("YamatoCsvExport", "sample-app-secret")
)
token = response.json()

レスポンス例

{
"access_token": "ory_at_...",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "ory_rt_...",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"scope": "openid offline order_read product_read"
}

#### Step 4: ID Token の検証

// JWKS から公開鍵を取得
jwksResp, _ := http.Get("http://hydra:4444/.well-known/jwks.json")
defer jwksResp.Body.Close()

var jwks struct {
    Keys []map[string]interface{} `json:"keys"`
}
json.NewDecoder(jwksResp.Body).Decode(&jwks)

// ID Token をデコード・検証
idToken := token["id_token"].(string)
parts := strings.Split(idToken, ".")
payloadBytes, _ := base64.RawURLEncoding.DecodeString(parts[1])
var payload map[string]interface{}
json.Unmarshal(payloadBytes, &payload)

// nonce を検証（リプレイ攻撃防止）
if session.Nonce != payload["nonce"].(string) {
    http.Error(w, "nonce が不正です", http.StatusBadRequest)
    return
}

#### Step 5: リフレッシュトークンによる更新

// リフレッシュトークンによるトークン更新
formData := url.Values{
    "client_id":     {"YamatoCsvExport"},
    "grant_type":    {"refresh_token"},
    "refresh_token": {token["refresh_token"].(string)},
}
req, _ := http.NewRequest(http.MethodPost, "http://hydra:4444/oauth2/token",
    strings.NewReader(formData.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
req.SetBasicAuth("YamatoCsvExport", "sample-app-secret")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var newToken map[string]interface{}
json.NewDecoder(resp.Body).Decode(&newToken)

#### Step 6: Token Introspection

リクエストを受け取った際、Admin API でトークンを検証します。

formData := url.Values{"token": {accessToken}}
resp, _ := http.PostForm("http://hydra:4445/oauth2/introspect", formData)
defer resp.Body.Close()

var introspection HydraAccessToken
json.NewDecoder(resp.Body).Decode(&introspection)
// {
//   "active": true,
//   "scope": "order_read product_read",
//   "client_id": "YamatoCsvExport",
//   "sub": "xxx",
//   "exp": 1700000000,
//   "ext": { "shop_id": "xxx", "app_id": 1 }
// }