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トークンがクライアントサイドで実行されるスクリプトに直接公開されないようにする必要があります。このエクステンションでは、CSRFトークンは、以下のようになります。

  • HTTPOnly のCookieとしてクライアントに送信され、

  • サーバサイドレンダリングフォームの隠しフォーム入力に直接埋め込まれ、クライアントに送信され使用されます。

このエクステンションは、 application/x-www-form-urlencoded と multipart/form-data フォームの CSRF トークンを作成し検証する RESTEasy Reactive サーバフィルターと、 QuteテンプレートへのCSRFトークン注入 をサポートする Qute HTML form parameter provider からなります。

プロジェクトの作成

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

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

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

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

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.16.12.Final:create \
    -DplatformVersion=2.16 \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-csrf-prevention \
    -Dextensions='csrf-reactive' \
    -DnoCode
cd security-csrf-prevention

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

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

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

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

これにより、 pom.xml に以下が追加されます:

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

次に、このテンプレートを含むファイルを 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 javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.FormParam;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.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.csrf-reactive.form-field-name=csrftoken
quarkus.csrf-reactive.cookie-name=csrftoken

CSRFトークンに署名

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

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

CSRFトークンの検証を制限

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

package io.quarkus.it.csrf;

import javax.inject.Inject;
import javax.ws.rs.BadRequestException;
import javax.ws.rs.Consumes;
import javax.ws.rs.FormParam;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.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.csrf-reactive.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
quarkus.csrf-reactive.require-form-url-encoded=false

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

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

package io.quarkus.it.csrf;

import javax.inject.Inject;
import javax.ws.rs.BadRequestException;
import javax.ws.rs.Consumes;
import javax.ws.rs.CookieParam;
import javax.ws.rs.FormParam;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Cookie;
import javax.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.csrf-reactive.verify-token=false

設定リファレンス

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

Configuration property

タイプ

デフォルト

quarkus.csrf-reactive.enabled

If filter is enabled.

Environment variable: QUARKUS_CSRF_REACTIVE_ENABLED

Show more

boolean

true

quarkus.csrf-reactive.form-field-name

Form field name which keeps a CSRF token.

Environment variable: QUARKUS_CSRF_REACTIVE_FORM_FIELD_NAME

Show more

string

csrf-token

quarkus.csrf-reactive.cookie-name

CSRF cookie name.

Environment variable: QUARKUS_CSRF_REACTIVE_COOKIE_NAME

Show more

string

csrf-token

quarkus.csrf-reactive.cookie-max-age

CSRF cookie max age.

Environment variable: QUARKUS_CSRF_REACTIVE_COOKIE_MAX_AGE

Show more

Duration

10M

quarkus.csrf-reactive.cookie-path

CSRF cookie path.

Environment variable: QUARKUS_CSRF_REACTIVE_COOKIE_PATH

Show more

string

/

quarkus.csrf-reactive.cookie-domain

CSRF cookie domain.

Environment variable: QUARKUS_CSRF_REACTIVE_COOKIE_DOMAIN

Show more

string

quarkus.csrf-reactive.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_CSRF_REACTIVE_COOKIE_FORCE_SECURE

Show more

boolean

false

quarkus.csrf-reactive.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_CSRF_REACTIVE_CREATE_TOKEN_PATH

Show more

文字列のリスト

quarkus.csrf-reactive.token-size

Random CSRF token size in bytes.

Environment variable: QUARKUS_CSRF_REACTIVE_TOKEN_SIZE

Show more

int

16

quarkus.csrf-reactive.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_CSRF_REACTIVE_TOKEN_SIGNATURE_KEY

Show more

string

quarkus.csrf-reactive.verify-token

Verify CSRF token in the CSRF filter. If this property is enabled then the input stream will be read and cached by the CSRF filter to verify the token. If you prefer then you can disable this property and compare CSRF form and cookie parameters in the application code using JAX-RS javax.ws.rs.FormParam which refers to the form-field-name form property and javax.ws.rs.CookieParam which refers to the CsrfReactiveConfig#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_CSRF_REACTIVE_VERIFY_TOKEN

Show more

boolean

true

quarkus.csrf-reactive.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.

Environment variable: QUARKUS_CSRF_REACTIVE_REQUIRE_FORM_URL_ENCODED

Show more

boolean

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

期間のフォーマットは標準の java.time.Duration フォーマットを使用します。詳細は Duration#parse() javadoc を参照してください。

数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 PT が暗黙的に値の前に付加され、標準の java.time.Duration 形式が得られます。

参照

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

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

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.