JWTでユーザー認証する

[syuilo]

Summary

JWTでユーザー認証する

Purpose

• 実装がシンプルになり、場合によってはバックエンドでユーザー情報を別途取得しないでも良くなることからパフォーマンス向上しそう
  • localUserByNativeTokenCache が要らなくなることからメモリ使用量が減る
• Signout should invalidate session server-side | サインアウト後にtoken自身も無効にして欲しい #15567 などに対応できそう

Do you want to implement this feature yourself?

• Yes, I will implement this by myself and send a pull request

[kakkokari-gtyih]

場合によってはユーザー情報を別途取得しないでも良くなる

多分全情報をJWTに乗せるのは悪手

[syuilo]

全情報は載せない

[syuilo]

ホームタイムライン取得するAPIを考えると、必要なのはユーザーIDくらいで、ユーザー名とかは明らかに不要

[kakkokari-gtyih]

あーサーバー側でってことか

[kakkokari-gtyih]

#15567 などに対応できそう

マスターのログイントークンをJWTに入れて iat を付与したものを通常のログイントークンとする → ログイン処理ごとにどこかにJWTを格納する → ログアウト時にJWTを削除する
ペイロードにユーザーIDなどの変更不可能なものを含めるかたちでJWTを発行する場合にJWTを取り消す手段がないということでJWTは悪手と言われるが、ログイントークンをJWTのペイロードに入れるようにすることで、今まで通りログイントークンの再生成を行えば今までのログイントークンを含んだJWTも無効にすることができるはず

[syuilo]

#15567 などに対応できそう

マスターのログイントークンをJWTに入れて iat を付与したものを通常のログイントークンとする → ログイン処理ごとにどこかにJWTを格納する → ログアウト時にJWTを削除する ペイロードにユーザーIDなどの変更不可能なものを含めるかたちでJWTを発行する場合にJWTを取り消す手段がないということでJWTは悪手と言われるが、ログイントークンをJWTのペイロードに入れるようにすることで、今まで通りログイントークンの再生成を行えば今までのログイントークンを含んだJWTも無効にすることができるはず

これだとパフォーマンス向上のメリットは消えそう？

[syuilo]

JWTの有効期限を数分といった短い期間にする & ステートレス
にすれば今より安全性もパフォーマンスもどっちも向上できそうに思った

[syuilo]

現実的には定期的にリフレッシュが必要ということを考えるとリフレッシュトークン<->ユーザーのキャッシュは持っておく必要があり、結局はパフォーマンス向上にはつながらなさそう

[syuilo]

いやリフレッシュの頻度によっては別にキャッシュ無くても良いか

[syuilo]

あと署名の生成・検証でどれくらいCPUを消費するのかは気になる

[KisaragiEffective]

HMAC-SHA512 (HS512) であれば比較的重くなさそう
確実に言えるのはAPの署名よりは軽いこと

[eternal-flame-AD]

I can take on this issue next week if no one is already working on an implementation, I wanted this for my own instance too.

[kakkokari-gtyih]

I can take on this issue next week if no one is already working on an implementation, I wanted this for my own instance too.

Schedule is not fixed yet, but we might do the overhaul of the login auth by @acid-chicken (#13865) so maybe we should coordinate who and when to actually implement

[eternal-flame-AD]

I think transition to JWT (or any alternative format than random string we agree on) should be done first, because many features in #13865 are contingent upon a rich token format (tokens with structured info that backend can parse).

パスワード認証を要求するすべてのエンドポイントを sudo トークンに置き換える -> this is essentially granular token policy

sudo モード -> this needs ways to identify tokens too (like a token_sudo_until table), and we have to agree on a format first before all

SSO -> many SSO services require you to store refresh tokens, so we need a rich format too

[eternal-flame-AD]

I propose we do this, we don't have to have me or anyone dictate how it works, we can do a few stages

• spec out how the token is formatted, authenticated, and optionally encrypt secret state
• discuss with @acid-chicken about their opinion on frontend adoption

On second around we implement in this order again.

[eternal-flame-AD]

Some early thoughts, everything is illustration only and only suggestive

Inspirations and References

• JWT: https://datatracker.ietf.org/doc/html/rfc7519
• TTL and renewal flexibility: https://developer.hashicorp.com/vault/docs/concepts/tokens#token-time-to-live-periodic-tokens-and-explicit-max-ttls
• HKDF, a cheap KDF for deriving from already strong entropy sources: https://en.wikipedia.org/wiki/HKDF

Static Configuration

• max-ttl: The absolute maximum TTL for a non-root user token (3 months or so is reasonable), used for preventing users from creating indefinitely long tokens for garbage collection and security issues
• IKM (Input Key Material): Ways to generate key material for secrets.

Illustration:

jwt:
  max-ttl: 90d

runtimeSecret:
  ikm:
    - source: env # a BASE64 encoded environment variable, cleared after reading into memory
      name: MISSKEY_RUNTIME_SECRET
    - source: file # a file path
      path: /run/secrets/misskey_runtime_secret
      clear: true
    - source: http # a URL to fetch the secret from (we don't need to implement this, just illustrating the flexibility)
      url: https://vault.example/v1/secret/data/misskey-runtime-secret

At runtime, all the IKM sources are individually passed through bcrypt to generate a key, and then HKDF-SHA512 is used to derive the runtime secret this architecture keeps our options open for:

• needing more runtime secrets in the future, for example actor key encryption
• using different IKM sources for different secrets without the need to recompute bcrypt
• possibly avoid holding keys resident in memory

function deriveRuntimeSecret(key: string, externalIkms: string[]) {
    return hkdf(
        "sha512",
        [metaRepository.getBase64("runtimeSecret"), ...externalIkms.map(fromBase64)].map(ikm => bcrypt(ikm)).join(),
        metaRepository.getBase64("runtimeSecretSalt"),
        `Product: Misskey\r\nHost: ${metaRepository.get("host")}\r\nX-Secret-Type: ${key}\r\n`,
    );
}

const jwtSecret = deriveRuntimeSecret("api.auth.jwt", externalIkms);

Format

Header

• alg: HS256/HS512, there is no need for public-key here as there is no federated authentication, this is usually fast enough, if performance is a concern, HS256 is better (smaller payload and better architecture optimizations)
• typ: JWT

Payload Claims

• sub: User ID (AIDX, etc)
• exp: Expiration time (Optional)
• aud: https://misskey.example/api/ | https://misskey.example/queue/ (Defense against issues like GHSA-38w6-vx8g-67pp)
• iss: Hostname
• iat: Issued at
• jti: User ID concatenated with a 32-bit counter
• mkPolicy: Policy that is currently effective but can be elevated by a password prompt.
• mkSudoPolicy: Policy that is applied after a password prompt. (Something like POST /api/admin/elevate, and the token is elevated for the next 15 minutes)
• mkBoundingExp: Bounding expiration time (Optional)
• mkRenewalTolerance: Renewal tolerance, generally the better option is to renew at half of the TTL and continue trying, not wait until token is unusable (Optional)

A renewal is allowed if:

• claims.exp ? claims.exp < currentTime - (claims.mkRenewalTolerance ?? 0) : true, and
• claims.iat + max-ttl < currentTime, and
• claims.mkBoundingExp ? claims.mkBoundingExp < currentTime : true

Policy

We will continue using the existing permission system, with some extensions:

• meta:legacy: Apply legacy policy (basically allow all). We can gradually phase this out by:
  • In 2025.4.0, we can make this lose admin privileges.
  • In 2025.8.0, we can make this token invalid.
• meta:web: Apply policy for the web client.
• meta:webAdmin: Apply policy for the web control panel.
• write:admin:bullBoard: Can exchange token for a short-lived bull board access cookie.
• deny:<permission>: Deny the specified permission, cannot be overridden by other policies.

Elevation

Elevation is done by a POST request to /api/admin/elevate with a payload similar:

POST /api/admin/elevate
Content-Type: application/json

{
  "id": "...",
  "ttl": 900
}

The token will then have its mkSudoPolicy applied for the next 15 minutes.

[eternal-flame-AD]

We can also do double encryption (store a DEK in the database) if rekeying is necessary, depending on the complexity desired.

https://learn.microsoft.com/en-us/azure/security/fundamentals/double-encryption