quarkusio/quarkus · error · ConfigurationException

Username and password must be set when a password grant is u

Error message

Username and password must be set when a password grant is used

What it means

When quarkus.oidc-client.grant.type=password, the token request requires grant-options entries for username and password. OidcClientRecorder.createOidcClientUniFromMetadata closes the client and throws a ConfigurationException listing the offending properties when either is missing.

Source

Thrown at extensions/oidc-client/runtime/src/main/java/io/quarkus/oidc/client/runtime/OidcClientRecorder.java:185

        MultiMap tokenGrantParams = null;

        if (oidcConfig.grant().type() != Grant.Type.REFRESH) {
            tokenGrantParams = MultiMap.caseInsensitiveMultiMap();
            setGrantClientParams(oidcConfig, tokenGrantParams, grantType);

            if (oidcConfig.grantOptions() != null) {
                Map<String, String> grantOptions = oidcConfig.grantOptions()
                        .get(oidcConfig.grant().type().name().toLowerCase());
                if (grantOptions != null) {
                    if (oidcConfig.grant().type() == Grant.Type.PASSWORD) {
                        // Without this block `password` will be listed first, before `username`
                        // which is not a technical problem but might affect Wiremock tests or the endpoints
                        // which expect a specific order.
                        final String userName = grantOptions.get(OidcConstants.PASSWORD_GRANT_USERNAME);
                        final String userPassword = grantOptions.get(OidcConstants.PASSWORD_GRANT_PASSWORD);
                        if (userName == null || userPassword == null) {
                            client.close();
                            throw new ConfigurationException(
                                    "Username and password must be set when a password grant is used",
                                    Set.of("quarkus.oidc-client.grant.type",
                                            "quarkus.oidc-client.grant-options"));
                        }
                        tokenGrantParams.add(OidcConstants.PASSWORD_GRANT_USERNAME, userName);
                        tokenGrantParams.add(OidcConstants.PASSWORD_GRANT_PASSWORD, userPassword);
                        for (Map.Entry<String, String> entry : grantOptions.entrySet()) {
                            if (!OidcConstants.PASSWORD_GRANT_USERNAME.equals(entry.getKey())
                                    && !OidcConstants.PASSWORD_GRANT_PASSWORD.equals(entry.getKey())) {
                                tokenGrantParams.add(entry.getKey(), entry.getValue());
                            }
                        }
                    } else {
                        tokenGrantParams.addAll(grantOptions);
                    }
                }
                if (oidcConfig.grant().type() == Grant.Type.EXCHANGE
                        && !tokenGrantParams.contains(OidcConstants.EXCHANGE_GRANT_SUBJECT_TOKEN_TYPE)) {

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.oidc-client.grant-options.password.username and quarkus.oidc-client.grant-options.password.password
Confirm grant.type=password is actually intended; otherwise switch grant.type
Check property nesting under the correct named-client prefix
Verify secrets resolve in the active profile (env vars, vault, etc.)

Example fix

# before
quarkus.oidc-client.grant.type=password

# after
quarkus.oidc-client.grant.type=password
quarkus.oidc-client.grant-options.password.username=alice
quarkus.oidc-client.grant-options.password.password=secret

Defensive patterns

Strategy: validation

Validate before calling

if (GrantType.PASSWORD.equals(config.grant().type())) {
    var opts = config.grantOptions().password();
    if (opts.username().isEmpty() || opts.password().isEmpty()) throw new IllegalArgumentException("password grant requires username and password grant-options");
}

Try / catch

try { return client.getTokens().await().indefinitely(); } catch (ConfigurationException e) { if (e.getMessage().contains("Username and password must be set")) { throw new IllegalStateException("Configure grant-options.password.username/password", e); } throw e; }

Prevention

Configure username/password under quarkus.oidc-client.grant-options.password.*
Externalize the password via env var or config secret reference
Validate client config with a smoke test at startup

When it happens

Trigger: Configuring grant.type=password without quarkus.oidc-client.grant-options.password.username and quarkus.oidc-client.grant-options.password.password — detected during client creation from metadata.

Common situations: Setting grant.type=password but forgetting grant-options; placing username/password at the wrong config level (not under grant-options); YAML/properties indentation errors hiding the options; secrets not injected in the active profile.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/c3544923c707a6fe. Report an issue: GitHub.