2.2. ビルトイン認証メカニズム
Quarkus Security は、次のビルトイン認証サポートを提供します。
2.2.1. Basic 認証
ビルトイン HTTP Basic 認証メカニズムを使用して、Quarkus アプリケーションのエンドポイントを保護できます。詳細は、以下のドキュメントを参照してください。
2.2.2. フォームベース認証
Quarkus は、従来の Servlet フォームベース認証と同様に機能するフォームベース認証を提供します。従来のフォーム認証とは異なり、Quarkus はクラスター化された HTTP セッションをサポートしていないため、認証されたユーザーは HTTP セッションに保存されません。代わりに、認証情報が暗号化された Cookie に保存されます。同じ暗号鍵を共有するすべてのクラスターメンバーは、これを読み取ることができます。
暗号化を適用するには、quarkus.http.auth.session.encryption-key プロパティーを追加し、設定する値が 16 文字以上であることを確認します。暗号鍵は、SHA-256 を使用してハッシュされます。結果のダイジェストは、Cookie 値の AES-256 暗号化の鍵として使用されます。Cookie には暗号化された値の一部として有効期限が含まれているため、クラスター内のすべてのノードのクロックを同期する必要があります。セッションが使用中の場合、更新された有効期限を持つ新しい Cookie が 1 分ごとに生成されます。
シングルページアプリケーション (SPA) では、通常、次の例に示すように、デフォルトのページパスを削除してリダイレクトを回避する必要があります。
# do not redirect, respond with HTTP 200 OK quarkus.http.auth.form.landing-page= # do not redirect, respond with HTTP 401 Unauthorized quarkus.http.auth.form.login-page= quarkus.http.auth.form.error-page= # HttpOnly must be false if you want to log out on the client; it can be true if logging out from the server quarkus.http.auth.form.http-only-cookie=false
SPA のリダイレクトを無効にしたため、クライアントからプログラムによってログインおよびログアウトする必要があります。以下は、j_security_check エンドポイントにログインし、Cookie を破棄することでアプリケーションからログアウトする JavaScript メソッドの例です。
const login = () => {
// Create an object to represent the form data
const formData = new URLSearchParams();
formData.append("j_username", username);
formData.append("j_password", password);
// Make an HTTP POST request using fetch against j_security_check endpoint
fetch("j_security_check", {
method: "POST",
body: formData,
headers: {
"Content-Type": "application/x-www-form-urlencoded",
},
})
.then((response) => {
if (response.status === 200) {
// Authentication was successful
console.log("Authentication successful");
} else {
// Authentication failed
console.error("Invalid credentials");
}
})
.catch((error) => {
console.error(error);
});
};
クライアントから SPA をログアウトするには、Cookie を quarkus.http.auth.form.http-only-cookie=false に設定して、Cookie を破棄し、可能であればメインページにリダイレクトできるようにする必要があります。
const logout= () => {
// delete the credential cookie, essentially killing the session
const removeCookie = `quarkus-credential=; Max-Age=0;path=/`;
document.cookie = removeCookie;
// perform post-logout actions here, such as redirecting back to your login page
};
サーバーから SPA をログアウトするには、Cookie を quarkus.http.auth.form.http-only-cookie=true に設定し、このサンプルコードを使用して Cookie を破棄します。
@ConfigProperty(name = "quarkus.http.auth.form.cookie-name")
String cookieName;
@Inject
CurrentIdentityAssociation identity;
@POST
public Response logout() {
if (identity.getIdentity().isAnonymous()) {
throw new UnauthorizedException("Not authenticated");
}
final NewCookie removeCookie = new NewCookie.Builder(cookieName)
.maxAge(0)
.expiry(Date.from(Instant.EPOCH))
.path("/")
.build();
return Response.noContent().cookie(removeCookie).build();
}フォームベース認証を設定するには、次のプロパティーを使用できます。
ビルド時に固定された設定プロパティー: その他の設定プロパティーはすべて実行時にオーバーライド可能
| 型 | デフォルト | |
|
フォーム認証が有効な場合。
環境変数: | boolean |
|
|
post の場所です。
環境変数: | string |
|
ビルド時に固定された設定プロパティー: その他の設定プロパティーはすべて実行時にオーバーライド可能
| 型 | デフォルト | |
|
ロールマッピングへのクライアント証明書のコモンネーム (CN) が含まれるプロパティーファイル。
プロパティーファイルのフォーマットは
環境変数: | path | |
|
認証レルム
環境変数: | string | |
|
ログインページ。
環境変数: | string |
|
|
ユーザー名のフィールド名。
環境変数: | string |
|
|
パスワードのフィールド名。
環境変数: | string |
|
|
エラーページ。
環境変数: | string |
|
|
リダイレクト先の保存済みページがない場合にリダイレクトするランディングページ。
環境変数: | string |
|
|
アクセスしたい場所にユーザーをリダイレクトするために使用される Cookie の名前を制御するオプション。
環境変数: | string |
|
|
非アクティブ (アイドル) タイムアウト。非アクティブタイムアウトに達すると、Cookie は更新されず、新たなログインが強制されます。
環境変数: |
| |
|
Cookie が、タイムアウトが更新された新しい Cookie に置き換えられるまでの Cookie 存続期間 ("renewal-timeout" とも呼ばれます)。値が小さいほど、サーバーの負荷がわずかに増加します (新しい暗号化された Cookie がより頻繁に生成されるため)。ただし、値が大きいと、Cookie の生成時にタイムアウトが設定されるため、非アクティブタイムアウトに影響します。たとえばこれが 10 分に設定され、非アクティブタイムアウトが 30 分に設定された場合、ユーザーの最終リクエストの Cookie 経過時間が 9 分と仮定すると、タイムアウトは新しい Cookie が生成された後でなければ更新されないため、実際のタイムアウトは最終リクエストの 21 分後に発生します。つまり、サーバー側ではタイムアウトは追跡されず、タイムスタンプは Cookie 自体にエンコードおよび暗号化され、リクエストごとに復号化されて解析されます。
環境変数: |
| |
|
永続的なセッションの保存に使用される Cookie。
環境変数: | string |
|
|
セッションクッキーとロケーション Cookie の Cookie パス。
環境変数: | string |
|
|
JavaScript 経由での Cookie へのアクセスを防ぐために、HttpOnly 属性を設定します。
環境変数: | boolean |
|
|
セッションおよびロケーションクッキーの SameSite 属性。
環境変数: |
|
|
|
権限セット全体を有効にするかどうかを決定します。デフォルトでは、権限セットが定義されている場合は有効になります。
環境変数: | boolean | |
|
この権限セットがリンクされている HTTP ポリシー。ビルトインポリシーには、permit、deny、authenticated の 3 つがあります。ロールベースのポリシーを定義でき、エクステンションは独自のポリシーを追加できます。
環境変数: | string |
required
|
|
この権限セットが適用されるメソッド。これが設定されていない場合は、すべてのメソッドに適用されます。リクエストが任意の権限セットからの任意のパスに一致し、そのメソッドがリストされていないために制約に一致しない場合、リクエストは拒否されることに注意してください。メソッド固有の権限は、メソッドが設定されていない一致よりも優先されます。たとえば、Quarkus が /admin への GET および POST リクエストを許可するように設定されていて、他の権限が設定されていない場合、/admin への PUT リクエストは拒否されます。
環境変数: | 文字列のリスト | |
|
この権限チェックが適用されるパス。パスが /* で終わる場合はパスの接頭辞として処理され、それ以外の場合は完全一致として処理されます。一致は長さに基づいて行われるため、パスに最も具体的に一致する場合が優先されます。複数の権限セットが同じパスに一致する場合、メソッドの明示的な一致がメソッドが設定されていない一致よりも優先され、それ以外の場合は最も制限の厳しい権限が適用されます。
環境変数: | 文字列のリスト | |
|
ユーザー認証に使用しなければならないパス固有の認証メカニズム。'basic'、'bearer'、'form' などの
環境変数: | string | |
|
このポリシーが、優先されるパスのポリシーに加え、一致したパスにも必ず適用されることを示しています。パフォーマンスへの影響を最小限に抑えるため、複数の共有ポリシーは作成しないでください。
環境変数: | boolean |
|
|
このポリシーによって保護されているリソースへのアクセスが許可されるロール。デフォルトでは、すべての認証済みユーザーにアクセスが許可されます。
環境変数: | 文字列のリスト |
|
|
環境変数: |
| |
|
このポリシーが正常に適用され (ポリシーによりリクエストの続行が許可される)、認証されたリクエストに必要なロールがある場合に、
環境変数: |
| |
|
このポリシーによって付与される権限は、この設定プロパティーによって指定された
環境変数: | string |
|
duration の値を書き込むには、標準の java.time.Duration フォーマットを使用します。詳細は、Duration#parse() Java API ドキュメント を参照してください。
数字で始まる簡略化されたフォーマットも使用できます。
- 値が数値のみの場合は、秒単位の時間を表します。
-
数字の後に
msが続く値は、ミリ秒単位の時間を表します。
その他の場合は、解析のために簡略化されたフォーマットが java.time.Duration フォーマットに変換されます。
-
数字の後に
h、m、またはsが続く値には、接頭辞PTが付きます。 -
数字の後に
dが続く値は、接頭辞Pが付きます。
2.2.3. 相互 TLS 認証
Quarkus は相互 TLS (mTLS) 認証を提供するため、X.509 証明書に基づきユーザーを認証できます。
この認証方法を使用するには、まずアプリケーションで SSL/TLS を有効にする必要があります。詳細は、Quarkus の "HTTP reference" ガイドで Supporting secure connections with SSL/TLS セクションを参照してください。
アプリケーションがセキュアな接続を受け入れた後、アプリケーションが信頼するすべての証明書を保持するファイルの名前を使用して quarkus.http.ssl.certificate.trust-store-file プロパティーを設定します。指定されたファイルには、ブラウザーやその他のサービスなどのクライアントが保護されたいずれかのリソースにアクセスしようとしたときに、アプリケーションが証明書を要求する方法に関する情報も含まれています。
quarkus.http.ssl.certificate.key-store-file=server-keystore.jks 1 quarkus.http.ssl.certificate.key-store-password=the_key_store_secret quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks 2 quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret quarkus.http.ssl.client-auth=required 3 quarkus.http.auth.permission.default.paths=/* 4 quarkus.http.auth.permission.default.policy=authenticated quarkus.http.insecure-requests=disabled 5
- 1
- サーバーの秘密鍵が保存されているキーストア。
- 2
- 信頼済み証明書がロードされるトラストストア。
- 3
- 値を
requiredに設定すると、サーバーはクライアント証明書を要求します。サーバーが証明書なしでリクエストを受け入れることを許可するには、値をREQUESTに設定します。この設定は、mTLS 以外の認証方法をサポートする場合に使用できます。 - 4
- 認証されたユーザーのみがアプリケーションのリソースにアクセスできるようにするポリシーを定義します。
- 5
- プレーン HTTP プロトコルを明示的に無効にすることで、すべてのリクエストで HTTPS を使用するように求めることができます。
quarkus.http.ssl.client-authをrequiredに設定すると、システムは自動的にquarkus.http.insecure-requestsをdisabledに設定します。
受信リクエストがトラストストア内の有効な証明書と一致する場合、アプリケーションは次のように SecurityIdentity を注入してサブジェクトを取得できます。
サブジェクトの取得
@Inject
SecurityIdentity identity;
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return String.format("Hello, %s", identity.getPrincipal().getName());
}
次の例に示すコードを使用して証明書を取得することもできます。
証明書の取得
import java.security.cert.X509Certificate; import io.quarkus.security.credential.CertificateCredential; CertificateCredential credential = identity.getCredential(CertificateCredential.class); X509Certificate certificate = credential.getCertificate();
2.2.3.1. 証明書属性をロールにマッピングする
クライアント証明書の情報を使用して、Quarkus SecurityIdentity にロールを追加できます。
クライアント証明書のコモンネーム (CN) 属性を確認した後、SecurityIdentity に新しいロールを追加できます。新しいロールを追加する最も簡単な方法は、証明書属性をロールマッピング機能に使用する方法です。
たとえば、相互 TLS 認証 を紹介するセクションに示されるプロパティーを次のように更新できます。
quarkus.http.ssl.certificate.key-store-file=server-keystore.jks quarkus.http.ssl.certificate.key-store-password=the_key_store_secret quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret quarkus.http.ssl.client-auth=required quarkus.http.insecure-requests=disabled quarkus.http.auth.certificate-role-properties=cert-role-mappings.properties 1 quarkus.http.auth.permission.certauthenticated.paths=/* 2 quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert 3 quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin 4
上記の設定では、クライアント証明書の CN 属性が alice または bob の場合にリクエストが認可され、jdoe の場合はリクエストが拒否されます。
2.2.3.2. 証明書属性を使用して SecurityIdentity を強化する
自動で 証明書属性をロールにマッピングする オプションが適していない場合は、いつでも SecurityIdentityAugmentor を登録できます。カスタム SecurityIdentityAugmentor を使用して、さまざまなクライアント証明書属性の値を確認し、それに応じて SecurityIdentity を拡張できます。
SecurityIdentity のカスタマイズの詳細は、Quarkus "Security tips and tricks" ガイドの Security identity customization セクションを参照してください。
