From cd9bec4efc8c59b1b7c8bba65fe64d5c4fa4fb21 Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Thu, 14 Dec 2023 14:07:14 -0500 Subject: [PATCH] Javadoc edits for quarkus-oidc.adoc --- .../oidc/common/runtime/OidcCommonConfig.java | 161 ++++---- .../keycloak/DevServicesConfig.java | 126 +++--- .../io/quarkus/oidc/OidcTenantConfig.java | 366 +++++++++--------- 3 files changed, 318 insertions(+), 335 deletions(-) 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 f3810d610a001..27eeef7703b04 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 @@ -13,84 +13,76 @@ @ConfigGroup public class OidcCommonConfig { /** - * The base URL of the OpenID Connect (OIDC) server, for example, `https://host:port/auth`. - * OIDC discovery endpoint will be called by default by appending a '.well-known/openid-configuration' path to this URL. - * Note if you work with Keycloak OIDC server, make sure the base URL is in the following format: - * `https://host:port/realms/{realm}` where `{realm}` has to be replaced by the name of the Keycloak realm. + * Optional. The base URL of the OpenID Connect (OIDC) server, for example, `https://host:port/auth`. + * The OIDC discovery endpoint is called by default by appending a `.well-known/openid-configuration` path to this URL. + * For Keycloak, use `https://host:port/realms/{realm}`, replacing `{realm}` with the Keycloak realm name. */ @ConfigItem public Optional authServerUrl = Optional.empty(); /** - * Enables OIDC discovery. - * If the discovery is disabled then the OIDC endpoint URLs must be configured individually. + * Optional. Discovery of the OIDC endpoints. + * If not enabled, you must configure the OIDC endpoint URLs individually. */ @ConfigItem(defaultValueDocumentation = "true") public Optional discoveryEnabled = Optional.empty(); /** - * Relative path or absolute URL of the OIDC token endpoint which issues access and refresh tokens. + * Optional. The OIDC token endpoint that issues access and refresh tokens; + * specified as a relative path or absolute URL. */ @ConfigItem public Optional tokenPath = Optional.empty(); /** - * Relative path or absolute URL of the OIDC token revocation endpoint. + * Optional. The relative path or absolute URL of the OIDC token revocation endpoint. */ @ConfigItem public Optional revokePath = Optional.empty(); /** - * The client-id of the application. Each application has a client-id that is used to identify the application + * Optional. The client id of the application. Each application has a client id that is used to identify the application. */ @ConfigItem public Optional clientId = Optional.empty(); /** - * The maximum amount of time connecting to the currently unavailable OIDC server will be attempted for. - * The number of times the connection request will be repeated is calculated by dividing the value of this property by 2. - * For example, setting it to `20S` will allow for requesting the connection up to 10 times with a 2 seconds delay between - * the retries. - * Note this property is only effective when the initial OIDC connection is created, - * for example, when requesting a well-known OIDC configuration. - * Use the 'connection-retry-count' property to support trying to re-establish an already available connection which may - * have been - * dropped. + * Optional. The duration to attempt the initial connection to an OIDC server. + * For example, setting the duration to `20S` allows 10 retries, each 2 seconds apart. + * This property is only effective when the initial OIDC connection is created. + * For dropped connections, use the `connection-retry-count` property instead. */ @ConfigItem public Optional connectionDelay = Optional.empty(); /** - * The number of times an attempt to re-establish an already available connection will be repeated. - * Note this property is different from the `connection-delay` property, which is only effective during the initial OIDC - * connection creation. - * This property is used to try to recover an existing connection that may have been temporarily lost. - * For example, if a request to the OIDC token endpoint fails due to a connection exception, then the request will be - * retried the number of times configured by this property. + * The number of times to retry re-establishing an existing OIDC connection if it's temporarily lost. + * Different from `connection-delay`, which applies only to initial connection attempts. + * For instance, if a request to the OIDC token endpoint fails due to a connection issue, it will be retried as per this setting. */ @ConfigItem(defaultValue = "3") public int connectionRetryCount = 3; /** - * The amount of time after which the current OIDC connection request will time out. + * The amount of time after which the current OIDC connection request times out. */ @ConfigItem(defaultValue = "10s") public Duration connectionTimeout = Duration.ofSeconds(10); /** - * The maximum size of the connection pool used by the WebClient + * Optional. The maximum size of the connection pool used by the WebClient. */ @ConfigItem public OptionalInt maxPoolSize = OptionalInt.empty(); /** - * Credentials which the OIDC adapter will use to authenticate to the OIDC server. + * Credentials the OIDC adapter uses to authenticate to the OIDC server. */ @ConfigItem public Credentials credentials = new Credentials(); /** - * Options to configure a proxy that OIDC adapter will use for talking with OIDC server. + * Options to configure the proxy the OIDC adapter uses to talk with the OIDC server. */ @ConfigItem public Proxy proxy = new Proxy(); @@ -105,15 +97,14 @@ public class OidcCommonConfig { public static class Credentials { /** - * Client secret which is used for a `client_secret_basic` authentication method. - * Note that a 'client-secret.value' can be used instead but both properties are mutually exclusive. + * Optional. The client secret used by the `client_secret_basic` authentication method. + * You can use `client-secret.value` instead, but both properties are mutually exclusive. */ @ConfigItem public Optional secret = Optional.empty(); /** - * Client secret which can be used for the `client_secret_basic` (default) and `client_secret_post` - * and 'client_secret_jwt' authentication methods. + * The client secret used by the `client_secret_basic` (default), `client_secret_post`, or `client_secret_jwt` authentication methods. * Note that a `secret.value` property can be used instead to support the `client_secret_basic` method * but both properties are mutually exclusive. */ @@ -121,7 +112,7 @@ public static class Credentials { public Secret clientSecret = new Secret(); /** - * Client JWT authentication methods + * Client JSON Web Token (JWT) authentication methods */ @ConfigItem public Jwt jwt = new Jwt(); @@ -151,7 +142,7 @@ public void setJwt(Jwt jwt) { } /** - * Supports the client authentication methods which involve sending a client secret. + * Supports the client authentication methods that involve sending a client secret. * * @see https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication @@ -161,38 +152,37 @@ public static class Secret { public static enum Method { /** - * client_secret_basic (default): client id and secret are submitted with the HTTP Authorization Basic scheme + * `client_secret_basic` (default): The client id and secret are submitted with the HTTP Authorization Basic scheme. */ BASIC, /** - * client_secret_post: client id and secret are submitted as the `client_id` and `client_secret` form - * parameters. + * `client_secret_post`: The 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` - * form - * parameters. + * `client_secret_jwt`: The client id and generated JWT secret are submitted as the `client_id` and `client_secret` + * form parameters. */ POST_JWT } /** - * The client secret value - it will be ignored if 'credentials.secret' is set + * Optional. The client secret value. This value is ignored if `credentials.secret` is set. */ @ConfigItem public Optional value = Optional.empty(); /** - * The Secret CredentialsProvider + * The Secret CredentialsProvider. */ @ConfigItem public Provider provider = new Provider(); /** - * Authentication method. + * Optional. The authentication method. */ @ConfigItem public Optional method = Optional.empty(); @@ -223,9 +213,8 @@ public void setSecretProvider(Provider secretProvider) { } /** - * 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. + * Supports the client authentication `client_secret_jwt` and `private_key_jwt` methods, which involves sending a JWT + * token assertion signed with a client secret or private key. * * @see https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication @@ -233,69 +222,69 @@ public void setSecretProvider(Provider secretProvider) { @ConfigGroup public static class Jwt { /** - * If provided, indicates that JWT is signed using a secret key + * Optional. If provided, indicates that JWT is signed using a secret key. */ @ConfigItem public Optional secret = Optional.empty(); /** - * If provided, indicates that JWT is signed using a secret key provided by Secret CredentialsProvider + * If provided, indicates that JWT is signed using a secret key provided by Secret CredentialsProvider. */ @ConfigItem public Provider secretProvider = new Provider(); /** - * If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the + * Optional. If provided, indicates that JWT is signed using a private key in PEM or JWK format. You can use the * {@link #signatureAlgorithm} property to specify the key algorithm. */ @ConfigItem public Optional keyFile = Optional.empty(); /** - * If provided, indicates that JWT is signed using a private key from a keystore + * Optional. 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 keystore file. + * Optional. A parameter to specify the password of the keystore file. */ @ConfigItem public Optional keyStorePassword; /** - * The private key id/alias + * Optional. The private key id or alias. */ @ConfigItem public Optional keyId = Optional.empty(); /** - * The private key password + * Optional. The private key password. */ @ConfigItem public Optional keyPassword; /** - * JWT audience ('aud') claim value. + * Optional. The JWT audience (`aud`) claim value. * By default, the audience is set to the address of the OpenId Connect Provider's token endpoint. */ @ConfigItem public Optional audience = Optional.empty(); /** - * Key identifier of the signing key added as a JWT 'kid' header + * Optional. The key identifier of the signing key added as a JWT `kid` header. */ @ConfigItem public Optional tokenKeyId = Optional.empty(); /** - * Issuer of the signing key added as a JWT `iss` claim (default: client id) + * Optional. The issuer of the signing key added as a JWT `iss` claim. The default value is the client id. */ @ConfigItem public Optional issuer = Optional.empty(); /** - * Subject of the signing key added as a JWT 'sub' claim (default: client id) + * Optional. Subject of the signing key added as a JWT `sub` claim The default value is the client id. */ @ConfigItem public Optional subject = Optional.empty(); @@ -307,14 +296,14 @@ public static class Jwt { public Map claims = new HashMap<>(); /** - * Signature algorithm, also used for the {@link #keyFile} property. - * Supported values: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512. + * Optional. The signature algorithm, also used for the {@link #keyFile} property. + * Supported values: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`, `HS256`, `HS384`, `HS512`. */ @ConfigItem public Optional signatureAlgorithm = Optional.empty(); /** - * JWT life-span in seconds. It will be added to the time it was issued at to calculate the expiration time. + * The JWT lifespan in seconds. This value is added to the time the JWT was issued to calculate the expiration time. */ @ConfigItem(defaultValue = "10") public int lifespan = 10; @@ -386,19 +375,19 @@ public void setClaims(Map claims) { } /** - * CredentialsProvider which provides a client secret + * CredentialsProvider, which provides a client secret. */ @ConfigGroup public static class Provider { /** - * The CredentialsProvider name which should only be set if more than one CredentialsProvider is registered + * Optional. The CredentialsProvider name, which should only be set if more than one CredentialsProvider is registered */ @ConfigItem public Optional name = Optional.empty(); /** - * The CredentialsProvider client secret key + * Optional. The CredentialsProvider client secret key */ @ConfigItem public Optional key = Optional.empty(); @@ -435,87 +424,85 @@ public enum Verification { CERTIFICATE_VALIDATION, /** - * All certificated are trusted and hostname verification is disabled. + * All certificates are trusted and hostname verification is disabled. */ NONE } /** - * Certificate validation and hostname verification, which can be one of the following {@link Verification} values. + * Optional. 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 keystore which holds the certificate information instead of specifying separate files. + * Optional. A keystore file that holds the certificate information instead of specifying separate files. */ @ConfigItem public Optional keyStoreFile = Optional.empty(); /** - * An optional parameter to specify type of the keystore file. If not given, the type is automatically detected - * based on the file name. + * Optional. The 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 keystore file. If not given, the provider is automatically - * detected - * based on the keystore file type. + * Optional. The provider of the keystore file. If not given, the provider is automatically detected based on the keystore file type. */ @ConfigItem public Optional keyStoreProvider; /** - * A parameter to specify the password of the keystore file. If not given, the default ("password") is used. + * Optional. The password of the keystore file. If not given, the default value, `password`, is used. */ @ConfigItem public Optional keyStorePassword; /** - * An optional parameter to select a specific key in the keystore. When SNI is disabled, if the keystore contains - * multiple + * Optional. The alias of 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. */ @ConfigItem public Optional keyStoreKeyAlias = Optional.empty(); /** - * An optional parameter to define the password for the key, in case it's different from {@link #keyStorePassword}. + * Optional. The password of the key, if it is different from the {@link #keyStorePassword}. */ @ConfigItem public Optional keyStoreKeyPassword = Optional.empty(); /** - * An optional truststore which holds the certificate information of the certificates to trust + * Optional. The truststore that holds the certificate information of the certificates to trust. */ @ConfigItem public Optional trustStoreFile = Optional.empty(); /** - * A parameter to specify the password of the truststore file. + * Optional. The password of the truststore file. */ @ConfigItem public Optional trustStorePassword = Optional.empty(); /** - * A parameter to specify the alias of the truststore certificate. + * Optional. The alias of the truststore certificate. */ @ConfigItem public Optional trustStoreCertAlias = Optional.empty(); /** - * An optional parameter to specify type of the truststore file. If not given, the type is automatically detected + * Optional. The 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 truststore file. If not given, the provider is automatically - * detected + * Optional. The provider of the truststore file. + * If not given, the provider is automatically detected * based on the truststore file type. */ @ConfigItem @@ -575,27 +562,27 @@ public void setTrustStoreProvider(String trustStoreProvider) { public static class Proxy { /** - * The host (name or IP address) of the Proxy.
- * Note: If OIDC adapter needs to use a Proxy to talk with OIDC server (Provider), - * then at least the "host" config item must be configured to enable the usage of a Proxy. + * Optional. The host name or IP address of the Proxy.
+ * Note: If the OIDC adapter requires a Proxy to talk with the OIDC server (Provider), + * set this value to enable the usage of a Proxy. */ @ConfigItem public Optional host = Optional.empty(); /** - * The port number of the Proxy. Default value is 80. + * The port number of the Proxy. The default value is `80`. */ @ConfigItem(defaultValue = "80") public int port = 80; /** - * The username, if Proxy needs authentication. + * Optional. The username, if the Proxy needs authentication. */ @ConfigItem public Optional username = Optional.empty(); /** - * The password, if Proxy needs authentication. + * Optional. The password, if the Proxy needs authentication. */ @ConfigItem public Optional password = Optional.empty(); 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 6a82d0475c8a3..68bca25f9ac5f 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 @@ -14,52 +14,43 @@ public class DevServicesConfig { /** - * If DevServices has been explicitly enabled or disabled. - *

- * When DevServices is enabled Quarkus will attempt to automatically configure and start - * Keycloak when running in Dev or Test mode and when Docker is running. + * Flag to enable (default) or disable Dev Services. + * + * When enabled, automatically configures and starts Keycloak in Dev or Test mode, and when Docker is active. */ @ConfigItem(defaultValue = "true") public boolean enabled = true; /** - * The container image name to use, for container-based DevServices providers. + * The container image name for Dev Services 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`. - *

- * 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 - * '-legacy' - * string. - * Set 'quarkus.keycloak.devservices.keycloak-x-image' to override this check. + * Defaults to a Quarkus-based Keycloak image. For a WildFly-based distribution, use an image like `quay.io/keycloak/keycloak:19.0.3-legacy`. + * + * Keycloak Quarkus and WildFly images are initialized differently. The default is Keycloak Quarkus unless the image version ends with `-legacy`. + * Override with `quarkus.keycloak.devservices.keycloak-x-image`. */ @ConfigItem(defaultValue = "quay.io/keycloak/keycloak:23.0.1") public String imageName; /** - * If Keycloak-X image is used. + * Optional. Indicates if a Keycloak-X image is used. * - * By default, Dev Services for Keycloak will assume a Keycloak-X image is used if the image name contains a 'keycloak-x' - * string. - * Set 'quarkus.keycloak.devservices.keycloak-x-image' to override this check which may be necessary if you build custom - * Keycloak-X or Keycloak images. + * By default, the image is identified by `keycloak-x` in the image name. + * For custom images, override with `quarkus.keycloak.devservices.keycloak-x-image`. * You do not need to set this property if the default check works. */ @ConfigItem public Optional keycloakXImage; /** - * Indicates if the Keycloak container managed by Quarkus Dev Services is shared. - * When shared, Quarkus looks for running containers using label-based service discovery. - * If a matching container is found, it is used, and so a second one is not started. - * Otherwise, Dev Services for Keycloak starts a new container. - *

- * The discovery uses the {@code quarkus-dev-service-label} label. - * The value is configured using the {@code service-name} property. - *

- * Container sharing is only used in dev mode. + * Determines if the Keycloak container is shared. + * + * When shared, Quarkus uses label-based service discovery to find and reuse a running Keycloak container, so a second one is not started. + * Otherwise, if a matching container is not is found, a new container is started. + * + * The service discovery uses the {@code quarkus-dev-service-label} label, whose value is set by the {@code service-name} property. + * + * Container sharing is available only in dev mode. */ @ConfigItem(defaultValue = "true") public boolean shared; @@ -69,23 +60,30 @@ public class DevServicesConfig { * This property is used when {@code shared} is set to {@code true}. * In this case, before starting a container, Dev Services for Keycloak looks for a container with the * {@code quarkus-dev-service-keycloak} label - * set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it + * set to the configured value. If found, it uses this container instead of starting a new one. Otherwise, it * starts a new container with the {@code quarkus-dev-service-keycloak} label set to the specified value. *

* Container sharing is only used in dev mode. */ + /** + * The value of the `quarkus-dev-service-keycloak` label for identifying the Keycloak container. + * + * Used in shared mode to locate an existing container with this label. If not found, a new container is initialized with this label. + * + * Applicable only in dev mode. + */ @ConfigItem(defaultValue = "quarkus") public String serviceName; /** - * The comma-separated list of class or file system paths to Keycloak realm files which will be used to initialize Keycloak. - * The first value in this list will be used to initialize default tenant connection properties. + * Optional. The comma-separated list of class or file system paths to Keycloak realm files are be used to initialize Keycloak. + * The first value in this list is used to initialize default tenant connection properties. */ @ConfigItem public Optional> realmPath; /** - * The JAVA_OPTS passed to the keycloak JVM + * Optional. The JAVA_OPTS passed to the keycloak JVM */ @ConfigItem public Optional javaOpts; @@ -97,80 +95,78 @@ public class DevServicesConfig { public boolean showLogs; /** - * Keycloak start command. + * Optional. Keycloak start command. * Use this property to experiment with Keycloak start options, see {@link https://www.keycloak.org/server/all-config}. - * Note it will be ignored when loading legacy Keycloak WildFly images. + * Note, it is ignored when loading legacy Keycloak WildFly images. */ @ConfigItem public Optional startCommand; /** - * 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 to determine the realm name. + * Optional. The name of the Keycloak realm. The default value is `quarkus`. * + * This property is used to create the realm when the realm file specified by the `realm-path` is not found. + * + * It's recommended to always set this property so that Dev Services for Keycloak can identify the realm name without parsing the realm file. */ @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 - * exist. - * - * Disable it if you'd like to create a realm using Keycloak Administration Console - * or Keycloak Admin API from {@linkplain io.quarkus.test.common.QuarkusTestResourceLifecycleManager}. - */ + /** + * Specifies whether to create the Keycloak realm when no realm file is found at the `realm-path`. + * + * Set to `false` if the realm is to be created using either the Keycloak Administration Console or + * the Keycloak Admin API provided by {@linkplain io.quarkus.test.common.QuarkusTestResourceLifecycleManager}. + */ @ConfigItem(defaultValue = "true") public boolean createRealm; /** - * 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 - * not exist. + * A map of Keycloak usernames to passwords. + * + * If empty, default users `alice` and `bob` are created with their names as passwords. + * This map is used for user creation when no realm file is found at the `realm-path`. */ @ConfigItem public Map users; /** - * 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 - * not exist. + * Defines roles for Keycloak users. + * + * If this map is empty, default roles are assigned: `alice` receives `admin` and `user` roles, while other users receive `user` role. + * This configuration is used for role creation when no realm file is found at the `realm-path`. */ @ConfigItem public Map> roles; /** - * Grant type. + * Specifies the grant type. * - * @deprecated Use {@link DevUiConfig#grant}. + * @deprecated This field is deprecated. Use {@link DevUiConfig#grant} instead. */ @Deprecated public Grant grant = new Grant(); + @ConfigGroup public static class Grant { public static enum Type { /** - * 'client_credentials' grant + * `client_credentials` grant */ CLIENT("client_credentials"), /** - * 'password' grant + * `password` grant */ PASSWORD("password"), /** - * 'authorization_code' grant + * `authorization_code` grant */ CODE("code"), /** - * 'implicit' grant + * `implicit` grant */ IMPLICIT("implicit"); @@ -186,22 +182,22 @@ public String getGrantType() { } /** - * Grant type which will be used to acquire a token to test the OIDC 'service' applications + * Defines the grant type for aquiring tokens for testing OIDC `service` applications. */ @ConfigItem(defaultValue = "code") public Type type = Type.CODE; } /** - * Optional fixed port the dev service will listen to. + * Optional. The specific port for the dev service to listen on. *

- * If not defined, the port will be chosen randomly. + * If not specified, a random port is selected. */ @ConfigItem public OptionalInt port; /** - * Environment variables that are passed to the container. + * Environment variables to be passed to the container. */ @ConfigItem public Map containerEnv; 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 8c178262454bc..805485c13db39 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 @@ -23,8 +23,8 @@ public class OidcTenantConfig extends OidcCommonConfig { /** - * A unique tenant identifier. It must be set by {@code TenantConfigResolver} providers which - * resolve the tenant configuration dynamically and is optional in all other cases. + * Optional. A unique tenant identifier. It can be set by {@code TenantConfigResolver} providers, which + * resolve the tenant configuration dynamically. */ @ConfigItem public Optional tenantId = Optional.empty(); @@ -32,66 +32,66 @@ public class OidcTenantConfig extends OidcCommonConfig { /** * If this tenant configuration is enabled. * - * Note that the default tenant will be disabled if it is not configured but either - * {@link TenantConfigResolver} which will resolve tenant configurations is registered + * The default tenant is disabled if it is not configured but + * a {@link TenantConfigResolver} that resolves tenant configurations is registered, * or named tenants are configured. - * You do not have to disable the default tenant in this case. + * In this case, you do not need to disable the default tenant. */ @ConfigItem(defaultValue = "true") public boolean tenantEnabled = true; /** - * The application type, which can be one of the following {@link ApplicationType} values. + * Optional. The application type, which can be one of the following {@link ApplicationType} values. */ @ConfigItem(defaultValueDocumentation = "service") public Optional applicationType = Optional.empty(); /** - * Relative path or absolute URL of the OIDC authorization endpoint which authenticates the users. - * This property must be set for the 'web-app' applications if OIDC discovery is disabled. - * This property will be ignored if the discovery is enabled. + * Optional. The relative path or absolute URL of the OpenID Connect (OIDC) authorization endpoint, which authenticates users. + * You must set this property for `web-app` applications if OIDC discovery is disabled. + * This property is ignored if OIDC discovery is enabled. */ @ConfigItem public Optional authorizationPath = Optional.empty(); /** - * 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. - * This property will be ignored if the discovery is enabled. + * Optional. The relative path or absolute URL of the OIDC UserInfo endpoint. + * You must set this property for `web-app` applications if OIDC discovery is disabled + * and the `authentication.user-info-required` property is enabled. + * This property is ignored if OIDC discovery is enabled. */ @ConfigItem public Optional userInfoPath = Optional.empty(); /** - * Relative path or absolute URL of the OIDC RFC7662 introspection endpoint which can introspect both opaque and JWT tokens. - * This property must be set if OIDC discovery is disabled and 1) the opaque bearer access tokens have to be verified - * or 2) JWT tokens have to be verified while the cached JWK verification set with no matching JWK is being refreshed. - * This property will be ignored if the discovery is enabled. + * Optional. Relative path or absolute URL of the OIDC RFC7662 introspection endpoint which can introspect both opaque and JSON Web Token (JWT) tokens. + * This property must be set if OIDC discovery is disabled and 1) the opaque bearer access tokens must be verified + * or 2) JWT tokens must be verified while the cached JWK verification set with no matching JWK is being refreshed. + * This property is ignored if the discovery is enabled. */ @ConfigItem public Optional introspectionPath = Optional.empty(); /** - * Relative path or absolute URL of the OIDC JWKS endpoint which returns a JSON Web Key Verification Set. + * Optional. Relative path or absolute URL of the OIDC JSON Web Key Set (JWKS) endpoint which returns a JSON Web Key Verification Set. * This property should be set if OIDC discovery is disabled and the local JWT verification is required. - * This property will be ignored if the discovery is enabled. + * This property is ignored if the discovery is enabled. */ @ConfigItem public Optional jwksPath = Optional.empty(); /** - * Relative path or absolute URL of the OIDC end_session_endpoint. - * This property must be set if OIDC discovery is disabled and RP Initiated Logout support for the 'web-app' applications is + * Optional. Relative path or absolute URL of the OIDC end_session_endpoint. + * This property must be set if OIDC discovery is disabled and RP Initiated Logout support for the `web-app` applications is * required. - * This property will be ignored if the discovery is enabled. + * This property is ignored if the discovery is enabled. */ @ConfigItem public Optional endSessionPath = Optional.empty(); /** - * Public key for the local JWT token verification. - * OIDC server connection will not be created when this property is set. + * Optional. The public key for the local JWT token verification. + * OIDC server connection is not created when this property is set. */ @ConfigItem public Optional publicKey = Optional.empty(); @@ -110,19 +110,19 @@ public class OidcTenantConfig extends OidcCommonConfig { @ConfigGroup public static class IntrospectionCredentials { /** - * Name + * Optional. Name */ @ConfigItem public Optional name = Optional.empty(); /** - * Secret + * Optional. Secret */ @ConfigItem public Optional secret = Optional.empty(); /** - * Include OpenId Connect Client ID configured with 'quarkus.oidc.client-id' + * Include OpenId Connect Client ID configured with `quarkus.oidc.client-id`. */ @ConfigItem(defaultValue = "true") public boolean includeClientId = true; @@ -173,7 +173,7 @@ public void setIncludeClientId(boolean includeClientId) { /** * Configuration of the certificate chain which can be used to verify tokens. - * If the certificate chain trusstore is configured then the tokens can be verified using the certificate + * If the certificate chain trusstore is configured, the tokens can be verified using the certificate * chain inlined in the Base64-encoded format as an `x5c` header in the token itself. */ @ConfigItem @@ -182,7 +182,7 @@ public void setIncludeClientId(boolean includeClientId) { @ConfigGroup public static class CertificateChain { /** - * Truststore file which keeps thumbprints of the trusted certificates + * Optional. Truststore file which keeps thumbprints of the trusted certificates. */ @ConfigItem public Optional trustStoreFile = Optional.empty(); @@ -194,13 +194,13 @@ public static class CertificateChain { public Optional trustStorePassword; /** - * A parameter to specify the alias of the truststore certificate. + * Optional. A parameter to specify the alias of the truststore certificate. */ @ConfigItem public Optional trustStoreCertAlias = Optional.empty(); /** - * An optional parameter to specify type of the truststore file. If not given, the type is automatically detected + * Optional. An optional parameter to specify type of the truststore file. If not given, the type is automatically detected * based on the file name. */ @ConfigItem @@ -278,14 +278,14 @@ public void setTrustStoreFileType(Optional trustStoreFileType) { public static class Logout { /** - * The relative path of the logout endpoint at the application. If provided, the application is able to initiate the + * Optional. The relative path of the logout endpoint at the application. If provided, the application is able to initiate the * logout through this endpoint in conformance with the OpenID Connect RP-Initiated Logout specification. */ @ConfigItem public Optional path = Optional.empty(); /** - * Relative path of the application endpoint where the user should be redirected to after logging out from the OpenID + * Optional. Relative path of the application endpoint where the user should be redirected to after logging out from the OpenID * Connect Provider. * This endpoint URI must be properly registered at the OpenID Connect Provider as a valid redirect URI. */ @@ -293,13 +293,13 @@ public static class Logout { public Optional postLogoutPath = Optional.empty(); /** - * Name of the post logout URI parameter which will be added as a query parameter to the logout redirect URI. + * Name of the post logout URI parameter which is added as a query parameter to the logout redirect URI. */ @ConfigItem(defaultValue = OidcConstants.POST_LOGOUT_REDIRECT_URI) public String postLogoutUriParam; /** - * Additional properties which will be added as the query parameters to the logout redirect URI. + * Additional properties which is added as the query parameters to the logout redirect URI. */ @ConfigItem public Map extraParams; @@ -368,7 +368,7 @@ public void setFrontchannel(Frontchannel frontchannel) { @ConfigGroup public static class Backchannel { /** - * The relative path of the Back-Channel Logout endpoint at the application. + * Optional. The relative path of the Back-Channel Logout endpoint at the application. */ @ConfigItem public Optional path = Optional.empty(); @@ -387,14 +387,14 @@ public static class Backchannel { public Duration tokenCacheTimeToLive = Duration.ofMinutes(10); /** - * Token cache timer interval. - * If this property is set then a timer will check and remove the stale entries periodically. + * Optional. Token cache timer interval. + * If this property is set, a timer checks and removes the stale entries periodically. */ @ConfigItem public Optional cleanUpTimerInterval = Optional.empty(); /** - * Logout token claim whose value will be used as a key for caching the tokens. + * Logout token claim whose value is used as a key for caching the tokens. * Only `sub` (subject) and `sid` (session id) claims can be used as keys. * Set it to `sid` only if ID tokens issued by the OIDC provider have no `sub` but have `sid` claim. */ @@ -455,7 +455,7 @@ public static class Jwks { * If JWK verification keys should be fetched at the moment a connection to the OIDC provider * is initialized. *

- * Disabling this property will delay the key acquisition until the moment the current token + * Disabling this property delays the key acquisition until the moment the current token * has to be verified. Typically it can only be necessary if the token or other telated request properties * provide an additional context which is required to resolve the keys correctly. */ @@ -464,22 +464,22 @@ public static class Jwks { /** * Maximum number of JWK keys that can be cached. - * This property will be ignored if the {@link #resolveEarly} property is set to true. + * This property is ignored if the {@link #resolveEarly} property is set to true. */ @ConfigItem(defaultValue = "10") public int cacheSize = 10; /** * Number of minutes a JWK key can be cached for. - * This property will be ignored if the {@link #resolveEarly} property is set to true. + * This property is ignored if the {@link #resolveEarly} property is set to true. */ @ConfigItem(defaultValue = "10M") public Duration cacheTimeToLive = Duration.ofMinutes(10); /** - * Cache timer interval. - * If this property is set then a timer will check and remove the stale entries periodically. - * This property will be ignored if the {@link #resolveEarly} property is set to true. + * Optional. Cache timer interval. + * If this property is set, a timer checks and removes the stale entries periodically. + * This property is ignored if the {@link #resolveEarly} property is set to true. */ @ConfigItem public Optional cleanUpTimerInterval = Optional.empty(); @@ -520,7 +520,7 @@ public void setResolveEarly(boolean resolveEarly) { @ConfigGroup public static class Frontchannel { /** - * The relative path of the Front-Channel Logout endpoint at the application. + * Optional. The relative path of the Front-Channel Logout endpoint at the application. */ @ConfigItem public Optional path = Optional.empty(); @@ -573,23 +573,23 @@ public enum Strategy { public boolean splitTokens; /** - * Mandates that the Default TokenStateManager will encrypt the session cookie that stores the tokens. + * Mandates that the Default TokenStateManager encrypt the session cookie that stores the tokens. */ @ConfigItem(defaultValue = "true") public boolean encryptionRequired = true; /** - * Secret which will be used by the Default TokenStateManager to encrypt the session cookie + * Optional. The secret used by the Default TokenStateManager to encrypt the session cookie * storing the tokens when {@link #encryptionRequired} property is enabled. *

* If this secret is not set, the client secret configured with - * either `quarkus.oidc.credentials.secret` or `quarkus.oidc.credentials.client-secret.value` will be checked. - * Finally, `quarkus.oidc.credentials.jwt.secret` which can be used for `client_jwt_secret` authentication will be + * either `quarkus.oidc.credentials.secret` or `quarkus.oidc.credentials.client-secret.value` is checked. + * Finally, `quarkus.oidc.credentials.jwt.secret` which can be used for `client_jwt_secret` authentication is * checked. - * The secret will be auto-generated if it remains uninitialized after checking all of these properties. + * The secret is auto-generated if it remains uninitialized after checking all of these properties. *

- * The length of the secret which will be used to encrypt the tokens should be at least 32 characters long. - * Warning will be logged if the secret length is less than 16 characters. + * The length of the secret used to encrypt the tokens should be at least 32 characters long. + * A warning is logged if the secret length is less than 16 characters. */ @ConfigItem public Optional encryptionSecret = Optional.empty(); @@ -738,24 +738,25 @@ public static Roles fromClaimPathAndSeparator(List path, String sep) { } /** - * List of paths to claims containing an array of groups. Each path starts from the top level JWT JSON object - * and can contain multiple segments where each segment represents a JSON object name only, - * example: "realm/groups". Use double quotes with the namespace qualified claim names. - * This property can be used if a token has no 'groups' claim but has the groups set in one or more different - * claims. + * Optional. A list of paths to claims containing an array of groups. + * Each path starts from the top level JWT JSON object + * and can contain multiple segments. + * Each segment represents a JSON object name only; for example: "realm/groups". + * Use double quotes with the namespace-qualified claim names. + * This property can be used if a token has no `groups` claim but has the groups set in one or more different claims. */ @ConfigItem public Optional> roleClaimPath = Optional.empty(); /** - * Separator for splitting a string which may contain multiple group values. - * It will only be used if the "role-claim-path" property points to one or more custom claims whose values are strings. - * A single space will be used by default because the standard 'scope' claim may contain a space separated sequence. + * Optional. The separator for splitting strings that contain multiple group values. + * It is only used if the "role-claim-path" property points to one or more custom claims whose values are strings. + * A single space is used by default because the standard `scope` claim can contain a space-separated sequence. */ @ConfigItem public Optional roleClaimSeparator = Optional.empty(); /** - * Source of the principal roles. + * Optional. Source of the principal roles. */ @ConfigItem public Optional source = Optional.empty(); @@ -787,13 +788,13 @@ public void setSource(Source source) { // Source of the principal roles public static enum Source { /** - * ID Token - the default value for the 'web-app' applications. + * ID Token - the default value for the `web-app` applications. */ idtoken, /** - * Access Token - the default value for the 'service' applications; - * can also be used as the source of roles for the 'web-app' applications. + * Access Token - the default value for the `service` applications; + * can also be used as the source of roles for the `web-app` applications. */ accesstoken, @@ -831,59 +832,59 @@ public enum ResponseMode { /** * Authorization response parameters are encoded as HTML form values that are auto-submitted in the browser - * and transmitted via the HTTP POST method using the application/x-www-form-urlencoded content type + * and transmitted by the HTTP POST method using the application/x-www-form-urlencoded content type */ FORM_POST } /** - * Authorization code flow response mode + * Optional. Authorization code flow response mode. */ @ConfigItem(defaultValueDocumentation = "query") public Optional responseMode = Optional.empty(); /** - * 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 - * will be set to 'https://localhost:8080/' if this property is set to '/' and be the same as the request URI + * Optional. The relative path for calculating a `redirect_uri` query parameter. + * It has to start from a forward slash and is appended to the request URI's host and port. + * For example, if the current request URI is `https://localhost:8080/service`, a `redirect_uri` parameter + * is 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 + * Note the original request URI is restored after the user has authenticated if `restorePathAfterRedirect` is set * to `true`. */ @ConfigItem public Optional redirectPath = Optional.empty(); /** - * 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. + * If this property is set to `true`, the original request URI which was used before + * the authentication is 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 + * Note if `redirectPath` property is not set, the original request URI is restored even if this property is * disabled. */ @ConfigItem(defaultValue = "false") public boolean restorePathAfterRedirect; /** - * Remove the query parameters such as 'code' and 'state' set by the OIDC server on the redirect URI + * Remove the query parameters such as `code` and `state` set by the OIDC server on the redirect URI * after the user has authenticated by redirecting a user to the same URI but without the query parameters. */ @ConfigItem(defaultValue = "true") public boolean removeRedirectParameters = true; /** - * 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 + * Optional. Relative path to the public endpoint which processes the error response from the OIDC authorization endpoint. + * If the user authentication has failed, the OIDC provider returns an `error` and an optional * `error_description` - * parameters, instead of the expected authorization 'code'. + * 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 - * error description page. It has to start from a forward slash and will be appended to the request URI's host and port. - * For example, if it is set as '/error' and the current request URI is - * 'https://localhost:8080/callback?error=invalid_scope' - * then a redirect will be made to 'https://localhost:8080/error?error=invalid_scope'. + * If this property is set, the user is redirected to the endpoint which can return a user-friendly + * error description page. It has to start from a forward slash and is appended to the request URI's host and port. + * For example, if it is set as `/error` and the current request URI is + * `https://localhost:8080/callback?error=invalid_scope`, + * a redirect is made to `https://localhost:8080/error?error=invalid_scope`. * - * If this property is not set then HTTP 401 status will be returned in case of the user authentication failure. + * If this property is not set, HTTP 401 status is returned in case of the user authentication failure. */ @ConfigItem public Optional errorPath = Optional.empty(); @@ -895,8 +896,8 @@ public enum ResponseMode { * Access token is not verified by default since it is meant to be propagated to the downstream services. * The verification of the access token should be enabled if it is injected as a JWT token. * - * Access tokens obtained as part of the code flow will always be verified if `quarkus.oidc.roles.source` - * property is set to `accesstoken` which means the authorization decision will be based on the roles extracted from the + * Access tokens obtained as part of the code flow are always verified if `quarkus.oidc.roles.source` + * property is set to `accesstoken` which means the authorization decision is based on the roles extracted from the * access token. * * Bearer access tokens are always verified. @@ -905,14 +906,14 @@ public enum ResponseMode { public boolean verifyAccessToken; /** - * 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. + * Optional. Force `https` as the `redirect_uri` parameter scheme when running behind an SSL/TLS terminating reverse proxy. + * This property, if enabled, also affects the logout `post_logout_redirect_uri` and the local redirect requests. */ @ConfigItem(defaultValueDocumentation = "false") public Optional forceRedirectHttpsScheme = Optional.empty(); /** - * List of scopes + * Optional. List of scopes */ @ConfigItem public Optional> scopes = Optional.empty(); @@ -927,35 +928,35 @@ public enum ResponseMode { public boolean nonceRequired = false; /** - * 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. + * Optional. Add the `openid` scope automatically to the list of scopes. This is required for OpenId Connect providers, + * but does not work for OAuth2 providers such as Twitter OAuth2, which do not accept this scope and throw errors. */ @ConfigItem(defaultValueDocumentation = "true") public Optional addOpenidScope = Optional.empty(); /** - * Additional properties which will be added as the query parameters to the authentication redirect URI. + * Additional properties added as query parameters to the authentication redirect URI. */ @ConfigItem public Map extraParams = new HashMap<>(); /** - * Request URL query parameters which, if present, will be added to the authentication redirect URI. + * Optional. Request URL query parameters which, if present, are added to the authentication redirect URI. */ @ConfigItem @ConvertWith(TrimmedStringConverter.class) 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/TLS terminating reverse proxy. - * The cookies will always be secure if HTTPS is used even if this property is set to false. + * If enabled the state, session, and post logout cookies have their `secure` parameter set to `true` + * when HTTP is used. It might be necessary when running behind an SSL/TLS terminating reverse proxy. + * The cookies are always secure if HTTPS is used, even if this property is set to false. */ @ConfigItem(defaultValue = "false") public boolean cookieForceSecure; /** - * Cookie name suffix. + * Optional. 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`. */ @@ -963,23 +964,23 @@ public enum ResponseMode { public Optional cookieSuffix = Optional.empty(); /** - * Cookie path parameter value which, if set, will be used to set a path parameter for the session, state and post + * Cookie path parameter value which, if set, is used to set a path parameter for the session, state and post * logout cookies. - * The `cookie-path-header` property, if set, will be checked first. + * The `cookie-path-header` property, if set, is checked first. */ @ConfigItem(defaultValue = "/") public String cookiePath = "/"; /** - * Cookie path header parameter value which, if set, identifies the incoming HTTP header - * whose value will be used to set a path parameter for the session, state and post logout cookies. - * If the header is missing then the `cookie-path` property will be checked. + * Optional. Cookie path header parameter value which, if set, identifies the incoming HTTP header + * whose value is used to set a path parameter for the session, state and post logout cookies. + * If the header is missing, the `cookie-path` property is checked. */ @ConfigItem public Optional cookiePathHeader = Optional.empty(); /** - * Cookie domain parameter value which, if set, will be used for the session, state and post logout cookies. + * Optional. Cookie domain parameter value which, if set, is used for the session, state and post logout cookies. */ @ConfigItem public Optional cookieDomain = Optional.empty(); @@ -991,11 +992,11 @@ public enum ResponseMode { public CookieSameSite cookieSameSite = CookieSameSite.LAX; /** - * If a state cookie is present then a `state` query parameter must also be present and both the state - * cookie name suffix and state cookie value have to match the value of the `state` query parameter when + * If a state cookie is present, a `state` query parameter must also be present and both the state + * cookie name suffix and state cookie value must match the value of the `state` query parameter when * the redirect path matches the current path. * 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 + * browser tabs, then the currently available state cookie might represent the authentication flow * initiated from another tab and not related to the current request. * Disable this property to permit only a single authorization code flow in the same browser. * @@ -1010,29 +1011,29 @@ public enum ResponseMode { * matches the original request URL, the stale state cookie might remain in the browser cache from * the earlier failed redirect to an OpenId Connect provider and be visible during the current request. * For example, if Single-page application (SPA) uses XHR to handle redirects to the provider - * which does not support CORS for its authorization endpoint, the browser will block it - * and the state cookie created by Quarkus will remain in the browser cache. - * Quarkus will report an authentication failure when it will detect such an old state cookie but find no matching state + * which does not support CORS for its authorization endpoint, the browser blocks it + * and the state cookie created by Quarkus remains in the browser cache. + * Quarkus reports an authentication failure when it detects such an old state cookie but find no matching state * query parameter. *

- * Reporting HTTP 401 error is usually the right thing to do in such cases, it will minimize a risk of the + * Reporting HTTP 401 error is usually the right thing to do in such cases, it minimizes a risk of the * browser redirect loop but also can identify problems in the way SPA or Quarkus application manage redirects. * For example, enabling {@link #javaScriptAutoRedirect} or having the provider redirect to URL configured - * with {@link #redirectPath} may be needed to avoid such errors. + * with {@link #redirectPath} might 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. Doing so may increase the + * However, setting this property to `false` might help if the above options are not suitable. + * It causes a new authentication redirect to OpenId Connect provider. Doing so might 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. - * This property will be enabled if `quarkus.oidc.roles.source` is `userinfo` + * Optional. If this property is set to `true`, an OIDC UserInfo endpoint is called. + * This property is 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`, - * you do not have to enable this property manually in these cases. + * you do not need to enable this property manually in these cases. */ @ConfigItem(defaultValueDocumentation = "false") public Optional userInfoRequired = Optional.empty(); @@ -1040,24 +1041,24 @@ 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 + * the user is redirected to the OIDC provider to re-authenticate once the session has expired. + * If this property is set to a nonzero 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. + * This property is ignored if the `token.refresh-expired` property has not been enabled. */ @ConfigItem(defaultValue = "5M") public Duration sessionAgeExtension = Duration.ofMinutes(5); /** - * 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 + * If this property is set to `true`, a normal 302 redirect response is returned + * if the request was initiated by a JavaScript API such as XMLHttpRequest or Fetch and the current user needs to be + * (re)authenticated, which might not be desirable for Single-page applications (SPA) since + * it automatically following the redirect might not work given that OIDC authorization endpoints typically do not support * CORS. *

- * If this property is set to 'false' then a status code of '499' will be returned to allow + * If this property is set to `false`, a status code of `499` is returned to allow * SPA to handle the redirect manually if a request header identifying current request as a JavaScript request is found. - * 'X-Requested-With' request header with its value set to either `JavaScript` or `XMLHttpRequest` is expected by + * `X-Requested-With` request header with its value set to either `JavaScript` or `XMLHttpRequest` is expected by * default if * this property is enabled. You can register a custom {@linkplain JavaScriptRequestChecker} to do a custom JavaScript * request check instead. @@ -1066,50 +1067,51 @@ public enum ResponseMode { public boolean javaScriptAutoRedirect = true; /** - * Requires that ID token is available when the authorization code flow completes. + * Optional. Requires that ID token is available when the authorization code flow completes. * Disable this property only when you need to use the authorization code flow with OAuth2 providers which do not return - * ID token - an internal IdToken will be generated in such cases. + * ID token - an internal IdToken is generated in such cases. */ @ConfigItem(defaultValueDocumentation = "true") public Optional idTokenRequired = Optional.empty(); /** - * Internal ID token lifespan. + * Optional. Internal ID token lifespan. * This property is only checked when an internal IdToken is generated when Oauth2 providers do not return IdToken. */ @ConfigItem(defaultValueDocumentation = "5M") public Optional internalIdTokenLifespan = Optional.empty(); /** - * Requires that a Proof Key for Code Exchange (PKCE) is used. + * Optional. Requires that a Proof Key for Code Exchange (PKCE) is used. */ @ConfigItem(defaultValueDocumentation = "false") public Optional pkceRequired = Optional.empty(); /** - * Secret which will be used to encrypt a Proof Key for Code Exchange (PKCE) code verifier in the code flow state. + * Optional. Secret used to encrypt a Proof Key for Code Exchange (PKCE) code verifier in the code flow state. * This secret should be at least 32 characters long. * - * @deprecated Use {@link #stateSecret} property instead. + * @deprecated This field is deprecated. Use {@link #stateSecret} instead. + * */ @ConfigItem @Deprecated(forRemoval = true) public Optional pkceSecret = Optional.empty(); /** - * Secret which will be used to encrypt Proof Key for Code Exchange (PKCE) code verifier and/or nonce in the code flow + * Optional. Secret used to encrypt Proof Key for Code Exchange (PKCE) code verifier and/or nonce in the code flow * state. * This secret should be at least 32 characters long. *

* If this secret is not set, the client secret configured with - * either `quarkus.oidc.credentials.secret` or `quarkus.oidc.credentials.client-secret.value` will be checked. - * Finally, `quarkus.oidc.credentials.jwt.secret` which can be used for `client_jwt_secret` authentication will be - * checked. Client secret will not be used as a state encryption secret if it is less than 32 characters + * either `quarkus.oidc.credentials.secret` or `quarkus.oidc.credentials.client-secret.value` is checked. + * Finally, `quarkus.oidc.credentials.jwt.secret` which can be used for `client_jwt_secret` authentication is + * checked. A client secret is not be used as a state encryption secret if it is less than 32 characters * long. *

- * The secret will be auto-generated if it remains uninitialized after checking all of these properties. + * The secret is auto-generated if it remains uninitialized after checking all of these properties. *

- * Error will be reported if the secret length is less than 16 characters. + * Error is reported if the secret length is less than 16 characters. */ @ConfigItem public Optional stateSecret = Optional.empty(); @@ -1341,13 +1343,13 @@ public static class CodeGrant { /** * Additional parameters, in addition to the required `code` and `redirect-uri` parameters, - * which have to be included to complete the authorization code grant request. + * which must be included to complete the authorization code grant request. */ @ConfigItem public Map extraParams = new HashMap<>(); /** - * Custom HTTP headers which have to be sent to complete the authorization code grant request. + * Custom HTTP headers which must be sent to complete the authorization code grant request. */ @ConfigItem public Map headers = new HashMap<>(); @@ -1411,11 +1413,11 @@ public static Token fromAudience(String... audience) { } /** - * Expected issuer `iss` claim value. - * Note this property overrides the `issuer` property which may be set in OpenId Connect provider's well-known + * Optional. The expected issuer `iss` claim value. + * This property overrides the `issuer` property, which might 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 - * issuer verification by setting this property to 'any' but it should be done only when other options (such as + * If the `iss` claim value varies depending on the host, IP address, or tenant id of the provider, you can skip the + * issuer verification by setting this property to `any`, but it should be done only when other options (such as * configuring * the provider to use the fixed `iss` claim value) are not possible. */ @@ -1423,15 +1425,15 @@ public static Token fromAudience(String... audience) { public Optional issuer = Optional.empty(); /** - * Expected audience 'aud' claim value which may be a string or an array of strings. + * Optional. The expected audience `aud` claim value, which can be a string or an array of strings. * - * Note the audience claim will be verified for ID tokens by default. + * Note the audience claim is verified for ID tokens by default. * ID token audience must be equal to the value of `quarkus.oidc.client-id` property. * Use this property to override the expected value if your OpenID Connect provider * sets a different audience claim value in ID tokens. Set it to `any` if your provider * does not set ID token audience` claim. * - * Audience verification for access tokens will only be done if this property is configured. + * Audience verification for access tokens is only done if this property is configured. */ @ConfigItem public Optional> audience = Optional.empty(); @@ -1439,7 +1441,7 @@ public static Token fromAudience(String... audience) { /** * Require that the token includes a `sub` (subject) claim which is a unique * and never reassigned identifier for the current user. - * Note that if you enable this property and if UserInfo is also required then + * Note that if you enable this property and if UserInfo is also required, * both the token and UserInfo `sub` claims must be present and match each other. */ @ConfigItem(defaultValue = "false") @@ -1457,7 +1459,7 @@ public static Token fromAudience(String... audience) { public Map requiredClaims = new HashMap<>(); /** - * Expected token type + * Optional. Expected token type */ @ConfigItem public Optional tokenType = Optional.empty(); @@ -1473,25 +1475,25 @@ public static Token fromAudience(String... audience) { public OptionalInt lifespanGrace = OptionalInt.empty(); /** - * Token age. + * Optional. Token age. * * It allows for the number of seconds to be specified that must not elapse since the `iat` (issued at) time. - * A small leeway to account for clock skew which can be configured with 'quarkus.oidc.token.lifespan-grace' to verify + * A small leeway to account for clock skew which can be configured with `quarkus.oidc.token.lifespan-grace` to verify * the token expiry time * can also be used to verify the token age property. * * Note that setting this property does not relax the requirement that Bearer and Code Flow JWT tokens - * must have a valid ('exp') expiry claim value. The only exception where setting this property relaxes the requirement + * must have a valid (`exp`) expiry claim value. The only exception where setting this property relaxes the requirement * is when a logout token is sent with a back-channel logout request since the current - * OpenId Connect Back-Channel specification does not explicitly require the logout tokens to contain an 'exp' claim. - * However, even if the current logout token is allowed to have no 'exp' claim, the `exp` claim will be still verified + * OpenId Connect Back-Channel specification does not explicitly require the logout tokens to contain an `exp` claim. + * However, even if the current logout token is allowed to have no `exp` claim, the `exp` claim is still verified * if the logout token contains it. */ @ConfigItem public Optional age = Optional.empty(); /** - * Name of the claim which contains a principal name. By default, the `upn`, `preferred_username` and `sub` claims are + * Optional. Name of the claim which contains a principal name. By default, the `upn`, `preferred_username` and `sub` claims are * checked. */ @ConfigItem @@ -1499,40 +1501,40 @@ public static Token fromAudience(String... audience) { /** * Refresh expired authorization code flow ID or access tokens. - * If this property is enabled then a refresh token request will be performed if the authorization code - * ID or access token has expired and, if successful, the local session will be updated with the new set of tokens. - * Otherwise, the local session will be invalidated and the user redirected to the OpenID Provider to re-authenticate. - * In this case the user may not be challenged again if the OIDC provider session is still active. + * If this property is enabled, a refresh token request is performed if the authorization code + * ID or access token has expired and, if successful, the local session is updated with the new set of tokens. + * Otherwise, the local session is invalidated and the user redirected to the OpenID Provider to re-authenticate. + * In this case, the user might not be challenged again if the OIDC provider session is still active. * - * For this option be effective the `authentication.session-age-extension` property should also be set to a non-zero + * For this option be effective the `authentication.session-age-extension` property should also be set to a nonzero * value since the refresh token is currently kept in the user session. * * This option is valid only when the application is of type {@link ApplicationType#WEB_APP}}. * - * This property will be enabled if `quarkus.oidc.token.refresh-token-time-skew` is configured, - * you do not have to enable this property manually in this case. + * This property is enabled if `quarkus.oidc.token.refresh-token-time-skew` is configured, + * you do not need to enable this property manually in this case. */ @ConfigItem public boolean refreshExpired; /** - * Refresh token time skew in seconds. - * If this property is enabled then the configured number of seconds is added to the current time + * Optional. The refresh token time skew, in seconds. + * If this property is enabled, the configured number of seconds is added to the current time * when checking if the authorization code ID or access token should be refreshed. - * If the sum is greater than the authorization code ID or access token's expiration time then a refresh is going to + * If the sum is greater than the authorization code ID or access token's expiration time, a refresh is going to * happen. */ @ConfigItem public Optional refreshTokenTimeSkew = Optional.empty(); /** - * Forced JWK set refresh interval in minutes. + * The forced JWK set refresh interval in minutes. */ @ConfigItem(defaultValue = "10M") public Duration forcedJwkRefreshInterval = Duration.ofMinutes(10); /** - * Custom HTTP header that contains a bearer token. + * Optional. Custom HTTP header that contains a bearer token. * This option is valid only when the application is of type {@link ApplicationType#SERVICE}}. */ @ConfigItem @@ -1545,7 +1547,7 @@ public static Token fromAudience(String... audience) { public String authorizationScheme = OidcConstants.BEARER_SCHEME; /** - * Required signature algorithm. + * Optional. Required signature algorithm. * OIDC providers support many signature algorithms but if necessary you can restrict * Quarkus application to accept tokens signed only using an algorithm configured with this property. */ @@ -1553,15 +1555,14 @@ public static Token fromAudience(String... audience) { public Optional signatureAlgorithm = Optional.empty(); /** - * Decryption key location. + * Optional. Decryption key location. * JWT tokens can be inner-signed and encrypted by OpenId Connect providers. * However, it is not always possible to remotely introspect such tokens because - * the providers may not control the private decryption keys. + * the providers might 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 - * 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. + * If this property is not set and the `private_key_jwt` client authentication method is used, the private key + * used to sign the client authentication JWT tokens are also used to decrypt the encrypted ID tokens. */ @ConfigItem public Optional decryptionKeyLocation = Optional.empty(); @@ -1569,10 +1570,9 @@ 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` - * instead in one of the next releases. + * This property is set to `true` by default for backward-compatibility reasons. It is planned that this default value will be changed to `false` in an upcoming release. * - * Also note this property will be ignored if JWK endpoint URI is not available and introspecting the tokens is + * Also note this property is ignored if JWK endpoint URI is not available and introspecting the tokens is * the only verification option. */ @ConfigItem(defaultValue = "true") @@ -1588,13 +1588,13 @@ public static Token fromAudience(String... audience) { /** * Allow the remote introspection of the opaque tokens. * - * Set this property to 'false' if only JWT tokens are expected. + * Set this property to `false` if only JWT tokens are expected. */ @ConfigItem(defaultValue = "true") public boolean allowOpaqueTokenIntrospection = true; /** - * Token customizer name. + * Optional. Token customizer name. * * Allows to select a tenant specific token customizer as a named bean. * Prefer using {@link TenantFeature} qualifier when registering custom {@link TokenCustomizer}. @@ -1604,11 +1604,11 @@ public static Token fromAudience(String... audience) { public Optional customizerName = Optional.empty(); /** - * Indirectly verify that the opaque (binary) access token is valid by using it to request UserInfo. + * Optional. Indirectly verify that the opaque (binary) access token is valid by using it to request UserInfo. * Opaque access token is considered valid if the provider accepted this token and returned a valid UserInfo. - * You should only enable this option if the opaque access tokens have to be accepted but OpenId Connect + * You should only enable this option if the opaque access tokens must be accepted but OpenId Connect * provider does not have a token introspection endpoint. - * This property will have no effect when JWT tokens have to be verified. + * This property has no effect when JWT tokens must be verified. */ @ConfigItem(defaultValueDocumentation = "false") public Optional verifyAccessTokenWithUserInfo = Optional.empty(); @@ -1790,14 +1790,14 @@ public static enum ApplicationType { /** * A combined {@code SERVICE} and {@code WEB_APP} client. - * For this type of client, the Bearer Authorization method will be used if the Authorization header is set + * For this type of client, the Bearer Authorization method is used if the Authorization header is set * and Authorization Code Flow - if not. */ HYBRID } /** - * Well known OpenId Connect provider identifier + * Optional. Well known OpenId Connect provider identifier */ @ConfigItem public Optional provider = Optional.empty();