The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

クロスサイトリクエストフォージェリー対策

クロスサイトリクエストフォージェリ（CSRF） とは、エンドユーザーが現在認証されているウェブアプリケーション上で意図しないアクションを実行させる攻撃です。

Quarkus Security は、 Double Submit Cookie と CSRFリクエスト・ヘッダー テクニックを実装したCSRF防止機能を提供しています。

Double Submit Cookie テクニックを使うには、CSRF トークンを (オプションで署名された) HTTPOnly クッキーとしてクライアントに送り、サーバサイドでレンダリングされた HTML フォームの隠されたフォーム入力に直接埋め込むか、リクエストヘッダ値として送信する必要があります。

このエクステンションは、 Quarkus REST（旧RESTEasy Reactive） サーバーフィルターで構成され、 application/x-www-form-urlencoded および multipart/form-data フォームで CSRF トークンの作成と検証を行います。また、Qute HTML フォームパラメータープロバイダーで、 Qute テンプレートへの CSRF トークンの注入 をサポートします。

プロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

コマンドラインインタフェース
quarkus create app org.acme:security-csrf-prevention \
    --extension='rest-csrf' \
    --no-code
cd security-csrf-prevention

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.21.2:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-csrf-prevention \
    -Dextensions='rest-csrf' \
    -DnoCode
cd security-csrf-prevention

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

  • cmdを使用する場合、（バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください）。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=security-csrf-prevention"

このコマンドは、 rest-csrf エクステンションをインポートするプロジェクトを生成します。

Quarkusプロジェクトがすでに設定されている場合は、プロジェクトのベースディレクトリで次のコマンドを実行することで、 rest-csrf エクステンションをプロジェクトに追加できます：

コマンドラインインタフェース
quarkus extension add rest-csrf
Maven
./mvnw quarkus:add-extension -Dextensions='rest-csrf'
Gradle
./gradlew addExtension --extensions='rest-csrf'

これにより、ビルドファイルに以下が追加されます:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-csrf</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-rest-csrf")

次に、このテンプレートを含むファイルを csrfToken.html と名付け、 src/main/resources/templates フォルダに置いてください:

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>User Name Input</title>
</head>
<body>
    <h1>User Name Input</h1>

    <form action="/service/csrfTokenForm" method="post">
    	<input type="hidden" name="{inject:csrf.parameterName}" value="{inject:csrf.token}" />  (1)

    	<p>Your Name: <input type="text" name="name" /></p>
    	<p><input type="submit" name="submit"/></p>
    </form>
</body>
</html>
1 この書式は、CSRF トークンを隠しフォームフィールドに注入するために使用されます。このトークンは CSRF フィルタによって CSRF クッキーと照合され検証されます。

では、HTMLフォームを返し、フォームのPOSTリクエストを処理するリソースクラスを作成しましょう:

package io.quarkus.it.csrf;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.FormParam;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

import io.quarkus.qute.Template;
import io.quarkus.qute.TemplateInstance;

@Path("/service")
public class UserNameResource {

    @Inject
    Template csrfToken; (1)

    @GET
    @Path("/csrfTokenForm")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance getCsrfTokenForm() {
        return csrfToken.instance(); (2)
    }

    @POST
    @Path("/csrfTokenForm")
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    @Produces(MediaType.TEXT_PLAIN)
    public String postCsrfTokenForm(@FormParam("name") String userName) {
        return userName; (3)
    }
}
1 csrfToken.html を Template として注入してください。
2 CSRFフィルターによって作成されたCSRFトークンを含むhiddenフォームフィールドを持つHTMLフォームを返します。
3 フォームの POST リクエストを処理します。このメソッドは、CSRF フィルターがトークンの確認に成功した場合にのみ呼び出すことができます。

フィルタが、隠された CSRF フォームフィールドがない、CSRF クッキーがない、あるいは CSRF フォームフィールドと CSRF クッキーの値が一致しないことを発見した場合、フォーム POST リクエストは HTTP ステータス 400 で失敗します。

この段階では、追加の設定は必要ありません。デフォルトでは、CSRFフォームフィールドとクッキー名は csrf-token に設定され、フィルタはトークンを検証します。しかし、必要であれば、これらの名前を変更することができます：

quarkus.rest-csrf.form-field-name=csrftoken
quarkus.rest-csrf.cookie-name=csrftoken

CSRFトークンに署名

生成された CSRF トークンに HMAC 署名を作成し、これらの HMAC 値を CSRF トークン・クッキーとして保存することで、攻撃者が CSRF クッキー・トークンを再作成するリスクを回避することができます。必要なのは、少なくとも 32 文字の長さのトークン署名シークレットを設定することだけです。

quarkus.rest-csrf.token-signature-key=AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow

CSRFリクエスト・ヘッダー

HTML form タグを使用せず、CSRFトークンをヘッダーとして渡す必要がある場合、例えばHTMXにヘッダー名とトークンを注入します：

<body hx-headers='{"{inject:csrf.headerName}":"{inject:csrf.token}"}'> (1)
</body>
1 この式は CSRF トークン・ヘッダーとトークンを注入するために使われます。このトークンは CSRF フィルターによって CSRF クッキーと照合されます。

デフォルトのヘッダー名は X-CSRF-TOKEN です。 quarkus.rest-csrf.token-header-name などでカスタマイズできます：

quarkus.rest-csrf.token-header-name=CUSTOM-X-CSRF-TOKEN

CSRF クッキーの値をヘッダとして渡すために、JavaScript から CSRF クッキーにアクセスする必要がある場合、 {inject:csrf.cookieName} と {inject:csrf.headerName} を使って、CSRF ヘッダ値として読まれなければならないクッキー名を注入し、このクッキーへのアクセスを許可してください：

quarkus.rest-csrf.cookie-http-only=false

クロスオリジンリソース共有

クロスオリジン環境でCSRF防止を実施したい場合は、すべてのオリジンをサポートするのは避けてください。

サポートされるOriginを信頼できるOriginのみに制限してください。詳細については、「Cross-originリソース共有」ガイドの CORSフィルター のセクションを参照してください。

CSRFトークンの検証を制限

Jakarta REST エンドポイントは、 application/x-www-form-urlencoded または multipart/form-data のペイロードを持つ HTTP POST リクエストだけでなく、他のメディアタイプを持つペイロードも、同じ URL パスまたは異なる URL パスで受け入れることがあります。したがって、そのような場合は CSRF トークンの検証を回避したいでしょう。例:

package io.quarkus.it.csrf;

import jakarta.inject.Inject;
import jakarta.ws.rs.BadRequestException;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.FormParam;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

import io.quarkus.qute.Template;
import io.quarkus.qute.TemplateInstance;

@Path("/service")
public class UserNameResource {

    @Inject
    Template csrfToken;

    @GET
    @Path("/user")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance getCsrfTokenForm() {
        return csrfToken.instance();
    }

    (1)
    @POST
    @Path("/user")
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    @Produces(MediaType.TEXT_PLAIN)
    public String postCsrfTokenForm(@FormParam("name") String userName) {
        return userName;
    }

    (2)
    @POST
    @Path("/user")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.TEXT_PLAIN)
    public String postJson(User user) {
        return user.name;
    }

    (3)
    @POST
    @Path("/users")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.TEXT_PLAIN)
    public String postJson(User user) {
        return user.name;
    }

    public static class User {
        private String name;
        public String getName() {
            return this.name;
        }
        public void setName(String name) {
            this.name = name;
        }
    }
}
1 /user へのPOSTフォームのリクエスト、CSRFフィルターによりCSRFトークンの検証が行われます。
2 /user への POST json リクエスト , CSRF トークン検証は不要です。
3 /users への POST json リクエスト , CSRF トークン検証は不要です。

ご覧のように、 service/user パスで application/x-www-form-urlencoded ペイロードを受け取る際に CSRF トークン検証が必要になりますが、 service/user と service/users の両方のメソッドにPOSTされた User JSON表現はCSRFトークンを持たないため、これらのケースではトークン検証をスキップする必要があります。この場合、特定の service/user リクエストパスに限定し、このパスでは application/x-www-form-urlencoded だけを許可しないようにします:

# Verify CSRF token only for the `/service/user` path, ignore other paths such as `/service/users`
quarkus.rest-csrf.create-token-path=/service/user

# If `/service/user` path accepts not only `application/x-www-form-urlencoded` payloads but also other ones such as JSON then allow them
# Setting this property is not necessary when the token is submitted as a header value
quarkus.rest-csrf.require-form-url-encoded=false

アプリケーションコード内のCSRFトークンの検証

もし、CSRFのフォームフィールドとクッキーの値をアプリケーションのコードで比較したい場合は、次のようにします。

package io.quarkus.it.csrf;

import jakarta.inject.Inject;
import jakarta.ws.rs.BadRequestException;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.CookieParam;
import jakarta.ws.rs.FormParam;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Cookie;
import jakarta.ws.rs.core.MediaType;

import io.quarkus.qute.Template;
import io.quarkus.qute.TemplateInstance;

@Path("/service")
public class UserNameResource {

    @Inject
    Template csrfToken;

    @GET
    @Path("/csrfTokenForm")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance getCsrfTokenForm() {
        return csrfToken.instance();
    }

    @POST
    @Path("/csrfTokenForm")
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    @Produces(MediaType.TEXT_PLAIN)
    public String postCsrfTokenForm(@CookieParam("csrf-token") Cookie csrfCookie, @FormParam("csrf-token") String formCsrfToken, @FormParam("name") String userName) {
        if (!csrfCookie.getValue().equals(formCsrfToken)) { (1)
            throw new BadRequestException();
        }
        return userName;
    }
}
1 CSRFのフォームフィールドとクッキーの値を比較し、一致しない場合はHTTPステータス 400 で失敗します。

また、フィルターのトークン検証を無効にします:

quarkus.rest-csrf.verify-token=false

設定リファレンス

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能

Configuration property

タイプ

デフォルト

quarkus.rest-csrf.enabled

If filter is enabled.

Environment variable: QUARKUS_REST_CSRF_ENABLED

Show more

ブーリアン

true

quarkus.rest-csrf.form-field-name

Form field name which keeps a CSRF token.

Environment variable: QUARKUS_REST_CSRF_FORM_FIELD_NAME

Show more

string

csrf-token

quarkus.rest-csrf.token-header-name

Token header which can provide a CSRF token.

Environment variable: QUARKUS_REST_CSRF_TOKEN_HEADER_NAME

Show more

string

X-CSRF-TOKEN

quarkus.rest-csrf.cookie-name

CSRF cookie name.

Environment variable: QUARKUS_REST_CSRF_COOKIE_NAME

Show more

string

csrf-token

quarkus.rest-csrf.cookie-max-age

CSRF cookie max age.

Environment variable: QUARKUS_REST_CSRF_COOKIE_MAX_AGE

Show more

Duration 

2H

quarkus.rest-csrf.cookie-path

CSRF cookie path.

Environment variable: QUARKUS_REST_CSRF_COOKIE_PATH

Show more

string

/

quarkus.rest-csrf.cookie-domain

CSRF cookie domain.

Environment variable: QUARKUS_REST_CSRF_COOKIE_DOMAIN

Show more

string

quarkus.rest-csrf.cookie-force-secure

If enabled the CSRF cookie will have its 'secure' parameter set to 'true' when HTTP is used. It may be necessary when running behind an SSL terminating reverse proxy. The cookie will always be secure if HTTPS is used even if this property is set to false.

Environment variable: QUARKUS_REST_CSRF_COOKIE_FORCE_SECURE

Show more

ブーリアン

false

quarkus.rest-csrf.cookie-http-only

Set the HttpOnly attribute to prevent access to the cookie via JavaScript.

Environment variable: QUARKUS_REST_CSRF_COOKIE_HTTP_ONLY

Show more

ブーリアン

true

quarkus.rest-csrf.create-token-path

Create CSRF token only if the HTTP GET relative request path matches one of the paths configured with this property. Use a comma to separate multiple path values.

Environment variable: QUARKUS_REST_CSRF_CREATE_TOKEN_PATH

Show more

list of string

quarkus.rest-csrf.token-size

Random CSRF token size in bytes.

Environment variable: QUARKUS_REST_CSRF_TOKEN_SIZE

Show more

int

16

quarkus.rest-csrf.token-signature-key

CSRF token HMAC signature key, if this key is set then it must be at least 32 characters long.

Environment variable: QUARKUS_REST_CSRF_TOKEN_SIGNATURE_KEY

Show more

string

quarkus.rest-csrf.verify-token

Verify CSRF token in the CSRF filter. If you prefer then you can disable this property and compare CSRF form and cookie parameters in the application code using JAX-RS jakarta.ws.rs.FormParam which refers to the form-field-name form property and jakarta.ws.rs.CookieParam which refers to the RestCsrfConfig#cookieName cookie. Note that even if the CSRF token verification in the CSRF filter is disabled, the filter will still perform checks to ensure the token is available, has the correct token-size in bytes and that the Content-Type HTTP header is either 'application/x-www-form-urlencoded' or 'multipart/form-data'.

Environment variable: QUARKUS_REST_CSRF_VERIFY_TOKEN

Show more

ブーリアン

true

quarkus.rest-csrf.require-form-url-encoded

Require that only 'application/x-www-form-urlencoded' or 'multipart/form-data' body is accepted for the token verification to proceed. Disable this property for the CSRF filter to avoid verifying the token for POST requests with other content types. This property is only effective if verify-token property is enabled and token-header-name is not configured.

Environment variable: QUARKUS_REST_CSRF_REQUIRE_FORM_URL_ENCODED

Show more

ブーリアン

true
期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

  • 数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

参照

関連コンテンツ

同じトピックについて

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by