Authentication Mechanisms and Identity Stores

quarkus-elytron-security-properties-file is the simplest identity store — users and roles read from a static file or inline configuration — appropriate for local development, tests, and small internal tools, never for production user management:

or, from a properties file on the classpath instead of inline configuration:

with users.properties mapping username=password (or a pre-computed hash when plain-text=false) and roles.properties mapping username=role1,role2. plain-text=false is strongly preferred outside local development — it expects a BCrypt hash rather than a plaintext password sitting in a file on disk.

quarkus-security-jdbc authenticates against an existing users/roles table structure via a hand-written SQL query, over a plain JDBC datasource (see Datasources and Transactions for configuring that datasource itself):

The query’s own column order drives password-index/attribute-mappings — there is no fixed schema quarkus- security-jdbc imposes, which makes it the right fit for authenticating against a user table an existing application already owns, at the cost of writing and maintaining that SQL by hand.

quarkus-security-jpa maps authentication onto a Hibernate ORM/Panache entity instead of hand-written SQL — see Hibernate ORM and JPA for the entity mapping this builds on:

@UserDefinition marks the entity as the identity source; @Username, @Password, and @Roles mark which fields carry each piece. By default @Password is compared as a BCrypt hash — BcryptUtil.bcryptHash(…​) above produces one at write time, and quarkus-security-jpa verifies it the same way at login time, so a plaintext password is never stored or compared.

quarkus-elytron-security-ldap authenticates against an existing LDAP or Active Directory directory — appropriate when user accounts are already centrally managed there rather than in an application-owned table:

dir-context. configures the service account Quarkus uses to bind and search the directory; identity-mapping. configures how a username resolves to a directory entry (rdn-identifier plus search-base-dn) and how that entry’s group memberships map onto SecurityIdentity roles.

quarkus-webauthn implements the WebAuthn/FIDO2 ceremonies — registration and assertion — against a browser’s platform authenticator (a passkey backed by Face ID, Windows Hello, a hardware security key), storing each user’s public-key credential rather than a password at all:

A WebAuthnUserProvider CDI bean (application-supplied) persists each user’s WebAuthn credential records (public key, sign counter) after the browser-side registration ceremony completes, and looks them up again on each subsequent assertion; the browser-side JavaScript ceremony itself (navigator.credentials.create()/.get()) sits outside the Quarkus extension’s scope entirely. Passkeys are the strongest and most phishing-resistant primary-authentication method covered on this page — the origin-bound cryptographic challenge that WebAuthn performs makes credential phishing structurally impossible in a way no password-based mechanism can match; see Authentication Methods: Passwordless and 2FA for how passkeys compare to the other passwordless and 2FA options along both of that page’s axes.

Mutual TLS authenticates the client during the TLS handshake itself, via a client certificate, rather than through any application-layer credential — configured on the TLS registry with client-certificate authentication turned on:

client-auth=required rejects the TLS handshake outright for a client that presents no certificate, or one not signed by a CA in the configured trust store; client-auth=request accepts the connection either way but still surfaces the certificate (if any) for the IdentityProvider mechanism below to consume. quarkus-elytron- security-ldap’s mTLS support (or a custom `IdentityProvider reading HttpAuthenticationMechanism’s `X509Certificate from the routing context) maps the certificate’s subject onto a SecurityIdentity; because authentication concludes at the TLS layer, mTLS composes cleanly with a quarkus.http.auth.permission.* policy restricting only the paths that need certificate-based clients, while other paths on the same server continue authenticating some other way.

More than one mechanism can be active at once — each HttpAuthenticationMechanism only actually engages for a request that carries its own kind of credential, so registering quarkus-elytron-security-properties-file (Basic) alongside quarkus-oidc (bearer JWT) does not force every client onto one scheme. Where mechanisms would otherwise be ambiguous for the same path, scope each explicitly with quarkus.http.auth.permission.* path matching (see Security Overview and Architecture) so a browser-facing path uses form/session authentication while a machine-facing API path under the same application uses bearer tokens. The general rule for choosing among the mechanisms on this page: reach for the properties-file store only in development/tests; JDBC when an existing hand-rolled user table must be reused as-is; JPA when the identity store can be modeled as a first-class entity in the application’s own domain; LDAP when accounts are already centrally managed there; WebAuthn for the strongest phishing resistance available to end users; and mTLS for service-to-service or highly-controlled-client scenarios where a certificate can actually be provisioned to every legitimate caller.

Older material — including the Quarkus Cookbook — documents identity stores under names that have since been renamed or reorganized: quarkus-elytron-security-jdbc is now quarkus-security-jdbc, and quarkus-elytron-security-jpa is now quarkus-security-jpa. quarkus-elytron-security-properties-file and quarkus-elytron-security-ldap keep their original elytron-prefixed names (they were not renamed), so the elytron prefix by itself is not a reliable signal that an extension is legacy — what changed is specifically the JDBC and JPA identity-store artifact names. A project built against the older names should update its pom.xml/build.gradle dependency coordinates and, where the guide being followed still shows quarkus-elytron-security-jdbc/-jpa, treat the current JDBC guide and the current JPA guide as authoritative over the older text.