diff --git a/extensions/oidc-common/runtime/src/main/java/io/quarkus/oidc/common/runtime/OidcCommonConfig.java b/extensions/oidc-common/runtime/src/main/java/io/quarkus/oidc/common/runtime/OidcCommonConfig.java index 46527078111ba..45b1923d5d805 100644 --- a/extensions/oidc-common/runtime/src/main/java/io/quarkus/oidc/common/runtime/OidcCommonConfig.java +++ b/extensions/oidc-common/runtime/src/main/java/io/quarkus/oidc/common/runtime/OidcCommonConfig.java @@ -166,13 +166,13 @@ public static enum Method { BASIC, /** - * client_secret_post: client id and secret are submitted as the 'client_id' and 'client_secret' form + * client_secret_post: client id and secret are submitted as the `client_id` and `client_secret` form * parameters. */ POST, /** - * client_secret_jwt: client id and generated JWT secret are submitted as the 'client_id' and 'client_secret' + * client_secret_jwt: client id and generated JWT secret are submitted as the `client_id` and `client_secret` * form * parameters. */ @@ -223,7 +223,7 @@ public void setSecretProvider(Provider secretProvider) { } /** - * Supports the client authentication 'client_secret_jwt' and 'private_key_jwt' methods which involve sending a JWT + * Supports the client authentication 'client_secret_jwt' and `private_key_jwt` methods which involve sending a JWT * token * assertion signed with either a client secret or private key. * @@ -252,13 +252,13 @@ public static class Jwt { public Optional keyFile = Optional.empty(); /** - * If provided, indicates that JWT is signed using a private key from a key store + * If provided, indicates that JWT is signed using a private key from a keystore */ @ConfigItem public Optional keyStoreFile = Optional.empty(); /** - * A parameter to specify the password of the key store file. + * A parameter to specify the password of the keystore file. */ @ConfigItem public Optional keyStorePassword; @@ -289,7 +289,7 @@ public static class Jwt { public Optional tokenKeyId = Optional.empty(); /** - * Issuer of the signing key added as a JWT 'iss' claim (default: client id) + * Issuer of the signing key added as a JWT `iss` claim (default: client id) */ @ConfigItem public Optional issuer = Optional.empty(); @@ -441,41 +441,41 @@ public enum Verification { } /** - * Certificate validation and hostname verification, which can be one of the following values from enum - * {@link Verification}. Default is required. + * Certificate validation and hostname verification, which can be one of the following {@link Verification} values. + * Default is required. */ @ConfigItem public Optional verification = Optional.empty(); /** - * An optional key store which holds the certificate information instead of specifying separate files. + * An optional keystore which holds the certificate information instead of specifying separate files. */ @ConfigItem public Optional keyStoreFile = Optional.empty(); /** - * An optional parameter to specify type of the key store file. If not given, the type is automatically detected + * An optional parameter to specify type of the keystore file. If not given, the type is automatically detected * based on the file name. */ @ConfigItem public Optional keyStoreFileType = Optional.empty(); /** - * An optional parameter to specify a provider of the key store file. If not given, the provider is automatically + * An optional parameter to specify a provider of the keystore file. If not given, the provider is automatically * detected - * based on the key store file type. + * based on the keystore file type. */ @ConfigItem public Optional keyStoreProvider; /** - * A parameter to specify the password of the key store file. If not given, the default ("password") is used. + * A parameter to specify the password of the keystore file. If not given, the default ("password") is used. */ @ConfigItem public Optional keyStorePassword; /** - * An optional parameter to select a specific key in the key store. When SNI is disabled, if the key store contains + * An optional parameter to select a specific key in the keystore. When SNI is disabled, if the keystore contains * multiple * keys and no alias is specified, the behavior is undefined. */ @@ -489,34 +489,34 @@ public enum Verification { public Optional keyStoreKeyPassword = Optional.empty(); /** - * An optional trust store which holds the certificate information of the certificates to trust + * An optional truststore which holds the certificate information of the certificates to trust */ @ConfigItem public Optional trustStoreFile = Optional.empty(); /** - * A parameter to specify the password of the trust store file. + * A parameter to specify the password of the truststore file. */ @ConfigItem public Optional trustStorePassword = Optional.empty(); /** - * A parameter to specify the alias of the trust store certificate. + * A parameter to specify the alias of the truststore certificate. */ @ConfigItem public Optional trustStoreCertAlias = Optional.empty(); /** - * An optional parameter to specify type of the trust store file. If not given, the type is automatically detected + * An optional parameter to specify type of the truststore file. If not given, the type is automatically detected * based on the file name. */ @ConfigItem public Optional trustStoreFileType = Optional.empty(); /** - * An optional parameter to specify a provider of the trust store file. If not given, the provider is automatically + * An optional parameter to specify a provider of the truststore file. If not given, the provider is automatically * detected - * based on the trust store file type. + * based on the truststore file type. */ @ConfigItem public Optional trustStoreProvider; diff --git a/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/OidcBuildTimeConfig.java b/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/OidcBuildTimeConfig.java index b9e2edd863702..2a25611394c30 100644 --- a/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/OidcBuildTimeConfig.java +++ b/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/OidcBuildTimeConfig.java @@ -22,8 +22,8 @@ public class OidcBuildTimeConfig { public DevUiConfig devui; /** * Enable the registration of the Default TokenIntrospection and UserInfo Cache implementation bean. - * Note it only allows to use the default implementation, one needs to configure it in order to activate it, - * please see {@link OidcConfig#tokenCache}. + * Note: This only enables the default implementation. It requires configuration to be activated. + * See {@link OidcConfig#tokenCache}. */ @ConfigItem(defaultValue = "true") public boolean defaultTokenCacheEnabled; diff --git a/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/devservices/keycloak/DevServicesConfig.java b/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/devservices/keycloak/DevServicesConfig.java index 624675b4fd05c..05a69f6df1015 100644 --- a/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/devservices/keycloak/DevServicesConfig.java +++ b/extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/devservices/keycloak/DevServicesConfig.java @@ -23,11 +23,11 @@ public class DevServicesConfig { public boolean enabled = true; /** - * The container image name to use, for container based DevServices providers. + * The container image name to use, for container-based DevServices providers. * * Image with a Quarkus based distribution is used by default. * Image with a WildFly based distribution can be selected instead, for example: - * 'quay.io/keycloak/keycloak:19.0.3-legacy'. + * `quay.io/keycloak/keycloak:19.0.3-legacy`. *

* Note Keycloak Quarkus and Keycloak WildFly images are initialized differently. * By default, Dev Services for Keycloak will assume it is a Keycloak Quarkus image if the image version does not end with a @@ -106,17 +106,17 @@ public class DevServicesConfig { /** * The Keycloak realm name. - * This property will be used to create the realm if the realm file pointed to by the 'realm-path' property does not exist, - * default value is 'quarkus' in this case. - * If the realm file pointed to by the 'realm-path' property exists then it is still recommended to set this property - * for Dev Services for Keycloak to avoid parsing the realm file in order to determine the realm name. + * This property will be used to create the realm if the realm file pointed to by the `realm-path` property does not exist, + * default value is `quarkus` in this case. + * If the realm file pointed to by the `realm-path` property exists then it is still recommended to set this property + * for Dev Services for Keycloak to avoid parsing the realm file to determine the realm name. * */ @ConfigItem public Optional realmName; /** - * Indicates if the Keycloak realm has to be created when the realm file pointed to by the 'realm-path' property does not + * Indicates if the Keycloak realm has to be created when the realm file pointed to by the `realm-path` property does not * exist. * * Disable it if you'd like to create a realm using Keycloak Administration Console @@ -128,7 +128,7 @@ public class DevServicesConfig { /** * The Keycloak users map containing the username and password pairs. * If this map is empty then two users, 'alice' and 'bob' with the passwords matching their names will be created. - * This property will be used to create the Keycloak users if the realm file pointed to by the 'realm-path' property does + * This property will be used to create the Keycloak users if the realm file pointed to by the `realm-path` property does * not exist. */ @ConfigItem @@ -138,7 +138,7 @@ public class DevServicesConfig { * The Keycloak user roles. * If this map is empty then a user named 'alice' will get 'admin' and 'user' roles and all other users will get a 'user' * role. - * This property will be used to create the Keycloak roles if the realm file pointed to by the 'realm-path' property does + * This property will be used to create the Keycloak roles if the realm file pointed to by the `realm-path` property does * not exist. */ @ConfigItem diff --git a/extensions/oidc/runtime/src/main/java/io/quarkus/oidc/OidcTenantConfig.java b/extensions/oidc/runtime/src/main/java/io/quarkus/oidc/OidcTenantConfig.java index 48d25c15adfa4..db4eea48e8d00 100644 --- a/extensions/oidc/runtime/src/main/java/io/quarkus/oidc/OidcTenantConfig.java +++ b/extensions/oidc/runtime/src/main/java/io/quarkus/oidc/OidcTenantConfig.java @@ -40,7 +40,7 @@ public class OidcTenantConfig extends OidcCommonConfig { public boolean tenantEnabled = true; /** - * The application type, which can be one of the following values from enum {@link ApplicationType}. + * The application type, which can be one of the following {@link ApplicationType} values. */ @ConfigItem(defaultValueDocumentation = "service") public Optional applicationType = Optional.empty(); @@ -54,9 +54,9 @@ public class OidcTenantConfig extends OidcCommonConfig { public Optional authorizationPath = Optional.empty(); /** - * Relative path or absolute URL of the OIDC userinfo endpoint. + * Relative path or absolute URL of the OIDC UserInfo endpoint. * This property must only be set for the 'web-app' applications if OIDC discovery is disabled - * and 'authentication.user-info-required' property is enabled. + * and `authentication.user-info-required` property is enabled. * This property will be ignored if the discovery is enabled. */ @ConfigItem @@ -189,7 +189,7 @@ public void setIncludeClientId(boolean includeClientId) { /** * Allow caching the token introspection data. * Note enabling this property does not enable the cache itself but only permits to cache the token introspection - * for a given tenant. If the default token cache can be used then please see {@link OidcConfig.TokenCache} how to enable + * for a given tenant. If the default token cache can be used, see {@link OidcConfig.TokenCache} to enable * it. */ @ConfigItem(defaultValue = "true") @@ -198,7 +198,7 @@ public void setIncludeClientId(boolean includeClientId) { /** * Allow caching the user info data. * Note enabling this property does not enable the cache itself but only permits to cache the user info data - * for a given tenant. If the default token cache can be used then please see {@link OidcConfig.TokenCache} how to enable + * for a given tenant. If the default token cache can be used, see {@link OidcConfig.TokenCache} to enable * it. */ @ConfigItem(defaultValue = "true") @@ -689,7 +689,7 @@ public enum CookieSameSite { */ public enum ResponseMode { /** - * Authorization response parameters are encoded in the query string added to the redirect_uri + * Authorization response parameters are encoded in the query string added to the `redirect_uri` */ QUERY, @@ -707,19 +707,19 @@ public enum ResponseMode { public Optional responseMode = Optional.empty(); /** - * Relative path for calculating a "redirect_uri" query parameter. + * Relative path for calculating a `redirect_uri` query parameter. * It has to start from a forward slash and will be appended to the request URI's host and port. - * For example, if the current request URI is 'https://localhost:8080/service' then a 'redirect_uri' parameter + * For example, if the current request URI is 'https://localhost:8080/service' then a `redirect_uri` parameter * will be set to 'https://localhost:8080/' if this property is set to '/' and be the same as the request URI * if this property has not been configured. * Note the original request URI will be restored after the user has authenticated if 'restorePathAfterRedirect' is set - * to 'true'. + * to `true`. */ @ConfigItem public Optional redirectPath = Optional.empty(); /** - * If this property is set to 'true' then the original request URI which was used before + * If this property is set to `true` then the original request URI which was used before * the authentication will be restored after the user has been redirected back to the application. * * Note if `redirectPath` property is not set, the original request URI will be restored even if this property is @@ -737,8 +737,8 @@ public enum ResponseMode { /** * Relative path to the public endpoint which will process the error response from the OIDC authorization endpoint. - * If the user authentication has failed then the OIDC provider will return an 'error' and an optional - * 'error_description' + * If the user authentication has failed then the OIDC provider will return an `error` and an optional + * `error_description` * parameters, instead of the expected authorization 'code'. * * If this property is set then the user will be redirected to the endpoint which can return a user-friendly @@ -769,7 +769,7 @@ public enum ResponseMode { public boolean verifyAccessToken; /** - * Force 'https' as the 'redirect_uri' parameter scheme when running behind an SSL terminating reverse proxy. + * Force 'https' as the `redirect_uri` parameter scheme when running behind an SSL/TLS terminating reverse proxy. * This property, if enabled, will also affect the logout `post_logout_redirect_uri` and the local redirect requests. */ @ConfigItem(defaultValueDocumentation = "false") @@ -791,7 +791,7 @@ public enum ResponseMode { public boolean nonceRequired = false; /** - * Add the 'openid' scope automatically to the list of scopes. This is required for OpenId Connect providers + * Add the `openid` scope automatically to the list of scopes. This is required for OpenId Connect providers * but will not work for OAuth2 providers such as Twitter OAuth2 which does not accept that scope and throws an error. */ @ConfigItem(defaultValueDocumentation = "true") @@ -811,8 +811,8 @@ public enum ResponseMode { public Optional> forwardParams = Optional.empty(); /** - * If enabled the state, session and post logout cookies will have their 'secure' parameter set to 'true' - * when HTTP is used. It may be necessary when running behind an SSL terminating reverse proxy. + * If enabled the state, session and post logout cookies will have their 'secure' parameter set to `true` + * when HTTP is used. It may be necessary when running behind an SSL/TLS terminating reverse proxy. * The cookies will always be secure if HTTPS is used even if this property is set to false. */ @ConfigItem(defaultValue = "false") @@ -820,8 +820,8 @@ public enum ResponseMode { /** * Cookie name suffix. - * For example, a session cookie name for the default OIDC tenant is 'q_session' but can be changed to 'q_session_test' - * if this property is set to 'test'. + * For example, a session cookie name for the default OIDC tenant is `q_session` but can be changed to `q_session_test` + * if this property is set to `test`. */ @ConfigItem public Optional cookieSuffix = Optional.empty(); @@ -861,8 +861,7 @@ public enum ResponseMode { * However, if multiple authentications are attempted from the same browser, for example, from the different * browser tabs, then the currently available state cookie may represent the authentication flow * initiated from another tab and not related to the current request. - * Disable this property if you would like to avoid supporting multiple authorization code flows running in the same - * browser. + * Disable this property to permit only a single authorization code flow in the same browser. * */ @ConfigItem(defaultValue = "true") @@ -886,14 +885,14 @@ public enum ResponseMode { * with {@link #redirectPath} may be needed to avoid such errors. *

* However, setting this property to `false` may help if the above options are not suitable. - * It will cause a new authentication redirect to OpenId Connect provider. Please be aware doing so may increase the + * It will cause a new authentication redirect to OpenId Connect provider. Doing so may increase the * risk of browser redirect loops. */ @ConfigItem(defaultValue = "false") public boolean failOnMissingStateParam = false; /** - * If this property is set to 'true' then an OIDC UserInfo endpoint will be called. + * If this property is set to `true` then an OIDC UserInfo endpoint will be called. * This property will be enabled if `quarkus.oidc.roles.source` is `userinfo` * or `quarkus.oidc.token.verify-access-token-with-user-info` is `true` * or `quarkus.oidc.authentication.id-token-required` is set to `false`, @@ -906,7 +905,7 @@ public enum ResponseMode { * Session age extension in minutes. * The user session age property is set to the value of the ID token life-span by default and * the user will be redirected to the OIDC provider to re-authenticate once the session has expired. - * If this property is set to a non-zero value then the expired ID token can be refreshed before + * If this property is set to a non-zero value, then the expired ID token can be refreshed before * the session has expired. * This property will be ignored if the `token.refresh-expired` property has not been enabled. */ @@ -914,7 +913,7 @@ public enum ResponseMode { public Duration sessionAgeExtension = Duration.ofMinutes(5); /** - * If this property is set to 'true' then a normal 302 redirect response will be returned + * If this property is set to `true` then a normal 302 redirect response will be returned * if the request was initiated via JavaScript API such as XMLHttpRequest or Fetch and the current user needs to be * (re)authenticated which may not be desirable for Single-page applications (SPA) since * it automatically following the redirect may not work given that OIDC authorization endpoints typically do not support @@ -1276,7 +1275,7 @@ public static Token fromAudience(String... audience) { } /** - * Expected issuer 'iss' claim value. + * Expected issuer `iss` claim value. * Note this property overrides the `issuer` property which may be set in OpenId Connect provider's well-known * configuration. * If the `iss` claim value varies depending on the host/IP address or tenant id of the provider then you may skip the @@ -1356,7 +1355,7 @@ public static Token fromAudience(String... audience) { public Optional age = Optional.empty(); /** - * Name of the claim which contains a principal name. By default, the 'upn', 'preferred_username' and `sub` claims are + * Name of the claim which contains a principal name. By default, the `upn`, `preferred_username` and `sub` claims are * checked. */ @ConfigItem @@ -1418,7 +1417,7 @@ public static Token fromAudience(String... audience) { * the providers may not control the private decryption keys. * In such cases set this property to point to the file containing the decryption private key in * PEM or JSON Web Key (JWK) format. - * Note that if a 'private_key_jwt' client authentication method is used then the private key + * Note that if a `private_key_jwt` client authentication method is used then the private key * which is used to sign client authentication JWT tokens will be used to try to decrypt an encrypted ID token * if this property is not set. */ @@ -1428,7 +1427,7 @@ public static Token fromAudience(String... audience) { /** * Allow the remote introspection of JWT tokens when no matching JWK key is available. * - * Note this property is set to 'true' by default for backward-compatibility reasons and will be set to `false` + * Note this property is set to `true` by default for backward-compatibility reasons and will be set to `false` * instead in one of the next releases. * * Also note this property will be ignored if JWK endpoint URI is not available and introspecting the tokens is @@ -1627,7 +1626,7 @@ public void setSubjectRequired(boolean subjectRequired) { public static enum ApplicationType { /** - * A {@code WEB_APP} is a client that serves pages, usually a frontend application. For this type of client the + * A {@code WEB_APP} is a client that serves pages, usually a front-end application. For this type of client the * Authorization Code Flow is defined as the preferred method for authenticating users. */ WEB_APP,