From a25468991a0e65167c1fc46c5adbeab16c111757 Mon Sep 17 00:00:00 2001 From: Tomas Langer Date: Tue, 30 Jul 2024 01:47:01 +0200 Subject: [PATCH] Regenerated configuration metadata, and a reference fix. --- .../asciidoc/config/config_reference.adoc | 9 +- ...helidon_common_configurable_AllowList.adoc | 22 +- ..._helidon_common_configurable_LruCache.adoc | 2 +- ..._helidon_common_configurable_Resource.adoc | 24 +-- ...onfigurable_ScheduledThreadPoolConfig.adoc | 20 +- ...figurable_ScheduledThreadPoolSupplier.adoc | 20 +- ..._common_configurable_ThreadPoolConfig.adoc | 46 ++--- ...ommon_configurable_ThreadPoolSupplier.adoc | 46 ++--- .../config/io_helidon_common_pki_Keys.adoc | 12 +- .../io_helidon_common_pki_KeystoreKeys.adoc | 28 +-- .../config/io_helidon_common_pki_PemKeys.adoc | 12 +- ...o_helidon_common_socket_SocketOptions.adoc | 30 +-- ...o_helidon_common_tls_RevocationConfig.adoc | 38 ++-- .../config/io_helidon_common_tls_Tls.adoc | 75 ++++--- ...on_dbclient_jdbc_JdbcParametersConfig.adoc | 46 ++--- .../io_helidon_faulttolerance_Async.adoc | 4 +- .../io_helidon_faulttolerance_Bulkhead.adoc | 10 +- ...helidon_faulttolerance_CircuitBreaker.adoc | 22 +- .../io_helidon_faulttolerance_Retry.adoc | 20 +- .../io_helidon_faulttolerance_Timeout.adoc | 8 +- ...don_http_RequestedUriDiscoveryContext.adoc | 13 ++ ..._http_encoding_ContentEncodingContext.adoc | 4 +- .../io_helidon_http_media_MediaContext.adoc | 12 +- .../io_helidon_integrations_neo4j_Neo4j.adoc | 7 + ...tegrations_oci_ConfigFileMethodConfig.adoc | 4 +- ...n_integrations_oci_ConfigMethodConfig.adoc | 35 ++-- ...don_integrations_oci_ImdsInstanceInfo.adoc | 75 +++++++ ...io_helidon_integrations_oci_OciConfig.adoc | 68 ++++--- ...grations_oci_SessionTokenMethodConfig.adoc | 61 +++--- ...rations_oci_metrics_OciMetricsSupport.adoc | 20 +- ...ntegrations_oci_sdk_runtime_OciConfig.adoc | 181 +++++++++-------- ...ertificates_OciCertificatesTlsManager.adoc | 24 +-- ...don_integrations_openapi_ui_OpenApiUi.adoc | 6 +- ..._KeyPerformanceIndicatorMetricsConfig.adoc | 4 +- .../io_helidon_metrics_api_MetricsConfig.adoc | 20 +- .../io_helidon_metrics_api_ScopeConfig.adoc | 8 +- .../io_helidon_metrics_api_ScopingConfig.adoc | 8 +- .../config/io_helidon_microprofile_jwt.adoc | 90 --------- ...microprofile_jwt_auth_JwtAuthProvider.adoc | 90 +++++++++ ...rofile_openapi_MpOpenApiManagerConfig.adoc | 4 +- .../io_helidon_openapi_OpenApiFeature.adoc | 24 +-- .../config/io_helidon_scheduling_Cron.adoc | 6 +- .../io_helidon_scheduling_FixedRate.adoc | 34 ++-- .../config/io_helidon_security_Security.adoc | 26 ++- .../io_helidon_security_SecurityTime.adoc | 4 +- ...urity_providers_common_EvictableCache.adoc | 6 +- ...urity_providers_common_OutboundTarget.adoc | 22 +- ...ders_config_vault_ConfigVaultProvider.adoc | 64 ++++++ ...ult_ConfigVaultProvider_SecretConfig.adoc} | 21 +- ...ders_google_login_GoogleTokenProvider.adoc | 4 +- ...ty_providers_header_HeaderAtnProvider.adoc | 6 +- ...viders_httpauth_HttpBasicAuthProvider.adoc | 6 +- ...iders_httpauth_HttpDigestAuthProvider.adoc | 28 ++- ...y_providers_httpsign_HttpSignProvider.adoc | 130 ++++++------ ...ders_httpsign_InboundClientDefinition.adoc | 4 +- ..._idcs_mapper_IdcsMtRoleMapperProvider.adoc | 18 +- ...rs_idcs_mapper_IdcsRoleMapperProvider.adoc | 14 +- ...er_IdcsRoleMapperProviderBase_Builder.adoc | 14 +- ...on_security_providers_jwt_JwtProvider.adoc | 30 ++- ..._security_providers_oidc_OidcProvider.adoc | 189 +++++++++++------- ...ity_providers_oidc_common_BaseBuilder.adoc | 77 +++++-- ...rity_providers_oidc_common_OidcConfig.adoc | 183 ++++++++++------- ...ty_providers_oidc_common_TenantConfig.adoc | 77 +++++-- .../config/io_helidon_tracing_Tracer.adoc | 25 ++- ..._providers_jaeger_JaegerTracerBuilder.adoc | 25 ++- ..._providers_zipkin_ZipkinTracerBuilder.adoc | 8 +- ...elidon_webclient_api_HttpClientConfig.adoc | 90 ++++----- ..._helidon_webclient_api_HttpConfigBase.adoc | 32 +-- .../io_helidon_webclient_api_Proxy.adoc | 11 +- .../io_helidon_webclient_api_WebClient.adoc | 92 ++++----- ..._webclient_api_WebClientCookieManager.adoc | 6 +- .../io_helidon_webclient_grpc_GrpcClient.adoc | 2 +- ...bclient_grpc_GrpcClientProtocolConfig.adoc | 26 +-- ...lient_http1_Http1ClientProtocolConfig.adoc | 20 +- ...lient_http2_Http2ClientProtocolConfig.adoc | 58 +++--- ..._helidon_webclient_websocket_WsClient.adoc | 2 +- ...io_helidon_webserver_ConnectionConfig.adoc | 44 ++-- .../io_helidon_webserver_ListenerConfig.adoc | 124 ++++++------ .../io_helidon_webserver_WebServer.adoc | 136 +++++++------ ...n_webserver_accesslog_AccessLogConfig.adoc | 122 +++++------ ..._webserver_accesslog_AccessLogFeature.adoc | 122 +++++------ ...idon_webserver_context_ContextFeature.adoc | 6 +- .../io_helidon_webserver_cors_CorsConfig.adoc | 8 +- ...io_helidon_webserver_cors_CorsFeature.adoc | 8 +- ...don_webserver_grpc_GrpcTracingConfig.adoc} | 20 +- ...o_helidon_webserver_http1_Http1Config.adoc | 50 ++--- ...o_helidon_webserver_http2_Http2Config.adoc | 86 ++++---- ...idon_webserver_observe_ObserveFeature.adoc | 28 +-- ..._webserver_observe_ObserverConfigBase.adoc | 2 +- ...bserver_observe_config_ConfigObserver.adoc | 6 +- ...bserver_observe_health_HealthObserver.adoc | 20 +- ...n_webserver_observe_info_InfoObserver.adoc | 2 +- ...don_webserver_observe_log_LogObserver.adoc | 4 +- ...webserver_observe_log_LogStreamConfig.adoc | 14 +- ...erver_observe_metrics_MetricsObserver.adoc | 22 +- ...erver_observe_tracing_TracingObserver.adoc | 10 +- ...elidon_webserver_security_PathsConfig.adoc | 36 ++-- ...on_webserver_security_SecurityFeature.adoc | 18 +- ...on_webserver_security_SecurityHandler.adoc | 36 ++-- ..._helidon_webserver_websocket_WsConfig.adoc | 8 +- .../config/io_opentracing_Tracer.adoc | 8 +- docs/src/main/asciidoc/mp/jwt.adoc | 2 +- 102 files changed, 2010 insertions(+), 1544 deletions(-) create mode 100644 docs/src/main/asciidoc/config/io_helidon_integrations_oci_ImdsInstanceInfo.adoc delete mode 100644 docs/src/main/asciidoc/config/io_helidon_microprofile_jwt.adoc create mode 100644 docs/src/main/asciidoc/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc create mode 100644 docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc rename docs/src/main/asciidoc/config/{io_helidon_webserver_servicecommon_RestServiceSettings_Builder.adoc => io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc} (52%) rename docs/src/main/asciidoc/config/{io_helidon_metrics_api_ComponentMetricsSettings_Builder.adoc => io_helidon_webserver_grpc_GrpcTracingConfig.adoc} (63%) diff --git a/docs/src/main/asciidoc/config/config_reference.adoc b/docs/src/main/asciidoc/config/config_reference.adoc index c94f4570f9d..a0a05104fc4 100644 --- a/docs/src/main/asciidoc/config/config_reference.adoc +++ b/docs/src/main/asciidoc/config/config_reference.adoc @@ -30,16 +30,16 @@ The following section lists all configurable types in Helidon. - xref:{rootdir}/config/io_helidon_common_configurable_AllowList.adoc[AllowList (common.configurable)] - xref:{rootdir}/config/io_helidon_faulttolerance_Async.adoc[Async (faulttolerance)] - xref:{rootdir}/config/io_helidon_security_providers_oidc_common_BaseBuilder.adoc[BaseBuilder (security.providers.oidc.common)] -- xref:{rootdir}/config/io_helidon_metrics_api_ComponentMetricsSettings_Builder.adoc[Builder (metrics.api.ComponentMetricsSettings)] - xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProviderBase_Builder.adoc[Builder (security.providers.idcs.mapper.IdcsRoleMapperProviderBase)] - xref:{rootdir}/config/io_helidon_webserver_servicecommon_HelidonFeatureSupport_Builder.adoc[Builder (webserver.servicecommon.HelidonFeatureSupport)] -- xref:{rootdir}/config/io_helidon_webserver_servicecommon_RestServiceSettings_Builder.adoc[Builder (webserver.servicecommon.RestServiceSettings)] - xref:{rootdir}/config/io_helidon_faulttolerance_Bulkhead.adoc[Bulkhead (faulttolerance)] - xref:{rootdir}/config/io_helidon_faulttolerance_CircuitBreaker.adoc[CircuitBreaker (faulttolerance)] +- xref:{rootdir}/config/io_helidon_metrics_api_ComponentMetricsSettings.adoc[ComponentMetricsSettings (metrics.api)] - xref:{rootdir}/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc[ConfigFileMethodConfig (integrations.oci)] - xref:{rootdir}/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc[ConfigMethodConfig (integrations.oci)] - xref:{rootdir}/config/io_helidon_webserver_observe_config_ConfigObserver.adoc[ConfigObserver (webserver.observe.config)] - xref:{rootdir}/config/io_helidon_security_providers_httpauth_ConfigUserStore_ConfigUser.adoc[ConfigUser (security.providers.httpauth.ConfigUserStore)] +- xref:{rootdir}/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc[ConfigVaultProvider (security.providers.config.vault)] - xref:{rootdir}/config/io_helidon_webserver_ConnectionConfig.adoc[ConnectionConfig (webserver)] - xref:{rootdir}/config/io_helidon_http_encoding_ContentEncodingContext.adoc[ContentEncodingContext (http.encoding)] - xref:{rootdir}/config/io_helidon_webserver_context_ContextFeature.adoc[ContextFeature (webserver.context)] @@ -53,6 +53,7 @@ The following section lists all configurable types in Helidon. - xref:{rootdir}/config/io_helidon_webclient_grpc_GrpcClient.adoc[GrpcClient (webclient.grpc)] - xref:{rootdir}/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc[GrpcClientProtocolConfig (webclient.grpc)] - xref:{rootdir}/config/io_helidon_webserver_grpc_GrpcConfig.adoc[GrpcConfig (webserver.grpc)] +- xref:{rootdir}/config/io_helidon_webserver_grpc_GrpcTracingConfig.adoc[GrpcTracingConfig (webserver.grpc)] - xref:{rootdir}/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc[HeaderAtnProvider (security.providers.header)] - xref:{rootdir}/config/io_helidon_security_providers_httpsign_SignedHeadersConfig_HeadersConfig.adoc[HeadersConfig (security.providers.httpsign.SignedHeadersConfig)] - xref:{rootdir}/config/io_helidon_webserver_observe_health_HealthObserver.adoc[HealthObserver (webserver.observe.health)] @@ -67,10 +68,12 @@ The following section lists all configurable types in Helidon. - xref:{rootdir}/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc[HttpSignProvider (security.providers.httpsign)] - xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc[IdcsMtRoleMapperProvider (security.providers.idcs.mapper)] - xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc[IdcsRoleMapperProvider (security.providers.idcs.mapper)] +- xref:{rootdir}/config/io_helidon_integrations_oci_ImdsInstanceInfo.adoc[ImdsInstanceInfo (integrations.oci)] - xref:{rootdir}/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc[InboundClientDefinition (security.providers.httpsign)] - xref:{rootdir}/config/io_helidon_webserver_observe_info_InfoObserver.adoc[InfoObserver (webserver.observe.info)] - xref:{rootdir}/config/io_helidon_tracing_providers_jaeger_JaegerTracerBuilder.adoc[JaegerTracerBuilder (tracing.providers.jaeger)] - xref:{rootdir}/config/io_helidon_dbclient_jdbc_JdbcParametersConfig.adoc[JdbcParametersConfig (dbclient.jdbc)] +- xref:{rootdir}/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc[JwtAuthProvider (microprofile.jwt.auth)] - xref:{rootdir}/config/io_helidon_security_providers_jwt_JwtProvider.adoc[JwtProvider (security.providers.jwt)] - xref:{rootdir}/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc[KeyPerformanceIndicatorMetricsConfig (metrics.api)] - xref:{rootdir}/config/io_helidon_common_pki_Keys.adoc[Keys (common.pki)] @@ -104,12 +107,14 @@ The following section lists all configurable types in Helidon. - xref:{rootdir}/config/io_helidon_webclient_api_Proxy.adoc[Proxy (webclient.api)] - xref:{rootdir}/config/io_helidon_http_RequestedUriDiscoveryContext.adoc[RequestedUriDiscoveryContext (http)] - xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource (common.configurable)] +- xref:{rootdir}/config/io_helidon_webserver_servicecommon_RestServiceSettings.adoc[RestServiceSettings (webserver.servicecommon)] - xref:{rootdir}/config/io_helidon_faulttolerance_Retry.adoc[Retry (faulttolerance)] - xref:{rootdir}/config/io_helidon_common_tls_RevocationConfig.adoc[RevocationConfig (common.tls)] - xref:{rootdir}/config/io_helidon_common_configurable_ScheduledThreadPoolConfig.adoc[ScheduledThreadPoolConfig (common.configurable)] - xref:{rootdir}/config/io_helidon_common_configurable_ScheduledThreadPoolSupplier.adoc[ScheduledThreadPoolSupplier (common.configurable)] - xref:{rootdir}/config/io_helidon_metrics_api_ScopeConfig.adoc[ScopeConfig (metrics.api)] - xref:{rootdir}/config/io_helidon_metrics_api_ScopingConfig.adoc[ScopingConfig (metrics.api)] +- xref:{rootdir}/config/io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc[SecretConfig (security.providers.config.vault.ConfigVaultProvider)] - xref:{rootdir}/config/io_helidon_security_Security.adoc[Security (security)] - xref:{rootdir}/config/io_helidon_webserver_security_SecurityFeature.adoc[SecurityFeature (webserver.security)] - xref:{rootdir}/config/io_helidon_webserver_security_SecurityHandler.adoc[SecurityHandler (webserver.security)] diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_AllowList.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_AllowList.adoc index 733341db9e0..44d46254466 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_AllowList.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_AllowList.adoc @@ -43,34 +43,34 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |key |type |default value |description |`allow.all` |boolean |`false` |Allows all strings to match (subject to "deny" conditions). An `allow.all` setting of `false` does - not deny all strings but rather represents the absence of a universal match, meaning that other allow and deny settings - determine the matching outcomes. +not deny all strings but rather represents the absence of a universal match, meaning that other allow and deny settings +determine the matching outcomes. - Whether to allow all strings to match (subject to "deny" conditions) +Whether to allow all strings to match (subject to "deny" conditions) |`allow.exact` |string[] |{nbsp} |Exact strings to allow. - Exact strings to allow +Exact strings to allow |`allow.pattern` |Pattern[] |{nbsp} |Patterns specifying strings to allow. - Patterns which allow matching +Patterns which allow matching |`allow.prefix` |string[] |{nbsp} |Prefixes specifying strings to allow. - Prefixes which allow matching +Prefixes which allow matching |`allow.suffix` |string[] |{nbsp} |Suffixes specifying strings to allow. - Suffixes which allow matching +Suffixes which allow matching |`deny.exact` |string[] |{nbsp} |Exact strings to deny. - Exact strings to allow +Exact strings to deny |`deny.pattern` |Pattern[] |{nbsp} |Patterns specifying strings to deny. - Patterns which deny matching +Patterns which deny matching |`deny.prefix` |string[] |{nbsp} |Prefixes specifying strings to deny. - Prefixes which deny matching +Prefixes which deny matching |`deny.suffix` |string[] |{nbsp} |Suffixes specifying strings to deny. - Suffixes which deny matching +Suffixes which deny matching |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_LruCache.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_LruCache.adoc index c06372ef3cc..b840fef899d 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_LruCache.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_LruCache.adoc @@ -44,7 +44,7 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |`capacity` |int |`10000` |Configure capacity of the cache. Defaults to LruCache.DEFAULT_CAPACITY. - Maximal number of records in the cache before the oldest one is removed +Maximal number of records in the cache before the oldest one is removed |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_Resource.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_Resource.adoc index c28b25ee425..971519477d9 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_Resource.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_Resource.adoc @@ -44,34 +44,34 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |`content` |string |{nbsp} |Binary content of the resource (base64 encoded). - Binary content +Binary content |`content-plain` |string |{nbsp} |Plain content of the resource (text). - Plain content +Plain content |`description` |string |{nbsp} |Description of this resource when configured through plain text or binary. - Description +Description |`path` |Path |{nbsp} |Resource is located on filesystem. - Path of the resource +Path of the resource |`proxy-host` |string |{nbsp} |Host of the proxy when using URI. - Proxy host +Proxy host |`proxy-port` |int |`80` |Port of the proxy when using URI. - Proxy port +Proxy port |`resource-path` |string |{nbsp} |Resource is located on classpath. - Classpath location of the resource +Classpath location of the resource |`uri` |URI |{nbsp} |Resource is available on a java.net.URI. - Of the resource - See proxy() - See useProxy() +Of the resource +See proxy() +See useProxy() |`use-proxy` |boolean |`true` |Whether to use proxy. If set to `false`, proxy will not be used even if configured. - When set to `true` (default), proxy will be used if configured. +When set to `true` (default), proxy will be used if configured. - Whether to use proxy if configured +Whether to use proxy if configured |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolConfig.adoc index 8e8a4a02a3d..4343535007a 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolConfig.adoc @@ -43,26 +43,26 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |key |type |default value |description |`core-pool-size` |int |`16` |Core pool size of the thread pool executor. - Defaults to DEFAULT_CORE_POOL_SIZE. +Defaults to DEFAULT_CORE_POOL_SIZE. - CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() +CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() |`is-daemon` |boolean |`true` |Is daemon of the thread pool executor. - Defaults to DEFAULT_IS_DAEMON. +Defaults to DEFAULT_IS_DAEMON. - Whether the threads are daemon threads +Whether the threads are daemon threads |`prestart` |boolean |`false` |Whether to prestart core threads in this thread pool executor. - Defaults to DEFAULT_PRESTART. +Defaults to DEFAULT_PRESTART. - Whether to prestart the threads +Whether to prestart the threads |`thread-name-prefix` |string |`helidon-` |Name prefix for threads in this thread pool executor. - Defaults to DEFAULT_THREAD_NAME_PREFIX. +Defaults to DEFAULT_THREAD_NAME_PREFIX. - Prefix of a thread name +Prefix of a thread name |`virtual-threads` |boolean |{nbsp} |When configured to `true`, an unbounded virtual executor service (project Loom) will be used. - If enabled, all other configuration options of this executor service are ignored! +If enabled, all other configuration options of this executor service are ignored! - Whether to use virtual threads or not, defaults to `false` +Whether to use virtual threads or not, defaults to `false` |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolSupplier.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolSupplier.adoc index 8e8a4a02a3d..4343535007a 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolSupplier.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ScheduledThreadPoolSupplier.adoc @@ -43,26 +43,26 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |key |type |default value |description |`core-pool-size` |int |`16` |Core pool size of the thread pool executor. - Defaults to DEFAULT_CORE_POOL_SIZE. +Defaults to DEFAULT_CORE_POOL_SIZE. - CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() +CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() |`is-daemon` |boolean |`true` |Is daemon of the thread pool executor. - Defaults to DEFAULT_IS_DAEMON. +Defaults to DEFAULT_IS_DAEMON. - Whether the threads are daemon threads +Whether the threads are daemon threads |`prestart` |boolean |`false` |Whether to prestart core threads in this thread pool executor. - Defaults to DEFAULT_PRESTART. +Defaults to DEFAULT_PRESTART. - Whether to prestart the threads +Whether to prestart the threads |`thread-name-prefix` |string |`helidon-` |Name prefix for threads in this thread pool executor. - Defaults to DEFAULT_THREAD_NAME_PREFIX. +Defaults to DEFAULT_THREAD_NAME_PREFIX. - Prefix of a thread name +Prefix of a thread name |`virtual-threads` |boolean |{nbsp} |When configured to `true`, an unbounded virtual executor service (project Loom) will be used. - If enabled, all other configuration options of this executor service are ignored! +If enabled, all other configuration options of this executor service are ignored! - Whether to use virtual threads or not, defaults to `false` +Whether to use virtual threads or not, defaults to `false` |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolConfig.adoc index 0470d14e859..27843db096e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolConfig.adoc @@ -43,58 +43,58 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |key |type |default value |description |`core-pool-size` |int |`10` |Core pool size of the thread pool executor. - Defaults to DEFAULT_CORE_POOL_SIZE. +Defaults to DEFAULT_CORE_POOL_SIZE. - CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() +CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() |`growth-rate` |int |`0` |The percentage of task submissions that should result in adding threads, expressed as a value from 1 to 100. The - rate applies only when all of the following are true: +rate applies only when all of the following are true: - the pool size is below the maximum, and - there are no idle threads, and - the number of tasks in the queue exceeds the `growthThreshold` For example, a rate of 20 means that while these conditions are met one thread will be added for every 5 submitted - tasks. +tasks. - Defaults to DEFAULT_GROWTH_RATE +Defaults to DEFAULT_GROWTH_RATE - The growth rate +The growth rate |`growth-threshold` |int |`1000` |The queue size above which pool growth will be considered if the pool is not fixed size. - Defaults to DEFAULT_GROWTH_THRESHOLD. +Defaults to DEFAULT_GROWTH_THRESHOLD. - The growth threshold +The growth threshold |`is-daemon` |boolean |`true` |Is daemon of the thread pool executor. - Defaults to DEFAULT_IS_DAEMON. +Defaults to DEFAULT_IS_DAEMON. - Whether the threads are daemon threads +Whether the threads are daemon threads |`keep-alive` |Duration |`PT3M` |Keep alive of the thread pool executor. - Defaults to DEFAULT_KEEP_ALIVE. +Defaults to DEFAULT_KEEP_ALIVE. - Keep alive see java.util.concurrent.ThreadPoolExecutor.getKeepAliveTime(java.util.concurrent.TimeUnit) +Keep alive see java.util.concurrent.ThreadPoolExecutor.getKeepAliveTime(java.util.concurrent.TimeUnit) |`max-pool-size` |int |`50` |Max pool size of the thread pool executor. - Defaults to DEFAULT_MAX_POOL_SIZE. +Defaults to DEFAULT_MAX_POOL_SIZE. - MaxPoolSize see java.util.concurrent.ThreadPoolExecutor.getMaximumPoolSize() +MaxPoolSize see java.util.concurrent.ThreadPoolExecutor.getMaximumPoolSize() |`name` |string |{nbsp} |Name of this thread pool executor. - The pool name +The pool name |`queue-capacity` |int |`10000` |Queue capacity of the thread pool executor. - Defaults to DEFAULT_QUEUE_CAPACITY. +Defaults to DEFAULT_QUEUE_CAPACITY. - Capacity of the queue backing the executor +Capacity of the queue backing the executor |`should-prestart` |boolean |`true` |Whether to prestart core threads in this thread pool executor. - Defaults to DEFAULT_PRESTART. +Defaults to DEFAULT_PRESTART. - Whether to prestart the threads +Whether to prestart the threads |`thread-name-prefix` |string |{nbsp} |Name prefix for threads in this thread pool executor. - Defaults to DEFAULT_THREAD_NAME_PREFIX. +Defaults to DEFAULT_THREAD_NAME_PREFIX. - Prefix of a thread name +Prefix of a thread name |`virtual-threads` |boolean |{nbsp} |When configured to `true`, an unbounded virtual executor service (project Loom) will be used. - If enabled, all other configuration options of this executor service are ignored! +If enabled, all other configuration options of this executor service are ignored! - Whether to use virtual threads or not, defaults to `false` +Whether to use virtual threads or not, defaults to `false` |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolSupplier.adoc b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolSupplier.adoc index 0470d14e859..27843db096e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolSupplier.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_configurable_ThreadPoolSupplier.adoc @@ -43,58 +43,58 @@ Type: link:{javadoc-base-url}/io.helidon.common.configurable/io/helidon/common/c |key |type |default value |description |`core-pool-size` |int |`10` |Core pool size of the thread pool executor. - Defaults to DEFAULT_CORE_POOL_SIZE. +Defaults to DEFAULT_CORE_POOL_SIZE. - CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() +CorePoolSize see java.util.concurrent.ThreadPoolExecutor.getCorePoolSize() |`growth-rate` |int |`0` |The percentage of task submissions that should result in adding threads, expressed as a value from 1 to 100. The - rate applies only when all of the following are true: +rate applies only when all of the following are true: - the pool size is below the maximum, and - there are no idle threads, and - the number of tasks in the queue exceeds the `growthThreshold` For example, a rate of 20 means that while these conditions are met one thread will be added for every 5 submitted - tasks. +tasks. - Defaults to DEFAULT_GROWTH_RATE +Defaults to DEFAULT_GROWTH_RATE - The growth rate +The growth rate |`growth-threshold` |int |`1000` |The queue size above which pool growth will be considered if the pool is not fixed size. - Defaults to DEFAULT_GROWTH_THRESHOLD. +Defaults to DEFAULT_GROWTH_THRESHOLD. - The growth threshold +The growth threshold |`is-daemon` |boolean |`true` |Is daemon of the thread pool executor. - Defaults to DEFAULT_IS_DAEMON. +Defaults to DEFAULT_IS_DAEMON. - Whether the threads are daemon threads +Whether the threads are daemon threads |`keep-alive` |Duration |`PT3M` |Keep alive of the thread pool executor. - Defaults to DEFAULT_KEEP_ALIVE. +Defaults to DEFAULT_KEEP_ALIVE. - Keep alive see java.util.concurrent.ThreadPoolExecutor.getKeepAliveTime(java.util.concurrent.TimeUnit) +Keep alive see java.util.concurrent.ThreadPoolExecutor.getKeepAliveTime(java.util.concurrent.TimeUnit) |`max-pool-size` |int |`50` |Max pool size of the thread pool executor. - Defaults to DEFAULT_MAX_POOL_SIZE. +Defaults to DEFAULT_MAX_POOL_SIZE. - MaxPoolSize see java.util.concurrent.ThreadPoolExecutor.getMaximumPoolSize() +MaxPoolSize see java.util.concurrent.ThreadPoolExecutor.getMaximumPoolSize() |`name` |string |{nbsp} |Name of this thread pool executor. - The pool name +The pool name |`queue-capacity` |int |`10000` |Queue capacity of the thread pool executor. - Defaults to DEFAULT_QUEUE_CAPACITY. +Defaults to DEFAULT_QUEUE_CAPACITY. - Capacity of the queue backing the executor +Capacity of the queue backing the executor |`should-prestart` |boolean |`true` |Whether to prestart core threads in this thread pool executor. - Defaults to DEFAULT_PRESTART. +Defaults to DEFAULT_PRESTART. - Whether to prestart the threads +Whether to prestart the threads |`thread-name-prefix` |string |{nbsp} |Name prefix for threads in this thread pool executor. - Defaults to DEFAULT_THREAD_NAME_PREFIX. +Defaults to DEFAULT_THREAD_NAME_PREFIX. - Prefix of a thread name +Prefix of a thread name |`virtual-threads` |boolean |{nbsp} |When configured to `true`, an unbounded virtual executor service (project Loom) will be used. - If enabled, all other configuration options of this executor service are ignored! +If enabled, all other configuration options of this executor service are ignored! - Whether to use virtual threads or not, defaults to `false` +Whether to use virtual threads or not, defaults to `false` |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_pki_Keys.adoc b/docs/src/main/asciidoc/config/io_helidon_common_pki_Keys.adoc index 73ac006f60d..0fa04a3f930 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_pki_Keys.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_pki_Keys.adoc @@ -43,15 +43,15 @@ Type: link:{javadoc-base-url}/io.helidon.common.pki/io/helidon/common/pki/Keys.h |key |type |default value |description |`keystore` |xref:{rootdir}/config/io_helidon_common_pki_KeystoreKeys.adoc[KeystoreKeys] |{nbsp} |Configure keys from a keystore. - Once the config object is built, this option will ALWAYS be empty. All keys from the keystore will be - populated to privateKey(), publicKey(), publicCert() etc. +Once the config object is built, this option will ALWAYS be empty. All keys from the keystore will be +populated to privateKey(), publicKey(), publicCert() etc. - Keystore configuration +Keystore configuration |`pem` |xref:{rootdir}/config/io_helidon_common_pki_PemKeys.adoc[PemKeys] |{nbsp} |Configure keys from pem file(s). - Once the config object is built, this option will ALWAYS be empty. All keys from the keystore will be - populated to privateKey(), publicKey(), publicCert() etc. +Once the config object is built, this option will ALWAYS be empty. All keys from the keystore will be +populated to privateKey(), publicKey(), publicCert() etc. - Pem based definition +Pem based definition |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_pki_KeystoreKeys.adoc b/docs/src/main/asciidoc/config/io_helidon_common_pki_KeystoreKeys.adoc index 879150c5ae8..ef3721069cd 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_pki_KeystoreKeys.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_pki_KeystoreKeys.adoc @@ -41,7 +41,7 @@ Type: link:{javadoc-base-url}/io.helidon.common.pki/io/helidon/common/pki/Keysto |`resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Keystore resource definition. - Keystore resource, from file path, classpath, URL etc. +Keystore resource, from file path, classpath, URL etc. |=== @@ -55,31 +55,31 @@ Type: link:{javadoc-base-url}/io.helidon.common.pki/io/helidon/common/pki/Keysto |`cert-chain.alias` |string |{nbsp} |Alias of an X.509 chain. - Alias of certificate chain in the keystore +Alias of certificate chain in the keystore |`cert.alias` |string |{nbsp} |Alias of X.509 certificate of public key. - Used to load both the certificate and public key. +Used to load both the certificate and public key. - Alias under which the certificate is stored in the keystore +Alias under which the certificate is stored in the keystore |`key.alias` |string |{nbsp} |Alias of the private key in the keystore. - Alias of the key in the keystore +Alias of the key in the keystore |`key.passphrase` |char[] |{nbsp} |Pass-phrase of the key in the keystore (used for private keys). - This is (by default) the same as keystore passphrase - only configure - if it differs from keystore passphrase. +This is (by default) the same as keystore passphrase - only configure +if it differs from keystore passphrase. - Pass-phrase of the key +Pass-phrase of the key |`passphrase` |char[] |{nbsp} |Pass-phrase of the keystore (supported with JKS and PKCS12 keystores). - Keystore password to use +Keystore password to use |`trust-store` |boolean |`false` |If you want to build a trust store, call this method to add all - certificates present in the keystore to certificate list. +certificates present in the keystore to certificate list. - Whether this is a trust store +Whether this is a trust store |`type` |string |`PKCS12` |Set type of keystore. - Defaults to DEFAULT_KEYSTORE_TYPE, - expected are other keystore types supported by java then can store keys under aliases. +Defaults to DEFAULT_KEYSTORE_TYPE, +expected are other keystore types supported by java then can store keys under aliases. - Keystore type to load the key +Keystore type to load the key |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_pki_PemKeys.adoc b/docs/src/main/asciidoc/config/io_helidon_common_pki_PemKeys.adoc index 0ce01213cc4..86165efb690 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_pki_PemKeys.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_pki_PemKeys.adoc @@ -44,20 +44,20 @@ Type: link:{javadoc-base-url}/io.helidon.common.pki/io/helidon/common/pki/PemKey |`cert-chain.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Load certificate chain from PEM resource. - Resource (e.g. classpath, file path, URL etc.) +Resource (e.g. classpath, file path, URL etc.) |`certificates.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Read one or more certificates in PEM format from a resource definition. Used eg: in a trust store. - Key resource (file, classpath, URL etc.) +Key resource (file, classpath, URL etc.) |`key.passphrase` |char[] |{nbsp} |Passphrase for private key. If the key is encrypted (and in PEM PKCS#8 format), this passphrase will be used to - decrypt it. +decrypt it. - Passphrase used to encrypt the private key +Passphrase used to encrypt the private key |`key.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Read a private key from PEM format from a resource definition. - Key resource (file, classpath, URL etc.) +Key resource (file, classpath, URL etc.) |`public-key.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Read a public key from PEM format from a resource definition. - Public key resource (file, classpath, URL etc.) +Public key resource (file, classpath, URL etc.) |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_socket_SocketOptions.adoc b/docs/src/main/asciidoc/config/io_helidon_common_socket_SocketOptions.adoc index 15582cb3901..c3b74f7d34d 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_socket_SocketOptions.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_socket_SocketOptions.adoc @@ -44,33 +44,33 @@ Type: link:{javadoc-base-url}/io.helidon.common.socket/io/helidon/common/socket/ |`connect-timeout` |Duration |`PT10S` |Socket connect timeout. Default is 10 seconds. - Connect timeout duration +Connect timeout duration |`read-timeout` |Duration |`PT30S` |Socket read timeout. Default is 30 seconds. - Read timeout duration +Read timeout duration |`socket-keep-alive` |boolean |`true` |Configure socket keep alive. - Default is `true`. +Default is `true`. - Keep alive - See java.net.StandardSocketOptions.SO_KEEPALIVE +Keep alive +See java.net.StandardSocketOptions.SO_KEEPALIVE |`socket-receive-buffer-size` |int |{nbsp} |Socket receive buffer size. - Buffer size, in bytes - See java.net.StandardSocketOptions.SO_RCVBUF +Buffer size, in bytes +See java.net.StandardSocketOptions.SO_RCVBUF |`socket-reuse-address` |boolean |`true` |Socket reuse address. - Default is `true`. +Default is `true`. - Whether to reuse address - See java.net.StandardSocketOptions.SO_REUSEADDR +Whether to reuse address +See java.net.StandardSocketOptions.SO_REUSEADDR |`socket-send-buffer-size` |int |{nbsp} |Socket send buffer size. - Buffer size, in bytes - See java.net.StandardSocketOptions.SO_SNDBUF +Buffer size, in bytes +See java.net.StandardSocketOptions.SO_SNDBUF |`tcp-no-delay` |boolean |`false` |This option may improve performance on some systems. - Default is `false`. +Default is `false`. - Whether to use TCP_NODELAY, defaults to `false` - See java.net.StandardSocketOptions.TCP_NODELAY +Whether to use TCP_NODELAY, defaults to `false` +See java.net.StandardSocketOptions.TCP_NODELAY |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_common_tls_RevocationConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_common_tls_RevocationConfig.adoc index 20c489ce277..3dd53382018 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_tls_RevocationConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_tls_RevocationConfig.adoc @@ -43,38 +43,38 @@ Type: link:{javadoc-base-url}/io.helidon.common.tls/io/helidon/common/tls/Revoca |key |type |default value |description |`check-only-end-entity` |boolean |`false` |Only check the revocation status of end-entity certificates. - Default value is `false`. +Default value is `false`. - Whether to check only end-entity certificates +Whether to check only end-entity certificates |`enabled` |boolean |`false` |Flag indicating whether this revocation config is enabled. - Enabled flag +Enabled flag |`fallback-enabled` |boolean |`true` |Enable fallback to the less preferred checking option. -
- If the primary method for revocation checking fails to verify the revocation status of a certificate - (such as using a CRL or OCSP), the checker will attempt alternative methods. This option ensures - whether revocation checking is performed strictly according to the specified method, or should fallback - to the one less preferred. OCSP is preferred over the CRL by default. - Whether to allow fallback to the less preferred checking option +If the primary method for revocation checking fails to verify the revocation status of a certificate +(such as using a CRL or OCSP), the checker will attempt alternative methods. This option ensures +whether revocation checking is performed strictly according to the specified method, or should fallback +to the one less preferred. OCSP is preferred over the CRL by default. + +Whether to allow fallback to the less preferred checking option |`ocsp-responder-uri` |URI |{nbsp} |The URI that identifies the location of the OCSP responder. This - overrides the `ocsp.responderURL` security property and any - responder specified in a certificate's Authority Information Access - Extension, as defined in RFC 5280. +overrides the `ocsp.responderURL` security property and any +responder specified in a certificate's Authority Information Access +Extension, as defined in RFC 5280. - OCSP responder URI +OCSP responder URI |`prefer-crl-over-ocsp` |boolean |`false` |Prefer CRL over OCSP. - Default value is `false`. OCSP is preferred over the CRL by default. +Default value is `false`. OCSP is preferred over the CRL by default. - Whether to prefer CRL over OCSP +Whether to prefer CRL over OCSP |`soft-fail-enabled` |boolean |`false` |Allow revocation check to succeed if the revocation status cannot be - determined for one of the following reasons: +determined for one of the following reasons: - The CRL or OCSP response cannot be obtained because of a - network error. - + network error. + - The OCSP responder returns one of the following errors - specified in section 2.3 of RFC 2560: internalError or tryLater. + specified in section 2.3 of RFC 2560: internalError or tryLater. Whether soft fail is enabled diff --git a/docs/src/main/asciidoc/config/io_helidon_common_tls_Tls.adoc b/docs/src/main/asciidoc/config/io_helidon_common_tls_Tls.adoc index 0be141798c3..cd75173fc43 100644 --- a/docs/src/main/asciidoc/config/io_helidon_common_tls_Tls.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_common_tls_Tls.adoc @@ -44,75 +44,88 @@ Type: link:{javadoc-base-url}/io.helidon.common.tls/io/helidon/common/tls/Tls.ht |`cipher-suite` |string[] |{nbsp} |Enabled cipher suites for TLS communication. - Cipher suits to enable, by default (or if list is empty), all available cipher suites - are enabled -|`client-auth` |TlsClientAuth |`TlsClientAuth.NONE` |Configure requirement for mutual TLS. +Cipher suites to enable, by default (or if list is empty), all available cipher suites + are enabled +|`client-auth` |TlsClientAuth (REQUIRED, OPTIONAL, NONE) |`TlsClientAuth.NONE` |Configure requirement for mutual TLS. + +What type of mutual TLS to use, defaults to TlsClientAuth.NONE + +Allowed values: + +- `REQUIRED`: Mutual TLS is required. +Server MUST present a certificate trusted by the client, client MUST present a certificate trusted by the server. +This implies private key and trust configuration for both server and client. +- `OPTIONAL`: Mutual TLS is optional. +Server MUST present a certificate trusted by the client, client MAY present a certificate trusted by the server. +This implies private key configuration at least for server, trust configuration for at least client. +- `NONE`: Mutual TLS is disabled. +Server MUST present a certificate trusted by the client, client does not present a certificate. +This implies private key configuration for server, trust configuration for client. - What type of mutual TLS to use, defaults to TlsClientAuth.NONE |`enabled` |boolean |`true` |Flag indicating whether Tls is enabled. - Enabled flag +Enabled flag |`endpoint-identification-algorithm` |string |`HTTPS` |Identification algorithm for SSL endpoints. - Configure endpoint identification algorithm, or set to `NONE` - to disable endpoint identification (equivalent to hostname verification). - Defaults to Tls.ENDPOINT_IDENTIFICATION_HTTPS +Configure endpoint identification algorithm, or set to `NONE` + to disable endpoint identification (equivalent to hostname verification). + Defaults to Tls.ENDPOINT_IDENTIFICATION_HTTPS |`internal-keystore-provider` |string |{nbsp} |Provider of the key stores used internally to create a key and trust manager factories. - Keystore provider, if not defined, provider is not specified +Keystore provider, if not defined, provider is not specified |`internal-keystore-type` |string |{nbsp} |Type of the key stores used internally to create a key and trust manager factories. - Keystore type, defaults to java.security.KeyStore.getDefaultType() +Keystore type, defaults to java.security.KeyStore.getDefaultType() |`key-manager-factory-algorithm` |string |{nbsp} |Algorithm of the key manager factory used when private key is defined. - Defaults to javax.net.ssl.KeyManagerFactory.getDefaultAlgorithm(). +Defaults to javax.net.ssl.KeyManagerFactory.getDefaultAlgorithm(). - Algorithm to use +Algorithm to use |`manager` |io.helidon.common.tls.TlsManager (service provider interface) |{nbsp} |The Tls manager. If one is not explicitly defined in the config then a default manager will be created. - The tls manager of the tls instance - See ConfiguredTlsManager +The tls manager of the tls instance +See ConfiguredTlsManager |`private-key` |PrivateKey |{nbsp} |Private key to use. For server side TLS, this is required. - For client side TLS, this is optional (used when mutual TLS is enabled). +For client side TLS, this is optional (used when mutual TLS is enabled). - Private key to use +Private key to use |`protocol` |string |`TLS` |Configure the protocol used to obtain an instance of javax.net.ssl.SSLContext. - Protocol to use, defaults to DEFAULT_PROTOCOL +Protocol to use, defaults to DEFAULT_PROTOCOL |`protocols` |string[] |{nbsp} |Enabled protocols for TLS communication. - Example of valid values for `TLS` protocol: `TLSv1.3`, `TLSv1.2` +Example of valid values for `TLS` protocol: `TLSv1.3`, `TLSv1.2` - Protocols to enable, by default (or if list is empty), all available protocols are enabled +Protocols to enable, by default (or if list is empty), all available protocols are enabled |`provider` |string |{nbsp} |Use explicit provider to obtain an instance of javax.net.ssl.SSLContext. - Provider to use, defaults to none (only protocol() is used by default) +Provider to use, defaults to none (only protocol() is used by default) |`revocation` |xref:{rootdir}/config/io_helidon_common_tls_RevocationConfig.adoc[RevocationConfig] |{nbsp} |Certificate revocation check configuration. - Certificate revocation configuration +Certificate revocation configuration |`secure-random-algorithm` |string |{nbsp} |Algorithm to use when creating a new secure random. - Algorithm to use, by default uses java.security.SecureRandom constructor +Algorithm to use, by default uses java.security.SecureRandom constructor |`secure-random-provider` |string |{nbsp} |Provider to use when creating a new secure random. - When defined, secureRandomAlgorithm() must be defined as well. +When defined, secureRandomAlgorithm() must be defined as well. - Provider to use, by default no provider is specified +Provider to use, by default no provider is specified |`session-cache-size` |int |`20480` |SSL session cache size. - Session cache size, defaults to DEFAULT_SESSION_CACHE_SIZE. +Session cache size, defaults to DEFAULT_SESSION_CACHE_SIZE. |`session-timeout` |Duration |`PT24H` |SSL session timeout. - Session timeout, defaults to DEFAULT_SESSION_TIMEOUT. +Session timeout, defaults to DEFAULT_SESSION_TIMEOUT. |`trust` |X509Certificate[] |{nbsp} |List of certificates that form the trust manager. - Certificates to be trusted +Certificates to be trusted |`trust-all` |boolean |`false` |Trust any certificate provided by the other side of communication. - This is a dangerous setting: if set to `true`, any certificate will be accepted, throwing away - most of the security advantages of TLS. NEVER do this in production. +*This is a dangerous setting:* if set to `true`, any certificate will be accepted, throwing away +most of the security advantages of TLS. *NEVER* do this in production. - Whether to trust all certificates, do not use in production +Whether to trust all certificates, do not use in production |`trust-manager-factory-algorithm` |string |{nbsp} |Trust manager factory algorithm. - Algorithm to use +Algorithm to use |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_dbclient_jdbc_JdbcParametersConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_dbclient_jdbc_JdbcParametersConfig.adoc index 070a64f2c12..db6fe8a629c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_dbclient_jdbc_JdbcParametersConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_dbclient_jdbc_JdbcParametersConfig.adoc @@ -49,41 +49,41 @@ parameters |key |type |default value |description |`set-object-for-java-time` |boolean |`true` |Set all `java.time` Date/Time values directly using java.sql.PreparedStatement.setObject(int, Object). - This option shall work fine for recent JDBC drivers. - Default value is `true`. +This option shall work fine for recent JDBC drivers. +Default value is `true`. - Whether to use java.sql.PreparedStatement.setObject(int, Object) for `java.time` Date/Time values +Whether to use java.sql.PreparedStatement.setObject(int, Object) for `java.time` Date/Time values |`string-binding-size` |int |`1024` |String values with length above this limit will be bound - using java.sql.PreparedStatement.setCharacterStream(int, java.io.Reader, int) - if useStringBinding() is set to `true`. - Default value is `1024`. +using java.sql.PreparedStatement.setCharacterStream(int, java.io.Reader, int) +if useStringBinding() is set to `true`. +Default value is `1024`. - String values length limit for java.io.CharArrayReader binding +String values length limit for java.io.CharArrayReader binding |`timestamp-for-local-time` |boolean |`true` |Use java.sql.PreparedStatement.setTimestamp(int, java.sql.Timestamp) - to set java.time.LocalTime values when `true` - or use java.sql.PreparedStatement.setTime(int, java.sql.Time) when `false`. - Default value is `true`. +to set java.time.LocalTime values when `true` +or use java.sql.PreparedStatement.setTime(int, java.sql.Time) when `false`. +Default value is `true`. This option is vendor specific. Most of the databases are fine with java.sql.Timestamp, - but for example SQL Server requires java.sql.Time. - This option does not apply when setObjectForJavaTime() is set to `true`. +but for example SQL Server requires java.sql.Time. +This option does not apply when setObjectForJavaTime() is set to `true`. - Whether to use java.sql.Timestamp instead of java.sql.Time - for java.time.LocalTime values +Whether to use java.sql.Timestamp instead of java.sql.Time + for java.time.LocalTime values |`use-byte-array-binding` |boolean |`true` |Use java.sql.PreparedStatement.setBinaryStream(int, java.io.InputStream, int) binding - for `byte[]` values. - Default value is `true`. +for `byte[]` values. +Default value is `true`. - Whether to use java.io.ByteArrayInputStream binding +Whether to use java.io.ByteArrayInputStream binding |`use-n-string` |boolean |`false` |Use SQL `NCHAR`, `NVARCHAR` or `LONGNVARCHAR` value conversion - for String values. - Default value is `false`. +for String values. +Default value is `false`. - Whether NString conversion is used +Whether NString conversion is used |`use-string-binding` |boolean |`true` |Use java.sql.PreparedStatement.setCharacterStream(int, java.io.Reader, int) binding - for String values with length above stringBindingSize() limit. - Default value is `true`. +for String values with length above stringBindingSize() limit. +Default value is `true`. - Whether to use java.io.CharArrayReader binding +Whether to use java.io.CharArrayReader binding |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Async.adoc b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Async.adoc index c0a54be5be9..13d24ed588e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Async.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Async.adoc @@ -44,8 +44,8 @@ Type: link:{javadoc-base-url}/io.helidon.faulttolerance/io/helidon/faulttoleranc |`executor-name` |string |{nbsp} |Name of an executor service. This is only honored when service registry is used. - Name fo the java.util.concurrent.ExecutorService to lookup - See executor() +Name fo the java.util.concurrent.ExecutorService to lookup +See executor() |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Bulkhead.adoc b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Bulkhead.adoc index 9f7027f1ca2..8a7645c5e00 100644 --- a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Bulkhead.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Bulkhead.adoc @@ -45,14 +45,14 @@ This is a standalone configuration type, prefix from configuration root: `fault- |key |type |default value |description |`limit` |int |`10` |Maximal number of parallel requests going through this bulkhead. - When the limit is reached, additional requests are enqueued. +When the limit is reached, additional requests are enqueued. - Maximal number of parallel calls, defaults is DEFAULT_LIMIT +Maximal number of parallel calls, defaults is DEFAULT_LIMIT |`queue-length` |int |`10` |Maximal number of enqueued requests waiting for processing. - When the limit is reached, additional attempts to invoke - a request will receive a BulkheadException. +When the limit is reached, additional attempts to invoke +a request will receive a BulkheadException. - Length of the queue +Length of the queue |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_CircuitBreaker.adoc b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_CircuitBreaker.adoc index 9a4dd921426..ea06b3b349c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_CircuitBreaker.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_CircuitBreaker.adoc @@ -46,24 +46,24 @@ This is a standalone configuration type, prefix from configuration root: `fault- |`delay` |Duration |`PT5S` |How long to wait before transitioning from open to half-open state. - Delay +Delay |`error-ratio` |int |`60` |How many failures out of 100 will trigger the circuit to open. - This is adapted to the volume() used to handle the window of requests. +This is adapted to the volume() used to handle the window of requests. If errorRatio is 40, and volume is 10, 4 failed requests will open the circuit. - Default is DEFAULT_ERROR_RATIO. +Default is DEFAULT_ERROR_RATIO. - Percent of failure that trigger the circuit to open - See volume() +Percent of failure that trigger the circuit to open +See volume() |`success-threshold` |int |`1` |How many successful calls will close a half-open circuit. - Nevertheless, the first failed call will open the circuit again. - Default is DEFAULT_SUCCESS_THRESHOLD. +Nevertheless, the first failed call will open the circuit again. +Default is DEFAULT_SUCCESS_THRESHOLD. - Number of calls +Number of calls |`volume` |int |`10` |Rolling window size used to calculate ratio of failed requests. - Default is DEFAULT_VOLUME. +Default is DEFAULT_VOLUME. - How big a window is used to calculate error errorRatio - See errorRatio() +How big a window is used to calculate error errorRatio +See errorRatio() |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Retry.adoc b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Retry.adoc index b1784993715..58e69696b83 100644 --- a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Retry.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Retry.adoc @@ -46,25 +46,25 @@ This is a standalone configuration type, prefix from configuration root: `fault- |`calls` |int |`3` |Number of calls (first try + retries). - Number of desired calls, must be 1 (means no retries) or higher. +Number of desired calls, must be 1 (means no retries) or higher. |`delay` |Duration |`PT0.2S` |Base delay between try and retry. - Defaults to `200 ms`. +Defaults to `200 ms`. - Delay between retries (combines with retry policy) +Delay between retries (combines with retry policy) |`delay-factor` |double |`-1.0` |Delay retry policy factor. If unspecified (value of `-1`), Jitter retry policy would be used, unless - jitter is also unspecified. +jitter is also unspecified. - Default when Retry.DelayingRetryPolicy is used is `2`. +Default when Retry.DelayingRetryPolicy is used is `2`. - Delay factor for delaying retry policy +Delay factor for delaying retry policy |`jitter` |Duration |`PT-1S` |Jitter for Retry.JitterRetryPolicy. If unspecified (value of `-1`), - delaying retry policy is used. If both this value, and delayFactor() are specified, delaying retry policy - would be used. +delaying retry policy is used. If both this value, and delayFactor() are specified, delaying retry policy +would be used. - Jitter +Jitter |`overall-timeout` |Duration |`PT1S` |Overall timeout of all retries combined. - Overall timeout +Overall timeout |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Timeout.adoc b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Timeout.adoc index 1311988311f..d8a0ad4beeb 100644 --- a/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Timeout.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_faulttolerance_Timeout.adoc @@ -45,13 +45,13 @@ This is a standalone configuration type, prefix from configuration root: `fault- |key |type |default value |description |`current-thread` |boolean |`false` |Flag to indicate that code must be executed in current thread instead - of in an executor's thread. This flag is `false` by default. +of in an executor's thread. This flag is `false` by default. - whether to execute on current thread (`true`), or in an executor service (`false`}) +Whether to execute on current thread (`true`), or in an executor service (`false`}) |`timeout` |Duration |`PT10S` |Duration to wait before timing out. - Defaults to `10 seconds`. +Defaults to `10 seconds`. - Timeout +Timeout |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_http_RequestedUriDiscoveryContext.adoc b/docs/src/main/asciidoc/config/io_helidon_http_RequestedUriDiscoveryContext.adoc index c43c7416ba8..d1f5a96f870 100644 --- a/docs/src/main/asciidoc/config/io_helidon_http_RequestedUriDiscoveryContext.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_http_RequestedUriDiscoveryContext.adoc @@ -46,6 +46,19 @@ Type: link:{javadoc-base-url}/io.helidon.http/io/helidon/http/RequestedUriDiscov |`trusted-proxies` |xref:{rootdir}/config/io_helidon_common_configurable_AllowList.adoc[AllowList] |{nbsp} |Sets the trusted proxies for requested URI discovery for requests arriving on the socket. |`types` |RequestedUriDiscoveryType[] (FORWARDED, X_FORWARDED, HOST) |{nbsp} |Sets the discovery types for requested URI discovery for requests arriving on the socket. +Allowed values: + +- `FORWARDED`: The `io.helidon.http.Header#FORWARDED` header is used to discover the original requested URI. +- `X_FORWARDED`: The +`io.helidon.http.Header#X_FORWARDED_PROTO`, +`io.helidon.http.Header#X_FORWARDED_HOST`, +`io.helidon.http.Header#X_FORWARDED_PORT`, +`io.helidon.http.Header#X_FORWARDED_PREFIX` +headers are used to discover the original requested URI. +- `HOST`: This is the default, only the `io.helidon.http.Header#HOST` header is used to discover +requested URI. + + |=== // end::config[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/config/io_helidon_http_encoding_ContentEncodingContext.adoc b/docs/src/main/asciidoc/config/io_helidon_http_encoding_ContentEncodingContext.adoc index fc67019499f..88ae5154b10 100644 --- a/docs/src/main/asciidoc/config/io_helidon_http_encoding_ContentEncodingContext.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_http_encoding_ContentEncodingContext.adoc @@ -43,9 +43,9 @@ Type: link:{javadoc-base-url}/io.helidon.http.encoding/io/helidon/http/encoding/ |key |type |default value |description |`content-encodings` |io.helidon.http.encoding.ContentEncoding[] (service provider interface) |{nbsp} |List of content encodings that should be used. - Encodings configured here have priority over encodings discovered through service loader. +Encodings configured here have priority over encodings discovered through service loader. - List of content encodings to be used (such as `gzip,deflate`) +List of content encodings to be used (such as `gzip,deflate`) |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_http_media_MediaContext.adoc b/docs/src/main/asciidoc/config/io_helidon_http_media_MediaContext.adoc index ffafeed8c35..a12f74de824 100644 --- a/docs/src/main/asciidoc/config/io_helidon_http_media_MediaContext.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_http_media_MediaContext.adoc @@ -44,16 +44,16 @@ Type: link:{javadoc-base-url}/io.helidon.http.media/io/helidon/http/media/MediaC |`fallback` |xref:{rootdir}/config/io_helidon_http_media_MediaContext.adoc[MediaContext] |{nbsp} |Existing context to be used as a fallback for this context. - Media context to use if supports configured on this request cannot provide a good result +Media context to use if supports configured on this request cannot provide a good result |`media-supports` |io.helidon.http.media.MediaSupport[] (service provider interface) |{nbsp} |Media supports to use. - This instance has priority over provider(s) discovered by service loader. - The providers are used in order of calling this method, where the first support added is the - first one to be queried for readers and writers. +This instance has priority over provider(s) discovered by service loader. +The providers are used in order of calling this method, where the first support added is the +first one to be queried for readers and writers. - Media supports +Media supports |`register-defaults` |boolean |`true` |Should we register defaults of Helidon, such as String media support. - Whether to register default media supports +Whether to register default media supports |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_neo4j_Neo4j.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_neo4j_Neo4j.adoc index 04274bfc301..5f36b7c4ee1 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_neo4j_Neo4j.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_neo4j_Neo4j.adoc @@ -54,6 +54,13 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.neo4j/io/helidon/integrati |`metrics-enabled` |boolean |{nbsp} |Enable metrics. |`password` |string |{nbsp} |Create password. |`trust-strategy` |TrustStrategy (TRUST_ALL_CERTIFICATES, TRUST_CUSTOM_CA_SIGNED_CERTIFICATES, TRUST_SYSTEM_CA_SIGNED_CERTIFICATES) |{nbsp} |Set trust strategy. + +Allowed values: + +- `TRUST_ALL_CERTIFICATES`: Trust all. +- `TRUST_CUSTOM_CA_SIGNED_CERTIFICATES`: Trust custom certificates. +- `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES`: Trust system CA. + |`uri` |string |{nbsp} |Create uri. |`username` |string |{nbsp} |Create username. diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc index 854dcd47c2a..d69eb150a69 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc @@ -44,10 +44,10 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.oci/io/helidon/integration |`path` |string |{nbsp} |The OCI configuration profile path. - The OCI configuration profile path +The OCI configuration profile path |`profile` |string |`DEFAULT` |The OCI configuration/auth profile name. - The optional OCI configuration/auth profile name +The optional OCI configuration/auth profile name |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc index dad71bd1e1d..1053716e1ec 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc @@ -44,39 +44,38 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.oci/io/helidon/integration |`fingerprint` |string |{nbsp} |The OCI authentication fingerprint. - This configuration property must be provided in order to set the API signing key's fingerprint. - See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. +This configuration property must be provided in order to set the https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm[API signing key's fingerprint]. +See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. - The OCI authentication fingerprint +The OCI authentication fingerprint |`passphrase` |char[] |{nbsp} |The OCI authentication passphrase. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). - The OCI authentication passphrase +The OCI authentication passphrase |`private-key` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |The OCI authentication private key resource. - A resource can be defined as a resource on classpath, file on the file system, - base64 encoded text value in config, or plain-text value in config. +A resource can be defined as a resource on classpath, file on the file system, +base64 encoded text value in config, or plain-text value in config. - If not defined, we will use `.oci/oic_api_key.pem` file in user home directory. +If not defined, we will use `.oci/oic_api_key.pem` file in user home directory. - The OCI authentication key file +The OCI authentication key file |`region` |string |{nbsp} |The OCI region. - The OCI region +The OCI region |`tenant-id` |string |{nbsp} |The OCI tenant id. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getTenantId(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getTenantId(). - The OCI tenant id +The OCI tenant id |`user-id` |string |{nbsp} |The OCI user id. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getUserId(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getUserId(). - The OCI user id +The OCI user id |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ImdsInstanceInfo.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ImdsInstanceInfo.adoc new file mode 100644 index 00000000000..5069d2b45ea --- /dev/null +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_ImdsInstanceInfo.adoc @@ -0,0 +1,75 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2024 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + +ifndef::rootdir[:rootdir: {docdir}/..] +:description: Configuration of io.helidon.integrations.oci.ImdsInstanceInfo +:keywords: helidon, config, io.helidon.integrations.oci.ImdsInstanceInfo +:basic-table-intro: The table below lists the configuration keys that configure io.helidon.integrations.oci.ImdsInstanceInfo +include::{rootdir}/includes/attributes.adoc[] + += ImdsInstanceInfo (integrations.oci) Configuration + +// tag::config[] + + +Type: link:{javadoc-base-url}/io.helidon.integrations.oci/io/helidon/integrations/oci/ImdsInstanceInfo.html[io.helidon.integrations.oci.ImdsInstanceInfo] + + + + +== Configuration options + + + +.Optional configuration options +[cols="3,3a,2,5a"] + +|=== +|key |type |default value |description + +|`canonical-region-name` |string |{nbsp} |Canonical Region Name. + +Canonical Region Name of where the Instance exists +|`compartment-id` |string |{nbsp} |Compartment Id. + +Compartment Id where the Instance was provisioned. +|`display-name` |string |{nbsp} |Display Name. + +Display Name of the Instance +|`fault-domain` |string |{nbsp} |Fault Domain Name. + +Fault Domain Name where the Instance exists +|`host-name` |string |{nbsp} |Host Name. + +Host Name of the Instance +|`json-object` |JsonObject |{nbsp} |Instance Data. + +Full information about the Instance as a jakarta.json.JsonObject +|`oci-ad-name` |string |{nbsp} |Oci Availability Domain Name. + +Physical Availaibility Domain Name where the Instance exists +|`region` |string |{nbsp} |Region Name. + +Short Region Name of where the Instance exists +|`tenant-id` |string |{nbsp} |Tenant Id. + +Tenant Id where the Instance was provisioned. + +|=== + +// end::config[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_OciConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_OciConfig.adoc index 5868fa757b7..3f82d6f30f5 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_OciConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_OciConfig.adoc @@ -44,62 +44,66 @@ This is a standalone configuration type, prefix from configuration root: `helido |=== |key |type |default value |description -|`allowed-atn-methods` |string[] |{nbsp} |List of attempted authentication strategies in case atnMethod() is set to ATN_METHOD_AUTO. +|`allowed-authentication-methods` |string[] |{nbsp} |List of attempted authentication strategies in case io.helidon.integrations.oci.OciConfig.authenticationMethod() is +set to AUTHENTICATION_METHOD_AUTO. - In case the list is empty, all available strategies will be tried, ordered by their io.helidon.common.Weight +In case the list is empty, all available strategies will be tried, ordered by their io.helidon.common.Weight - List of authentication strategies to be tried - See atnMethod() -|`atn-method` |string |`auto` |Authentication method to use. If the configured method is not available, an exception - would be thrown for OCI related services. +List of authentication strategies to be tried +See io.helidon.integrations.oci.OciConfig.authenticationMethod() +|`authentication-method` |string |`auto` |Authentication method to use. If the configured method is not available, an exception +would be thrown for OCI related services. - Known and supported authentication strategies for public OCI: +Known and supported authentication strategies for public OCI: -- ATN_METHOD_AUTO - use the list of allowedAtnMethods() (in the provided order), and choose - the first one - capable of providing data +- AUTHENTICATION_METHOD_AUTO - use the list of + io.helidon.integrations.oci.OciConfig.allowedAuthenticationMethods() + (in the provided order), and choose the first one capable of providing data - AuthenticationMethodConfig.METHOD - - use configuration of the application to obtain values needed to set up connectivity, uses - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider + use configuration of the application to obtain values needed to set up connectivity, uses + com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider - AuthenticationMethodConfigFile.METHOD - use configuration file of OCI (`home/.oci/config`), uses - com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider + com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider - `resource-principal` - use identity of the OCI resource the service is executed on - (fn), uses - com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider, and is available in a - separate module `helidon-integrations-oci-authentication-resource` + (fn), uses + com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider, and is available in a + separate module `helidon-integrations-oci-authentication-resource` - `instance-principal` - use identity of the OCI instance the service is running on, uses - com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider, and is available in a - separate module `helidon-integrations-oci-authentication-resource` + com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider, and is available in a + separate module `helidon-integrations-oci-authentication-resource` - `workload` - use workload identity of the OCI Kubernetes workload, available in a - separate module `helidon-integrations-oci-authentication-workload` + separate module `helidon-integrations-oci-authentication-workload` The authentication method to apply -|`atn-timeout` |Duration |`PT10S` |Timeout of authentication operations, where applicable. - This is a timeout for each operation (if there are retries, each timeout will be this duration). - Defaults to 10 seconds. +|`authentication-timeout` |Duration |`PT10S` |Timeout of authentication operations, where applicable. +This is a timeout for each operation (if there are retries, each timeout will be this duration). +Defaults to 10 seconds. - Authentication operation timeout +Authentication operation timeout |`authentication.config` |xref:{rootdir}/config/io_helidon_integrations_oci_ConfigMethodConfig.adoc[ConfigMethodConfig] |{nbsp} |Config method configuration (if provided and used). - Information needed for config atnMethod() +Information needed for config io.helidon.integrations.oci.OciConfig.authenticationMethod() |`authentication.config-file` |xref:{rootdir}/config/io_helidon_integrations_oci_ConfigFileMethodConfig.adoc[ConfigFileMethodConfig] |{nbsp} |Config file method configuration (if provided and used). - Information to customize config for atnMethod() +Information to customize config for io.helidon.integrations.oci.OciConfig.authenticationMethod() |`authentication.session-token` |xref:{rootdir}/config/io_helidon_integrations_oci_SessionTokenMethodConfig.adoc[SessionTokenMethodConfig] |{nbsp} |Session token method configuration (if provided and used). - Information to customize config for atnMethod() +Information to customize config for io.helidon.integrations.oci.OciConfig.authenticationMethod() |`imds-base-uri` |URI |{nbsp} |The OCI IMDS URI (http URL pointing to the metadata service, if customization needed). - The OCI IMDS URI -|`imds-timeout` |Duration |`PT0.1S` |The OCI IMDS connection timeout. This is used to auto-detect availability. +The OCI IMDS URI +|`imds-detect-retries` |int |{nbsp} |Customize the number of retries to contact IMDS service. - This configuration property is used when attempting to connect to the metadata service. +Number of retries, each provider has its own defaults +|`imds-timeout` |Duration |`PT1S` |The OCI IMDS connection timeout. This is used to auto-detect availability. - The OCI IMDS connection timeout +This configuration property is used when attempting to connect to the metadata service. + +The OCI IMDS connection timeout |`region` |Region |{nbsp} |Explicit region. The configured region will be used by region provider. - This may be ignored by authentication detail providers, as in most cases region is provided by them. +This may be ignored by authentication detail providers, as in most cases region is provided by them. - Explicit region +Explicit region |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_SessionTokenMethodConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_SessionTokenMethodConfig.adoc index 903dd8898c7..f54e475e444 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_SessionTokenMethodConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_SessionTokenMethodConfig.adoc @@ -44,62 +44,61 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.oci/io/helidon/integration |`fingerprint` |string |{nbsp} |The OCI authentication fingerprint. - This configuration property must be provided in order to set the API signing key's fingerprint. - See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. +This configuration property must be provided in order to set the https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm[API signing key's fingerprint]. +See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. - The OCI authentication fingerprint +The OCI authentication fingerprint |`initial-refresh-delay` |Duration |{nbsp} |Delay of the first refresh. - Defaults to 0, to refresh immediately (implemented in the authentication details provider). +Defaults to 0, to refresh immediately (implemented in the authentication details provider). - Initial refresh delay - See SessionTokenAuthenticationDetailsProviderBuilder.initialRefreshDelay(long) +Initial refresh delay +See com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider.SessionTokenAuthenticationDetailsProviderBuilder.initialRefreshDelay(long) |`passphrase` |char[] |{nbsp} |The OCI authentication passphrase. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). - The OCI authentication passphrase +The OCI authentication passphrase |`private-key-path` |Path |{nbsp} |The OCI authentication private key resource. - A resource can be defined as a resource on classpath, file on the file system, - base64 encoded text value in config, or plain-text value in config. +A resource can be defined as a resource on classpath, file on the file system, +base64 encoded text value in config, or plain-text value in config. - If not defined, we will use `".oci/sessions/DEFAULT/oci_api_key.pem` file in user home directory. +If not defined, we will use `".oci/sessions/DEFAULT/oci_api_key.pem` file in user home directory. - The OCI authentication key file +The OCI authentication key file |`refresh-period` |Duration |{nbsp} |Refresh period, i.e. how often refresh occurs. - Defaults to 55 minutes (implemented in the authentication details provider). +Defaults to 55 minutes (implemented in the authentication details provider). - Refresh period - See SessionTokenAuthenticationDetailsProviderBuilder.refreshPeriod(long) +Refresh period +See com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider.SessionTokenAuthenticationDetailsProviderBuilder.refreshPeriod(long) |`region` |string |{nbsp} |The OCI region. - The OCI region +The OCI region |`session-lifetime-hours` |long |{nbsp} |Maximal lifetime of a session. - Defaults to (and maximum is) 24 hours. - Can only be set to a lower value. +Defaults to (and maximum is) 24 hours. +Can only be set to a lower value. - Lifetime of a session in hours +Lifetime of a session in hours |`session-token` |string |{nbsp} |Session token value. - If both this value, and sessionTokenPath() is defined, this value is used. +If both this value, and sessionTokenPath() is defined, this value is used. - Session token +Session token |`session-token-path` |Path |{nbsp} |Session token path. - If both this value, and sessionToken() is defined, the value of sessionToken() is used. +If both this value, and sessionToken() is defined, the value of sessionToken() is used. - Session token path +Session token path |`tenant-id` |string |{nbsp} |The OCI tenant id. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getTenantId(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getTenantId(). - The OCI tenant id +The OCI tenant id |`user-id` |string |{nbsp} |The OCI user id. - This property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getUserId(). +This property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getUserId(). - The OCI user id +The OCI user id |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_metrics_OciMetricsSupport.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_metrics_OciMetricsSupport.adoc index b75534ef5a4..4a2ca3977e1 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_metrics_OciMetricsSupport.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_metrics_OciMetricsSupport.adoc @@ -43,29 +43,29 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.oci.metrics/io/helidon/int |key |type |default value |description |`batch-delay` |long |`1` |Sets the delay interval if metrics are posted in batches - (defaults to DEFAULT_BATCH_DELAY). +(defaults to DEFAULT_BATCH_DELAY). |`batch-size` |int |`50` |Sets the maximum no. of metrics to send in a batch - (defaults to DEFAULT_BATCH_SIZE). +(defaults to DEFAULT_BATCH_SIZE). |`compartment-id` |string |{nbsp} |Sets the compartment ID. |`delay` |long |`60` |Sets the delay interval between metric posting - (defaults to DEFAULT_SCHEDULER_DELAY). +(defaults to DEFAULT_SCHEDULER_DELAY). |`description-enabled` |boolean |`true` |Sets whether the description should be enabled or not. - Defaults to `true`. - + Defaults to `true`. + |`enabled` |boolean |`true` |Sets whether metrics transmission to OCI is enabled. - Defaults to `true`. - + Defaults to `true`. + |`initial-delay` |long |`1` |Sets the initial delay before metrics are sent to OCI - (defaults to DEFAULT_SCHEDULER_INITIAL_DELAY). +(defaults to DEFAULT_SCHEDULER_INITIAL_DELAY). |`namespace` |string |{nbsp} |Sets the namespace. |`resource-group` |string |{nbsp} |Sets the resource group. |`scheduling-time-unit` |TimeUnit (NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS) |`TimeUnit.SECONDS` |Sets the time unit applied to the initial delay and delay values (defaults to `TimeUnit.SECONDS`). |`scopes` |String[] |`All scopes` |Sets which metrics scopes (e.g., base, vendor, application) should be sent to OCI. - If this method is never invoked, defaults to all scopes. - + If this method is never invoked, defaults to all scopes. + |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_sdk_runtime_OciConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_sdk_runtime_OciConfig.adoc index d3f52799a44..ea125b939c9 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_sdk_runtime_OciConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_sdk_runtime_OciConfig.adoc @@ -45,135 +45,152 @@ This is a standalone configuration type, prefix from configuration root: `oci` |key |type |default value |description |`auth-strategies` |string[] (auto, config, config-file, instance-principals, resource-principal) |{nbsp} |The list of authentication strategies that will be attempted by - com.oracle.bmc.auth.BasicAuthenticationDetailsProvider when one is - called for. This is only used if authStrategy() is not present. +com.oracle.bmc.auth.AbstractAuthenticationDetailsProvider when one is +called for. This is only used if authStrategy() is not present. - `auto` - if present in the list, or if no value - for this property exists. + for this property exists. - `config` - the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider - will be used, customized with other configuration - properties described here. + com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider + will be used, customized with other configuration + properties described here. - `config-file` - the - com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider - will be used, customized with other configuration - properties described here. + com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider + will be used, customized with other configuration + properties described here. - `instance-principals` - the - com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider - will be used. + com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider + will be used. - `resource-principal` - the - com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider - will be used. + com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider + will be used. If there are more than one strategy descriptors defined, the - first one that is deemed to be available/suitable will be used and all others will be ignored. +first one that is deemed to be available/suitable will be used and all others will be ignored. + +The list of authentication strategies that will be applied, defaulting to `auto` +See io.helidon.integrations.oci.sdk.runtime.OciAuthenticationDetailsProvider.AuthStrategy + +Allowed values: + +- `auto`: auto select first applicable +- `config`: simple authentication provider +- `config-file`: config file authentication provider +- `instance-principals`: instance principals authentication provider +- `resource-principal`: resource principal authentication provider - The list of authentication strategies that will be applied, defaulting to `auto` - See io.helidon.integrations.oci.sdk.runtime.OciAuthenticationDetailsProvider.AuthStrategy |`auth-strategy` |string (auto, config, config-file, instance-principals, resource-principal) |{nbsp} |The singular authentication strategy to apply. This will be preferred over authStrategies() if both are - present. +present. + +The singular authentication strategy to be applied + +Allowed values: + +- `auto`: auto select first applicable +- `config`: simple authentication provider +- `config-file`: config file authentication provider +- `instance-principals`: instance principals authentication provider +- `resource-principal`: resource principals authentication provider - The singular authentication strategy to be applied |`auth.fingerprint` |string |{nbsp} |The OCI authentication fingerprint. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the API signing key's fingerprint. - See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm[API signing key's fingerprint]. +See com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getFingerprint() for more details. - The OCI authentication fingerprint +The OCI authentication fingerprint |`auth.keyFile` |string |`oci_api_key.pem` |The OCI authentication key file. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). This file must exist in the - `user.home` directory. Alternatively, this property can be set using either authPrivateKey() or - using authPrivateKeyPath(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). This file must exist in the +`user.home` directory. Alternatively, this property can be set using either authPrivateKey() or +using authPrivateKeyPath(). - The OCI authentication key file +The OCI authentication key file |`auth.passphrase` |char[] |{nbsp} |The OCI authentication passphrase. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPassphraseCharacters(). - The OCI authentication passphrase +The OCI authentication passphrase |`auth.private-key` |char[] |{nbsp} |The OCI authentication private key. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). Alternatively, this property - can be set using either authKeyFile() residing in the `user.home` directory, or using - authPrivateKeyPath(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). Alternatively, this property +can be set using either authKeyFile() residing in the `user.home` directory, or using +authPrivateKeyPath(). - The OCI authentication private key +The OCI authentication private key |`auth.private-key-path` |string |{nbsp} |The OCI authentication key file path. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). This file path is - an alternative for using authKeyFile() where the file must exist in the `user.home` directory. - Alternatively, this property can be set using authPrivateKey(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.SimpleAuthenticationDetailsProvider.getPrivateKey(). This file path is +an alternative for using authKeyFile() where the file must exist in the `user.home` directory. +Alternatively, this property can be set using authPrivateKey(). - The OCI authentication key file path +The OCI authentication key file path |`auth.region` |string |{nbsp} |The OCI region. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, either this property or com.oracle.bmc.auth.RegionProvider must be provide a value in order - to set the com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getRegion(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, either this property or com.oracle.bmc.auth.RegionProvider must be provide a value in order +to set the com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getRegion(). - The OCI region +The OCI region |`auth.tenant-id` |string |{nbsp} |The OCI tenant id. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getTenantId(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getTenantId(). - The OCI tenant id +The OCI tenant id |`auth.user-id` |string |{nbsp} |The OCI user id. - This configuration property has an effect only when `config` is, explicitly or implicitly, - present in the value for the authStrategies(). - When it is present, this property must be provided in order to set the - com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getUserId(). +This configuration property has an effect only when `config` is, explicitly or implicitly, +present in the value for the authStrategies(). +When it is present, this property must be provided in order to set the +com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider.getUserId(). - The OCI user id +The OCI user id |`config.path` |string |{nbsp} |The OCI configuration profile path. - This configuration property has an effect only when `config-file` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). - When it is present, this property must also be present and then the - com.oracle.bmc.ConfigFileReader.parse(String) - method will be passed this value. It is expected to be passed with a - valid OCI configuration file path. +This configuration property has an effect only when `config-file` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). +When it is present, this property must also be present and then the +com.oracle.bmc.ConfigFileReader.parse(String) +method will be passed this value. It is expected to be passed with a +valid OCI configuration file path. - The OCI configuration profile path +The OCI configuration profile path |`config.profile` |string |`DEFAULT` |The OCI configuration/auth profile name. - This configuration property has an effect only when `config-file` is, explicitly or implicitly, - present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). - When it is present, this property may also be optionally provided in order to override the default - DEFAULT_PROFILE_NAME. +This configuration property has an effect only when `config-file` is, explicitly or implicitly, +present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). +When it is present, this property may also be optionally provided in order to override the default +DEFAULT_PROFILE_NAME. - The optional OCI configuration/auth profile name +The optional OCI configuration/auth profile name |`imds.hostname` |string |`169.254.169.254` |The OCI IMDS hostname. - This configuration property is used to identify the metadata service url. +This configuration property is used to identify the metadata service url. - The OCI IMDS hostname +The OCI IMDS hostname |`imds.timeout.milliseconds` |Duration |`PT0.1S` |The OCI IMDS connection timeout. This is used to auto-detect availability. - This configuration property is used when attempting to connect to the metadata service. +This configuration property is used when attempting to connect to the metadata service. - The OCI IMDS connection timeout - See OciAvailability +The OCI IMDS connection timeout +See OciAvailability |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_tls_certificates_OciCertificatesTlsManager.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_tls_certificates_OciCertificatesTlsManager.adoc index 3cac3de9438..e2727ce4d68 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_oci_tls_certificates_OciCertificatesTlsManager.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_oci_tls_certificates_OciCertificatesTlsManager.adoc @@ -44,32 +44,32 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.oci.tls.certificates/io/he |`ca-ocid` |string |{nbsp} |The Certificate Authority OCID. - Certificate authority OCID +Certificate authority OCID |`cert-ocid` |string |{nbsp} |The Certificate OCID. - Certificate OCID +Certificate OCID |`compartment-ocid` |string |{nbsp} |The OCID of the compartment the services are in. - The compartment OCID +The compartment OCID |`key-ocid` |string |{nbsp} |The Key OCID. - Key OCID +Key OCID |`key-password` |Supplier |{nbsp} |The Key password. - Key password +Key password |`schedule` |string |{nbsp} |The schedule for trigger a reload check, testing whether there is a new io.helidon.common.tls.Tls instance - available. +available. - The schedule for reload +The schedule for reload |`vault-crypto-endpoint` |URI |{nbsp} |The address to use for the OCI Key Management Service / Vault crypto usage. - Each OCI Vault has public crypto and management endpoints. We need to specify the crypto endpoint of the vault we are - rotating the private keys in. The implementation expects both client and server to store the private key in the same vault. +Each OCI Vault has public crypto and management endpoints. We need to specify the crypto endpoint of the vault we are +rotating the private keys in. The implementation expects both client and server to store the private key in the same vault. - The address for the key management service / vault crypto usage +The address for the key management service / vault crypto usage |`vault-management-endpoint` |URI |{nbsp} |The address to use for the OCI Key Management Service / Vault management usage. - The crypto endpoint of the vault we are rotating the private keys in. +The crypto endpoint of the vault we are rotating the private keys in. - The address for the key management service / vault management usage +The address for the key management service / vault management usage |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_integrations_openapi_ui_OpenApiUi.adoc b/docs/src/main/asciidoc/config/io_helidon_integrations_openapi_ui_OpenApiUi.adoc index 53fd3897ad5..b03520e095d 100644 --- a/docs/src/main/asciidoc/config/io_helidon_integrations_openapi_ui_OpenApiUi.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_integrations_openapi_ui_OpenApiUi.adoc @@ -44,13 +44,13 @@ Type: link:{javadoc-base-url}/io.helidon.integrations.openapi.ui/io/helidon/inte |`enabled` |boolean |`true` |Sets whether the service should be enabled. - `true` if enabled, `false` otherwise +`true` if enabled, `false` otherwise |`options` |Map<string, string> |{nbsp} |Merges implementation-specific UI options. - Options for the UI to merge +Options for the UI to merge |`web-context` |string |{nbsp} |Full web context (not just the suffix). - Full web context path +Full web context path |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc index 64b33e47f53..9b1de363e07 100644 --- a/docs/src/main/asciidoc/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc @@ -44,10 +44,10 @@ Type: link:{javadoc-base-url}/io.helidon.metrics.api/io/helidon/metrics/api/KeyP |`extended` |boolean |`false` |Whether KPI extended metrics are enabled. - True if KPI extended metrics are enabled; false otherwise +True if KPI extended metrics are enabled; false otherwise |`long-running-requests.threshold` |Duration |`PT10S` |Threshold in ms that characterizes whether a request is long running. - Threshold in ms indicating a long-running request +Threshold in ms indicating a long-running request |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_metrics_api_MetricsConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_metrics_api_MetricsConfig.adoc index 81cfc79293f..e08d5a5b043 100644 --- a/docs/src/main/asciidoc/config/io_helidon_metrics_api_MetricsConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_metrics_api_MetricsConfig.adoc @@ -46,32 +46,32 @@ This is a standalone configuration type, prefix from configuration root: `metric |`app-name` |string |{nbsp} |Value for the application tag to be added to each meter ID. - Application tag value +Application tag value |`app-tag-name` |string |{nbsp} |Name for the application tag to be added to each meter ID. - Application tag name +Application tag name |`enabled` |boolean |`true` |Whether metrics functionality is enabled. - If metrics are configured to be enabled +If metrics are configured to be enabled |`key-performance-indicators` |xref:{rootdir}/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc[KeyPerformanceIndicatorMetricsConfig] |{nbsp} |Key performance indicator metrics settings. - Key performance indicator metrics settings +Key performance indicator metrics settings |`permit-all` |boolean |`true` |Whether to allow anybody to access the endpoint. - Whether to permit access to metrics endpoint to anybody, defaults to `true` - @see #roles() +Whether to permit access to metrics endpoint to anybody, defaults to `true` +See roles() |`rest-request-enabled` |boolean |`false` |Whether automatic REST request metrics should be measured. - True/false +True/false |`roles` |string[] |`observe` |Hints for role names the user is expected to be in. - List of hints +List of hints |`scoping` |xref:{rootdir}/config/io_helidon_metrics_api_ScopingConfig.adoc[ScopingConfig] |{nbsp} |Settings related to scoping management. - Scoping settings +Scoping settings |`tags` |xref:{rootdir}/config/io_helidon_metrics_api_Tag.adoc[Tag[]] |{nbsp} |Global tags. - Name/value pairs for global tags +Name/value pairs for global tags |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopeConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopeConfig.adoc index f1caf5e0661..633a78c55d2 100644 --- a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopeConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopeConfig.adoc @@ -44,16 +44,16 @@ Type: link:{javadoc-base-url}/io.helidon.metrics.api/io/helidon/metrics/api/Scop |`enabled` |boolean |`true` |Whether the scope is enabled. - If the scope is enabled +If the scope is enabled |`filter.exclude` |Pattern |{nbsp} |Regular expression for meter names to exclude. - Exclude expression +Exclude expression |`filter.include` |Pattern |{nbsp} |Regular expression for meter names to include. - Include expression +Include expression |`name` |string |{nbsp} |Name of the scope to which the configuration applies. - Scope name +Scope name |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopingConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopingConfig.adoc index a746c09d1bf..66647f2d924 100644 --- a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopingConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_metrics_api_ScopingConfig.adoc @@ -43,15 +43,15 @@ Type: link:{javadoc-base-url}/io.helidon.metrics.api/io/helidon/metrics/api/Scop |key |type |default value |description |`default` |string |`application` |Default scope value to associate with meters that are registered without an explicit setting; no setting means meters - are assigned scope io.helidon.metrics.api.Meter.Scope.DEFAULT. +are assigned scope io.helidon.metrics.api.Meter.Scope.DEFAULT. - Default scope value +Default scope value |`scopes` |xref:{rootdir}/config/io_helidon_metrics_api_ScopeConfig.adoc[Map<string, ScopeConfig>] |{nbsp} |Settings for individual scopes. - Scope settings +Scope settings |`tag-name` |string |`scope` |Tag name for storing meter scope values in the underlying implementation meter registry. - Tag name for storing scope values +Tag name for storing scope values |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt.adoc b/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt.adoc deleted file mode 100644 index f5b07663852..00000000000 --- a/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt.adoc +++ /dev/null @@ -1,90 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2022, 2023 Oracle and/or its affiliates. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - -/////////////////////////////////////////////////////////////////////////////// - -// MANUALLY CREATED DOC - -ifndef::rootdir[:rootdir: {docdir}/..] -:description: Configuration of io.helidon.microprofile.jwt -:keywords: helidon, security, jwt, microprofile -:basic-table-intro: The table below lists the configuration keys that configure io.helidon.microprofile.jwt.adoc -include::{rootdir}/includes/attributes.adoc[] - -= JWT Configuration - -// tag::config[] - -== Configuration options - - -.MicroProfile configuration options: -[cols="3,3,2,5a"] - -|=== -|key |type |default value |description - -|`mp.jwt.verify.publickey` |string |{nbsp} |The property allows the Public Verification Key text itself to be supplied as a string. -|`mp.jwt.verify.publickey.location` |string |{nbsp} |The property allows for an external or internal location of Public Verification Key to be specified. The value may be a relative path or a URL. -|`mp.jwt.verify.publickey.algorithm` |string |{nbsp} |The configuration property allows for specifying which Public Key Signature Algorithm is supported by the MP JWT endpoint. This property can be set to either `RS256` or `ES256`. Default value is `RS256`. Support for the other asymmetric signature algorithms such as `RS512`, `ES512` and others is optional. -|`mp.jwt.verify.issuer` |string |{nbsp} |Configuration key for expected issuer of incoming tokens. -|`mp.jwt.verify.audiences` |string |{nbsp} |Configuration key for expected audiences of incoming tokens. -|`mp.jwt.verify.token.age` |int |{nbsp} |Max number of seconds since token issue time. If this number of second accedes configured value, validation will fail. -|`mp.jwt.verify.clock.skew` |int |{nbsp} |Number of seconds for the clock skew during the token age verification and expiry. -|`mp.jwt.token.cookie` |string |{nbsp} |Cookie property name which is expected to contain a JWT token. -|`mp.jwt.token.header` |string |{nbsp} |Header name which is expected to contain a JWT token. -|`mp.jwt.decrypt.key.location` |string |{nbsp} |The property allows for an external or internal location of Private Decryption Key to be specified. The value may be a relative path or a URL. -|`mp.jwt.decrypt.key.algorithm` |string |{nbsp} |The configuration property allows for specifying which key management algorithm is supported by the MP JWT endpoint. Supported algorithms are either `RSA-OAEP` or `RSA-OAEP-256`. If no algorithm is set, both algorithms must be accepted. - -|=== - -.Helidon configuration options: -[cols="3,3,2,5a"] - -|=== -|key |type |default value |description - -|`optional` |boolean |`false` |If set to `true`, failure to authenticate will return `ABSTAIN` result instead of `FAILURE`. This is -an important distinction when more than one provider is used -|`authenticate` |boolean |`true` |Whether to attempt authentication -|`propagate`|boolean |`true` |Whether to attempt identity propagation/JWT creation -|`principal-type`|string |`USER` |Whether we authenticate a user or a service (other option is SERVICE) -|`atn-token` |string |{nbsp} |A group for configuring authentication of the request -|`atn-token.verify-signature`|boolean |`true` |Whether to verify signature in incoming JWT. If disabled, _ANY_ JWT will be accepted -|`atn-token.jwt-audience`|string |{nbsp} |Expected audience of the JWT. If not defined, any audience is accepted (and we may accept JWT not inteded for us) -|`atn-token.jwk.resource`|xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Configuration of the JWK to obtain key(s) to validate signatures of inbound token. The JWK should contain public keys. -|`atn-token.handler`|string |`Authorization` header with `bearer ` prefix |A handler configuration for inbound token - e.g. how to extract it -|`atn-token.handler.header`|string |{nbsp} |Name of a header the token is expected in -|`atn-token.handler.prefix`|string |{nbsp} |Prefix before the token value (optional) -|`atn-token.handler.regexp`|string |{nbsp} |Regular expression to obtain the token, first matching group is used (optional) -|`sign-token`|string |{nbsp} |A group for configuring outbound security -|`sign-token.jwk.resource`|xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Configuration of the JWK to use when generating tokens (follows the same rules as atn-token.jwk above). The JWK must contain private keys when using asymmetric ciphers. -|`sign-token.jwt-issuer`|string |{nbsp} |When we issue a new token, this is the issuer to be placed into it (validated by target service) -|`sign-token.outbound`|string |{nbsp} |A group for configuring outbound rules (based on transport, host and.or path) -|`sign-token.outbound.*.name`|string |{nbsp} |A short descriptive name for configured target service(s) -|`sign-token.outbound.*.transports`|string |any |An array of transports this outbound matches (e.g. https) -|`sign-token.outbound.*.hosts`|string |any |An array of hosts this outbound matches, may use * as a wild-card (e.g. *.oracle.com) -|`sign-token.outbound.*.paths`|string |any |An array of paths on the host this outbound matches, may use * as a wild-card (e.g. /some/path/*) -|`sign-token.outbound.*.outbound-token`|string |`Authorization` header with `bearer ` prefix |Configuration of outbound token handler (same as atn-token.handler) -|`sign-token.outbound.*.outbound-token.format`|string |{nbsp} |Java text format for generating the value of outbound token header (e.g. "bearer %1$s") -|`sign-token.outbound.*.jwk-kid`|string |{nbsp} |If this key is defined, we are generating a new token, otherwise we propagate existing. Defines the key id of a key definition in the JWK file to use for signing the outbound token -|`sign-token.outbound.*.jwt-kid`|string |{nbsp} |A key to use in the generated JWT - this is for the other service to locate the verification key in their JWK -|`sign-token.outbound.*.jwt-audience`|string |{nbsp} |Audience this key is generated for (e.g. http://www.example.org/api/myService) - validated by the other service -|`sign-token.outbound.*.jwt-not-before-seconds`|string |`5` |Makes this key valid this amount of seconds into the past. Allows a certain time-skew for the generated token to be valid before current time (e.g. when we expect a certain misalignment of clocks) -|`sign-token.outbound.*.jwt-validity-seconds`|string |1 day |Token validity in seconds -|=== - -// end::config[] diff --git a/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc new file mode 100644 index 00000000000..fe409f265d9 --- /dev/null +++ b/docs/src/main/asciidoc/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc @@ -0,0 +1,90 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2024 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + +ifndef::rootdir[:rootdir: {docdir}/..] +:description: Configuration of io.helidon.microprofile.jwt.auth.JwtAuthProvider +:keywords: helidon, config, io.helidon.microprofile.jwt.auth.JwtAuthProvider +:basic-table-intro: The table below lists the configuration keys that configure io.helidon.microprofile.jwt.auth.JwtAuthProvider +include::{rootdir}/includes/attributes.adoc[] + += JwtAuthProvider (microprofile.jwt.auth) Configuration + +// tag::config[] + +MP-JWT Auth configuration is defined by the spec (options prefixed with `mp.jwt.`), and we add a few configuration options for the security provider (options prefixed with `security.providers.mp-jwt-auth.`) + + +Type: link:{javadoc-base-url}/io.helidon.microprofile.jwt.auth/io/helidon/microprofile/jwt/auth/JwtAuthProvider.html[io.helidon.microprofile.jwt.auth.JwtAuthProvider] + + + + +== Configuration options + + + +.Optional configuration options +[cols="3,3a,2,5a"] + +|=== +|key |type |default value |description + +|`mp.jwt.decrypt.key.algorithm` |string (RSA-OAEP, RSA-OAEP-256) |{nbsp} |Expected key management algorithm supported by the MP JWT endpoint. +Supported algorithms are either `RSA-OAEP` or `RSA-OAEP-256`. +If no algorithm is set, both algorithms must be accepted. + +Allowed values: + +- `RSA-OAEP`: RSA-OAEP Algorithm +- `RSA-OAEP-256`: RSA-OAEP-256 Algorithm + +|`mp.jwt.decrypt.key.location` |string |{nbsp} |Private key for decryption of encrypted claims. +The value may be a relative path or a URL. +|`mp.jwt.token.cookie` |string |`Bearer` |Specific cookie property name where we should search for JWT property. +|`mp.jwt.token.header` |string |`Authorization` |Name of the header expected to contain the token. +|`mp.jwt.verify.audiences` |string[] |{nbsp} |Expected audiences of incoming tokens. +|`mp.jwt.verify.clock.skew` |int |`5` |Clock skew to be accounted for in token expiration and max age validations in seconds. +|`mp.jwt.verify.issuer` |string |{nbsp} |Expected issuer in incoming requests. +|`mp.jwt.verify.publickey` |string |{nbsp} |String representation of the public key. +|`mp.jwt.verify.publickey.location` |string |{nbsp} |Path to public key. +The value may be a relative path or a URL. +|`mp.jwt.verify.token.age` |int |{nbsp} |Maximal expected token age in seconds. If this value is set, `iat` claim needs to be present in the JWT. +|`security.providers.mp-jwt-auth.allow-impersonation` |boolean |`false` |Whether to allow impersonation by explicitly overriding +username from outbound requests using io.helidon.security.EndpointConfig.PROPERTY_OUTBOUND_ID +property. +By default this is not allowed and identity can only be propagated. +|`security.providers.mp-jwt-auth.atn-token.default-key-id` |string |{nbsp} |Default JWT key ID which should be used. +|`security.providers.mp-jwt-auth.atn-token.handler` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Token handler to extract username from request. +Uses `Authorization` header with `bearer ` prefix by default. +|`security.providers.mp-jwt-auth.atn-token.jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |JWK resource for authenticating the request +|`security.providers.mp-jwt-auth.atn-token.jwt-audience` |string |{nbsp} |Audience expected in inbound JWTs. +|`security.providers.mp-jwt-auth.atn-token.verify-key` |string |{nbsp} |Path to public key. +The value may be a relative path or a URL. +|`security.providers.mp-jwt-auth.authenticate` |boolean |`true` |Whether to authenticate requests. +|`security.providers.mp-jwt-auth.load-on-startup` |boolean |`false` |Whether to load JWK verification keys on server startup +Default value is `false`. +|`security.providers.mp-jwt-auth.optional` |boolean |`false` |Whether authentication is required. +By default, request will fail if the username cannot be extracted. +If set to false, request will process and this provider will abstain. +|`security.providers.mp-jwt-auth.principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates). +|`security.providers.mp-jwt-auth.propagate` |boolean |`true` |Whether to propagate identity. +|`security.providers.mp-jwt-auth.sign-token` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundConfig.adoc[OutboundConfig] |{nbsp} |Configuration of outbound rules. + +|=== + +// end::config[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/config/io_helidon_microprofile_openapi_MpOpenApiManagerConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_microprofile_openapi_MpOpenApiManagerConfig.adoc index 23d30831f44..fdc573009bf 100644 --- a/docs/src/main/asciidoc/config/io_helidon_microprofile_openapi_MpOpenApiManagerConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_microprofile_openapi_MpOpenApiManagerConfig.adoc @@ -43,9 +43,9 @@ Type: link:{javadoc-base-url}/io.helidon.microprofile.openapi/io/helidon/micropr |key |type |default value |description |`mp.openapi.extensions.helidon.use-jaxrs-semantics` |boolean |{nbsp} |If `true` and the `jakarta.ws.rs.core.Application` class returns a non-empty set, endpoints defined by - other resources are not included in the OpenAPI document. +other resources are not included in the OpenAPI document. - `true` if enabled, `false` otherwise +`true` if enabled, `false` otherwise |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_openapi_OpenApiFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_openapi_OpenApiFeature.adoc index 61f46f41ac7..275d8a67a84 100644 --- a/docs/src/main/asciidoc/config/io_helidon_openapi_OpenApiFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_openapi_OpenApiFeature.adoc @@ -50,36 +50,36 @@ This type provides the following service implementations: |`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |CORS config. - CORS config +CORS config |`enabled` |boolean |`true` |Sets whether the feature should be enabled. - `true` if enabled, `false` otherwise +`true` if enabled, `false` otherwise |`manager` |io.helidon.openapi.OpenApiManager (service provider interface) |{nbsp} |OpenAPI manager. - The OpenAPI manager +The OpenAPI manager |`permit-all` |boolean |`true` |Whether to allow anybody to access the endpoint. - Whether to permit access to metrics endpoint to anybody, defaults to `true` - See roles() +Whether to permit access to metrics endpoint to anybody, defaults to `true` +See roles() |`roles` |string[] |`openapi` |Hints for role names the user is expected to be in. - List of hints +List of hints |`services` |io.helidon.openapi.OpenApiService[] (service provider interface) |{nbsp} |OpenAPI services. - The OpenAPI services +The OpenAPI services |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`static-file` |string |{nbsp} |Path of the static OpenAPI document file. Default types are `json`, `yaml`, and `yml`. - Location of the static OpenAPI document file +Location of the static OpenAPI document file |`web-context` |string |`/openapi` |Web context path for the OpenAPI endpoint. - WebContext to use +WebContext to use |`weight` |double |`90.0` |Weight of the OpenAPI feature. This is quite low, to be registered after routing. - io.helidon.openapi.OpenApiFeature.WEIGHT. +io.helidon.openapi.OpenApiFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_scheduling_Cron.adoc b/docs/src/main/asciidoc/config/io_helidon_scheduling_Cron.adoc index afbb32ab850..f69f9df6925 100644 --- a/docs/src/main/asciidoc/config/io_helidon_scheduling_Cron.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_scheduling_Cron.adoc @@ -41,7 +41,7 @@ Type: link:{javadoc-base-url}/io.helidon.scheduling/io/helidon/scheduling/Cron.h |`expression` |string |{nbsp} |Cron expression for specifying period of execution. - Examples: +*Examples:* - `0/2 * * * * ? *` - Every 2 seconds - `0 45 9 ? * *` - Every day at 9:45 @@ -60,9 +60,9 @@ Cron expression |key |type |default value |description |`concurrent` |boolean |`true` |Allow concurrent execution if previous task didn't finish before next execution. - Default value is `true`. +Default value is `true`. - True for allow concurrent execution. +True for allow concurrent execution. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_scheduling_FixedRate.adoc b/docs/src/main/asciidoc/config/io_helidon_scheduling_FixedRate.adoc index 301fd9df2f1..d494d3bcb7e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_scheduling_FixedRate.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_scheduling_FixedRate.adoc @@ -40,9 +40,9 @@ Type: link:{javadoc-base-url}/io.helidon.scheduling/io/helidon/scheduling/FixedR |key |type |default value |description |`delay` |long |{nbsp} |Fixed rate delay between each invocation. Time unit is by default java.util.concurrent.TimeUnit.SECONDS, - can be specified with io.helidon.scheduling.FixedRateConfig.Builder.timeUnit(java.util.concurrent.TimeUnit). +can be specified with io.helidon.scheduling.FixedRateConfig.Builder.timeUnit(java.util.concurrent.TimeUnit). - Delay between each invocation +Delay between each invocation |=== @@ -54,22 +54,28 @@ Type: link:{javadoc-base-url}/io.helidon.scheduling/io/helidon/scheduling/FixedR |=== |key |type |default value |description -|`delay-type` |DelayType |`DelayType.SINCE_PREVIOUS_START` |Configure whether the delay between the invocations should be calculated from the time when previous task started or ended. - Delay type is by default FixedRate.DelayType.SINCE_PREVIOUS_START. +|`delay-type` |DelayType (SINCE_PREVIOUS_START, SINCE_PREVIOUS_END) |`DelayType.SINCE_PREVIOUS_START` |Configure whether the delay between the invocations should be calculated from the time when previous task started or ended. +Delay type is by default FixedRate.DelayType.SINCE_PREVIOUS_START. + +Delay type + +Allowed values: + +- `SINCE_PREVIOUS_START`: Next invocation delay is measured from the previous invocation task start. +- `SINCE_PREVIOUS_END`: Next invocation delay is measured from the previous invocation task end. - Delay type |`initial-delay` |long |`0` |Initial delay of the first invocation. Time unit is by default java.util.concurrent.TimeUnit.SECONDS, - can be specified with - io.helidon.scheduling.FixedRateConfig.Builder.timeUnit(java.util.concurrent.TimeUnit) timeUnit(). +can be specified with +io.helidon.scheduling.FixedRateConfig.Builder.timeUnit(java.util.concurrent.TimeUnit) timeUnit(). - Initial delay value -|`time-unit` |TimeUnit |`TimeUnit.TimeUnit.SECONDS` |java.util.concurrent.TimeUnit TimeUnit used for interpretation of values provided with - io.helidon.scheduling.FixedRateConfig.Builder.delay(long) - and io.helidon.scheduling.FixedRateConfig.Builder.initialDelay(long). +Initial delay value +|`time-unit` |TimeUnit (NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS) |`TimeUnit.TimeUnit.SECONDS` |java.util.concurrent.TimeUnit TimeUnit used for interpretation of values provided with +io.helidon.scheduling.FixedRateConfig.Builder.delay(long) +and io.helidon.scheduling.FixedRateConfig.Builder.initialDelay(long). - Time unit for interpreting values - in io.helidon.scheduling.FixedRateConfig.Builder.delay(long) - and io.helidon.scheduling.FixedRateConfig.Builder.initialDelay(long) +Time unit for interpreting values + in io.helidon.scheduling.FixedRateConfig.Builder.delay(long) + and io.helidon.scheduling.FixedRateConfig.Builder.initialDelay(long) |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_Security.adoc b/docs/src/main/asciidoc/config/io_helidon_security_Security.adoc index 7aa7f794246..dc0be6f755b 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_Security.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_Security.adoc @@ -48,6 +48,7 @@ This is a standalone configuration type, prefix from configuration root: `securi Such as: - xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc[idcs-role-mapper (IdcsRoleMapperProvider)] + - xref:{rootdir}/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc[config-vault (ConfigVaultProvider)] - xref:{rootdir}/config/io_helidon_security_providers_jwt_JwtProvider.adoc[jwt (JwtProvider)] - xref:{rootdir}/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc[http-basic-auth (HttpBasicAuthProvider)] - xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc[idcs-role-mapper (IdcsMtRoleMapperProvider)] @@ -58,7 +59,7 @@ Such as: - xref:{rootdir}/config/io_helidon_security_providers_abac_AbacProvider.adoc[abac (AbacProvider)] |{nbsp} |Add a provider, works as addProvider(io.helidon.security.spi.SecurityProvider, String), where the name is set - to `Class#getSimpleName()`. +to `Class#getSimpleName()`. |=== @@ -73,14 +74,29 @@ Such as: |`default-authentication-provider` |string (service provider interface) |{nbsp} |ID of the default authentication provider |`default-authorization-provider` |string |{nbsp} |ID of the default authorization provider |`enabled` |boolean |`true` |Security can be disabled using configuration, or explicitly. - By default, security instance is enabled. - Disabled security instance will not perform any checks and allow - all requests. +By default, security instance is enabled. +Disabled security instance will not perform any checks and allow +all requests. |`environment.server-time` |xref:{rootdir}/config/io_helidon_security_SecurityTime.adoc[SecurityTime] |{nbsp} |Server time to use when evaluating security policies that depend on time. |`provider-policy.class-name` |Class |{nbsp} |Provider selection policy class name, only used when type is set to CLASS |`provider-policy.type` |ProviderSelectionPolicyType (FIRST, COMPOSITE, CLASS) |`FIRST` |Type of the policy. + +Allowed values: + +- `FIRST`: Choose first provider from the list by default. +Choose provider with the name defined when explicit provider requested. +- `COMPOSITE`: Can compose multiple providers together to form a single +logical provider. +- `CLASS`: Explicit class for a custom ProviderSelectionPolicyType. + |`secrets` |Map<string, string> (documented for specific cases) |{nbsp} |Configured secrets -|`secrets.*.config` |io.helidon.security.SecretsProviderConfig (service provider interface) |{nbsp} |Configuration specific to the secret provider +|`secrets.*.config` |io.helidon.security.SecretsProviderConfig (service provider interface) + +Such as: + + - xref:{rootdir}/config/io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc[SecretConfig] + + |{nbsp} |Configuration specific to the secret provider |`secrets.*.name` |string |{nbsp} |Name of the secret, used for lookup |`secrets.*.provider` |string |{nbsp} |Name of the secret provider |`tracing.enabled` |boolean |`true` |Whether or not tracing should be enabled. If set to false, security tracer will be a no-op tracer. diff --git a/docs/src/main/asciidoc/config/io_helidon_security_SecurityTime.adoc b/docs/src/main/asciidoc/config/io_helidon_security_SecurityTime.adoc index e698c1b2fab..a5b7eeab695 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_SecurityTime.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_SecurityTime.adoc @@ -51,8 +51,8 @@ Type: link:{javadoc-base-url}/io.helidon.security/io/helidon/security/SecurityTi |`shift-by-seconds` |long |`0` |Configure a time-shift in seconds, to move the current time to past or future. |`time-zone` |ZoneId |{nbsp} |Override current time zone. The time will represent the SAME instant, in an explicit timezone. - If we are in a UTC time zone and you set the timezone to "Europe/Prague", the time will be shifted by the offset - of Prague (e.g. if it is noon right now in UTC, you would get 14:00). +If we are in a UTC time zone and you set the timezone to "Europe/Prague", the time will be shifted by the offset +of Prague (e.g. if it is noon right now in UTC, you would get 14:00). |`year` |long |{nbsp} |Set an explicit value for one of the time fields (such as ChronoField.YEAR). |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_common_EvictableCache.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_common_EvictableCache.adoc index e58103fa272..bc02a878aed 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_common_EvictableCache.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_common_EvictableCache.adoc @@ -43,14 +43,14 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.common/io/helidon/se |key |type |default value |description |`cache-enabled` |boolean |`true` |If the cacheEnabled is set to false, no caching will be done. - Otherwise (default behavior) evictable caching will be used. +Otherwise (default behavior) evictable caching will be used. |`cache-evict-delay-millis` |long |`60000` |Delay from the creation of the cache to first eviction |`cache-evict-period-millis` |long |`300000` |How often to evict records |`cache-overall-timeout-millis` |long |`3600000` |Configure record timeout since its creation. |`cache-timeout-millis` |long |`3600000` |Configure record timeout since last access. |`evictor-class` |Class |{nbsp} |Configure evictor to check if a record is still valid. - This should be a fast way to check, as it is happening in a ConcurrentHashMap.forEachKey(long, Consumer). - This is also called during all get and remove operations to only return valid records. +This should be a fast way to check, as it is happening in a ConcurrentHashMap.forEachKey(long, Consumer). +This is also called during all get and remove operations to only return valid records. |`max-size` |long |`100000` |Configure maximal cache size. |`parallelism-threshold` |long |`10000` |Configure parallelism threshold. diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_common_OutboundTarget.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_common_OutboundTarget.adoc index b89ca777630..3c9e2cec3b0 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_common_OutboundTarget.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_common_OutboundTarget.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2023 Oracle and/or its affiliates. + Copyright (c) 2023, 2024 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -53,31 +53,31 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.common/io/helidon/se |`hosts` |string[] |{nbsp} |Add supported host for this target. May be called more than once to add more hosts. - Valid examples: +Valid examples: - localhost - + - www.google.com - + - 127.0.0.1 - + - *.oracle.com - + - 192.169.*.* - + - *.google.* |`methods` |string[] |{nbsp} |Add supported method for this target. May be called more than once to add more methods. - The method is tested as is ignoring case against the used method. +The method is tested as is ignoring case against the used method. |`paths` |string[] |{nbsp} |Add supported paths for this target. May be called more than once to add more paths. - The path is tested as is against called path, and also tested as a regular expression. +The path is tested as is against called path, and also tested as a regular expression. |`transport` |string[] |{nbsp} |Add supported transports for this target. May be called more than once to add more transports. - Valid examples: +Valid examples: - http - + - https There is no wildcard support diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc new file mode 100644 index 00000000000..02fe4a1679e --- /dev/null +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider.adoc @@ -0,0 +1,64 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2024 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + +ifndef::rootdir[:rootdir: {docdir}/..] +:description: Configuration of io.helidon.security.providers.config.vault.ConfigVaultProvider +:keywords: helidon, config, io.helidon.security.providers.config.vault.ConfigVaultProvider +:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.config.vault.ConfigVaultProvider +include::{rootdir}/includes/attributes.adoc[] + += ConfigVaultProvider (security.providers.config.vault) Configuration + +// tag::config[] + +Secrets and Encryption provider using just configuration + + +Type: link:{javadoc-base-url}/io.helidon.security.providers.config.vault/io/helidon/security/providers/config/vault/ConfigVaultProvider.html[io.helidon.security.providers.config.vault.ConfigVaultProvider] + + +[source,text] +.Config key +---- +config-vault +---- + + +This type provides the following service implementations: + +- `io.helidon.security.spi.SecurityProvider` +- `io.helidon.security.spi.SecretsProvider` +- `io.helidon.security.spi.EncryptionProvider` + + +== Configuration options + +.Required configuration options +[cols="3,3a,2,5a"] +|=== +|key |type |default value |description + +|`master-password` |string |{nbsp} |Configure master password used for encryption/decryption. +If master password cannot be obtained from any source (this method, configuration, system property, +environment variable), encryption and decryption will not be supported. + +|=== + + + +// end::config[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_servicecommon_RestServiceSettings_Builder.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc similarity index 52% rename from docs/src/main/asciidoc/config/io_helidon_webserver_servicecommon_RestServiceSettings_Builder.adoc rename to docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc index 32e941a325d..604012e420c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_servicecommon_RestServiceSettings_Builder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_config_vault_ConfigVaultProvider_SecretConfig.adoc @@ -17,21 +17,27 @@ /////////////////////////////////////////////////////////////////////////////// ifndef::rootdir[:rootdir: {docdir}/..] -:description: Configuration of io.helidon.webserver.servicecommon.RestServiceSettings.Builder -:keywords: helidon, config, io.helidon.webserver.servicecommon.RestServiceSettings.Builder -:basic-table-intro: The table below lists the configuration keys that configure io.helidon.webserver.servicecommon.RestServiceSettings.Builder +:description: Configuration of io.helidon.security.providers.config.vault.ConfigVaultProvider.SecretConfig +:keywords: helidon, config, io.helidon.security.providers.config.vault.ConfigVaultProvider.SecretConfig +:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.config.vault.ConfigVaultProvider.SecretConfig include::{rootdir}/includes/attributes.adoc[] -= Builder (webserver.servicecommon.RestServiceSettings) Configuration += SecretConfig (security.providers.config.vault.ConfigVaultProvider) Configuration // tag::config[] +Provider of secrets defined in configuration itself -Type: link:{javadoc-base-url}/io.helidon.webserver.servicecommon.RestServiceSettings/io/helidon/webserver/servicecommon/RestServiceSettings/Builder.html[io.helidon.webserver.servicecommon.RestServiceSettings.Builder] +Type: link:{javadoc-base-url}/io.helidon.security.providers.config.vault.ConfigVaultProvider/io/helidon/security/providers/config/vault/ConfigVaultProvider/SecretConfig.html[io.helidon.security.providers.config.vault.ConfigVaultProvider.SecretConfig] +This type provides the following service implementations: + +- `io.helidon.security.SecretsProviderConfig` + + == Configuration options @@ -42,10 +48,7 @@ Type: link:{javadoc-base-url}/io.helidon.webserver.servicecommon.RestServiceSett |=== |key |type |default value |description -|`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[Map<string, CrossOriginConfig>] |{nbsp} |Sets the cross-origin config builder for use in establishing CORS support for the service endpoints. -|`enabled` |boolean |`true` |Is this service enabled or not. -|`routing` |string |{nbsp} |Sets the routing name to use for setting up the service's endpoint. -|`web-context` |string |{nbsp} |Sets the web context to use for the service's endpoint. +|`value` |ConfiguredOption |{nbsp} |Value of the secret, can be a reference to another configuration key, such as ${app.secret} |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc index d9b8791fab3..245347d4c51 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc @@ -57,9 +57,9 @@ This type provides the following service implementations: |`client-id` |string |{nbsp} |Google application client id, to validate that the token was generated by Google for us. |`optional` |boolean |`false` |If set to true, this provider will return io.helidon.security.SecurityResponse.SecurityStatus.ABSTAIN instead - of failing in case of invalid request. +of failing in case of invalid request. |`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundConfig.adoc[OutboundConfig] |{nbsp} |Outbound configuration - a set of outbound targets that - will have the token propagated. +will have the token propagated. |`proxy-host` |string |{nbsp} |Set proxy host when talking to Google. |`proxy-port` |int |`80` |Set proxy port when talking to Google. |`realm` |string |`helidon` |Set the authentication realm to build challenge, defaults to "helidon". diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc index cf267481c23..9ab2b5c1863 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc @@ -58,11 +58,11 @@ This type provides the following service implementations: |`atn-token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Token handler to extract username from request. |`authenticate` |boolean |`true` |Whether to authenticate requests. |`optional` |boolean |`false` |Whether authentication is required. - By default, request will fail if the username cannot be extracted. - If set to false, request will process and this provider will abstain. +By default, request will fail if the username cannot be extracted. +If set to false, request will process and this provider will abstain. |`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundTarget.adoc[OutboundTarget[]] |{nbsp} |Configure outbound target for identity propagation. |`outbound-token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Token handler to create outbound headers to propagate identity. - If not defined, atnTokenHandler will be used. +If not defined, atnTokenHandler will be used. |`principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates). |`propagate` |boolean |`false` |Whether to propagate identity. diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc index 9ba61b0ab0b..0e902bbef34 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc @@ -56,13 +56,13 @@ This type provides the following service implementations: |key |type |default value |description |`optional` |boolean |`false` |Whether authentication is required. - By default, request will fail if the authentication cannot be verified. - If set to false, request will process and this provider will abstain. +By default, request will fail if the authentication cannot be verified. +If set to false, request will process and this provider will abstain. |`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundTarget.adoc[OutboundTarget[]] |{nbsp} |Add a new outbound target to configure identity propagation or explicit username/password. |`principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates). |`realm` |string |`helidon` |Set the realm to use when challenging users. |`users` |xref:{rootdir}/config/io_helidon_security_providers_httpauth_ConfigUserStore_ConfigUser.adoc[ConfigUser[]] |{nbsp} |Set user store to validate users. - Removes any other stores added through addUserStore(SecureUserStore). +Removes any other stores added through addUserStore(SecureUserStore). |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc index a548cdd044f..12711830dc1 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2023 Oracle and/or its affiliates. + Copyright (c) 2023, 2024 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -56,18 +56,32 @@ This type provides the following service implementations: |key |type |default value |description |`algorithm` |Algorithm (MD5) |`MD5` |Digest algorithm to use. + +Allowed values: + +- `MD5`: MD5 algorithm. + |`nonce-timeout-millis` |long |`86400000` |How long will the nonce value be valid. When timed-out, browser will re-request username/password. |`optional` |boolean |`false` |Whether authentication is required. - By default, request will fail if the authentication cannot be verified. - If set to false, request will process and this provider will abstain. +By default, request will fail if the authentication cannot be verified. +If set to false, request will process and this provider will abstain. |`principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates). |`qop` |Qop (NONE, AUTH) |`NONE` |Only `AUTH` supported. If left empty, uses the legacy approach (older RFC version). `AUTH-INT` is not supported. + +Allowed values: + +- `NONE`: Legacy approach - used internally to parse headers. Do not use this option when +building provider. If you want to support only legacy RFC, please use +HttpDigestAuthProvider.Builder.noDigestQop(). +Only AUTH is supported, as auth-int requires access to message body. +- `AUTH`: QOP "auth" - stands for "authentication". + |`realm` |string |`Helidon` |Set the realm to use when challenging users. |`server-secret` |string |{nbsp} |The nonce is encrypted using this secret - to make sure the nonce we get back was generated by us and to - make sure we can safely time-out nonce values. - This secret must be the same for all service instances (or all services that want to share the same authentication). - Defaults to a random password - e.g. if deployed to multiple servers, the authentication WILL NOT WORK. You MUST - provide your own password to work in a distributed environment with non-sticky load balancing. +make sure we can safely time-out nonce values. +This secret must be the same for all service instances (or all services that want to share the same authentication). +Defaults to a random password - e.g. if deployed to multiple servers, the authentication WILL NOT WORK. You MUST +provide your own password to work in a distributed environment with non-sticky load balancing. |`users` |xref:{rootdir}/config/io_helidon_security_providers_httpauth_ConfigUserStore_ConfigUser.adoc[ConfigUser[]] |{nbsp} |Set user store to obtain passwords and roles based on logins. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc index 4135b525654..ebbab063bf8 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc @@ -56,75 +56,91 @@ This type provides the following service implementations: |`backward-compatible-eol` |boolean |`false` |Enable support for Helidon versions before 3.0.0 (exclusive). - Until version 3.0.0 (exclusive) there was a trailing end of line added to the signed - data. - To be able to communicate cross versions, we must configure this when talking to older versions of Helidon. - Default value is `false`. In Helidon 2.x, this switch exists as well and the default is `true`, to - allow communication between versions as needed. +Until version 3.0.0 (exclusive) there was a trailing end of line added to the signed +data. +To be able to communicate cross versions, we must configure this when talking to older versions of Helidon. +Default value is `false`. In Helidon 2.x, this switch exists as well and the default is `true`, to +allow communication between versions as needed. |`headers` |HttpSignHeader[] (SIGNATURE, AUTHORIZATION, CUSTOM) |{nbsp} |Add a header that is validated on inbound requests. Provider may support more than - one header to validate. +one header to validate. + +Allowed values: + +- `SIGNATURE`: Creates (or validates) a "Signature" header. +- `AUTHORIZATION`: Creates (or validates) an "Authorization" header, that contains "Signature" as the +beginning of its content (the rest of the header is the same as for SIGNATURE. +- `CUSTOM`: Custom provided using a io.helidon.security.util.TokenHandler. + |`inbound.keys` |xref:{rootdir}/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc[InboundClientDefinition[]] |{nbsp} |Add inbound configuration. This is used to validate signature and authenticate the - party. - - The same can be done through configuration: - 
- {
-  name = "http-signatures"
-  class = "HttpSignProvider"
-  http-signatures {
-      inbound {
-          # This configures the InboundClientDefinition
-          keys: [
-          {
-              key-id = "service1"
-              hmac.secret = "${CLEAR=password}"
-          }]
-      }
-  }
+party.
+
+The same can be done through configuration:
+
+----
+
+{
+ name = "http-signatures"
+ class = "HttpSignProvider"
+ http-signatures {
+     inbound {
+         # This configures the InboundClientDefinition
+         keys: [
+         {
+             key-id = "service1"
+             hmac.secret = "${CLEAR=password}"
+         }]
+     }
  }
-
+} + +---- + |`optional` |boolean |`true` |Set whether the signature is optional. If set to true (default), this provider will - SecurityResponse.SecurityStatus.ABSTAIN from this request if signature is not - present. If set to false, this provider will SecurityResponse.SecurityStatus.FAILURE fail - if signature is not present. +SecurityResponse.SecurityStatus.ABSTAIN from this request if signature is not +present. If set to false, this provider will SecurityResponse.SecurityStatus.FAILURE fail +if signature is not present. |`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundConfig.adoc[OutboundConfig] |{nbsp} |Add outbound targets to this builder. - The targets are used to chose what to do for outbound communication. - The targets should have OutboundTargetDefinition attached through - OutboundTarget.Builder.customObject(Class, Object) to tell us how to sign - the request. - - The same can be done through configuration: - 
- {
-  name = "http-signatures"
-  class = "HttpSignProvider"
-  http-signatures {
-      targets: [
-      {
-          name = "service2"
-          hosts = ["localhost"]
-          paths = ["/service2/.*"]
-
-          # This configures the OutboundTargetDefinition
-          signature {
-              key-id = "service1"
-              hmac.secret = "${CLEAR=password}"
-          }
-      }]
-  }
+The targets are used to chose what to do for outbound communication.
+The targets should have OutboundTargetDefinition attached through
+OutboundTarget.Builder.customObject(Class, Object) to tell us how to sign
+the request.
+
+The same can be done through configuration:
+
+----
+
+{
+ name = "http-signatures"
+ class = "HttpSignProvider"
+ http-signatures {
+     targets: [
+     {
+         name = "service2"
+         hosts = ["localhost"]
+         paths = ["/service2/.*"]
+
+         # This configures the OutboundTargetDefinition
+         signature {
+             key-id = "service1"
+             hmac.secret = "${CLEAR=password}"
+         }
+     }]
  }
-
+} + +---- + |`realm` |string |`helidon` |Realm to use for challenging inbound requests that do not have "Authorization" header - in case header is HttpSignHeader.AUTHORIZATION and singatures are not optional. +in case header is HttpSignHeader.AUTHORIZATION and singatures are not optional. |`sign-headers` |xref:{rootdir}/config/io_helidon_security_providers_httpsign_SignedHeadersConfig_HeadersConfig.adoc[HeadersConfig[]] |{nbsp} |Override the default inbound required headers (e.g. headers that MUST be signed and - headers that MUST be signed IF present). +headers that MUST be signed IF present). - Defaults: +Defaults: - get, head, delete methods: date, (request-target), host are mandatory; authorization if present (unless we are - creating/validating the HttpSignHeader.AUTHORIZATION ourselves +creating/validating the HttpSignHeader.AUTHORIZATION ourselves - put, post: same as above, with addition of: content-length, content-type and digest if present - + - for other methods: date, (request-target) Note that this provider DOES NOT validate the "Digest" HTTP header, only the signature. diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc index 9f134d63f49..43c503610e3 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc @@ -43,14 +43,14 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.httpsign/io/helidon/ |key |type |default value |description |`algorithm` |string |{nbsp} |Algorithm of signature used by this client. - Currently supported: +Currently supported: - rsa-sha256 - asymmetric based on public/private keys - hmac-sha256 - symmetric based on a shared secret |`hmac.secret` |string |{nbsp} |Helper method to configure a password-like secret (instead of byte based hmacSecret(byte[]). - The password is transformed to bytes with StandardCharsets.UTF_8 charset. +The password is transformed to bytes with StandardCharsets.UTF_8 charset. |`key-id` |string |{nbsp} |The key id of this client to map to this signature validation configuration. |`principal-name` |string |{nbsp} |The principal name of the client, defaults to keyId if not configured. |`principal-type` |SubjectType (USER, SERVICE) |`SERVICE` |The type of principal we have authenticated (either user or service, defaults to service). diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc index 3edcf211006..af72a410d6c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperProvider.adoc @@ -57,19 +57,19 @@ This type provides the following service implementations: |`cache-config` |xref:{rootdir}/config/io_helidon_security_providers_common_EvictableCache.adoc[EvictableCache] |{nbsp} |Use explicit io.helidon.security.providers.common.EvictableCache for role caching. |`default-idcs-subject-type` |string |`user` |Configure subject type to use when requesting roles from IDCS. - Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. - Defaults to IDCS_SUBJECT_TYPE_USER. +Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. +Defaults to IDCS_SUBJECT_TYPE_USER. |`idcs-app-name-handler` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Configure token handler for IDCS Application name. - By default the header IdcsMtRoleMapperProvider.IDCS_APP_HEADER is used. +By default the header IdcsMtRoleMapperProvider.IDCS_APP_HEADER is used. |`idcs-tenant-handler` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Configure token handler for IDCS Tenant ID. - By default the header IdcsMtRoleMapperProvider.IDCS_TENANT_HEADER is used. +By default the header IdcsMtRoleMapperProvider.IDCS_TENANT_HEADER is used. |`oidc-config` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc[OidcConfig] |{nbsp} |Use explicit io.helidon.security.providers.oidc.common.OidcConfig instance, e.g. when using it also for OIDC - provider. +provider. |`subject-types` |SubjectType[] (USER, SERVICE) |`USER` |Add a supported subject type. - If none added, io.helidon.security.SubjectType.USER is used. - If any added, only the ones added will be used (e.g. if you want to use - both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, - both need to be added. +If none added, io.helidon.security.SubjectType.USER is used. +If any added, only the ones added will be used (e.g. if you want to use +both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, +both need to be added. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc index 67b7f64bbc3..528642bc210 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProvider.adoc @@ -57,15 +57,15 @@ This type provides the following service implementations: |`cache-config` |xref:{rootdir}/config/io_helidon_security_providers_common_EvictableCache.adoc[EvictableCache] |{nbsp} |Use explicit io.helidon.security.providers.common.EvictableCache for role caching. |`default-idcs-subject-type` |string |`user` |Configure subject type to use when requesting roles from IDCS. - Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. - Defaults to IDCS_SUBJECT_TYPE_USER. +Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. +Defaults to IDCS_SUBJECT_TYPE_USER. |`oidc-config` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc[OidcConfig] |{nbsp} |Use explicit io.helidon.security.providers.oidc.common.OidcConfig instance, e.g. when using it also for OIDC - provider. +provider. |`subject-types` |SubjectType[] (USER, SERVICE) |`USER` |Add a supported subject type. - If none added, io.helidon.security.SubjectType.USER is used. - If any added, only the ones added will be used (e.g. if you want to use - both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, - both need to be added. +If none added, io.helidon.security.SubjectType.USER is used. +If any added, only the ones added will be used (e.g. if you want to use +both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, +both need to be added. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProviderBase_Builder.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProviderBase_Builder.adoc index 18f2c61476e..546e355da16 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProviderBase_Builder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperProviderBase_Builder.adoc @@ -43,15 +43,15 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.idcs.mapper.IdcsRole |key |type |default value |description |`default-idcs-subject-type` |string |`user` |Configure subject type to use when requesting roles from IDCS. - Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. - Defaults to IDCS_SUBJECT_TYPE_USER. +Can be either IDCS_SUBJECT_TYPE_USER or IDCS_SUBJECT_TYPE_CLIENT. +Defaults to IDCS_SUBJECT_TYPE_USER. |`oidc-config` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc[OidcConfig] |{nbsp} |Use explicit io.helidon.security.providers.oidc.common.OidcConfig instance, e.g. when using it also for OIDC - provider. +provider. |`subject-types` |SubjectType[] (USER, SERVICE) |`USER` |Add a supported subject type. - If none added, io.helidon.security.SubjectType.USER is used. - If any added, only the ones added will be used (e.g. if you want to use - both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, - both need to be added. +If none added, io.helidon.security.SubjectType.USER is used. +If any added, only the ones added will be used (e.g. if you want to use +both io.helidon.security.SubjectType.USER and io.helidon.security.SubjectType.SERVICE, +both need to be added. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_jwt_JwtProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_jwt_JwtProvider.adoc index 0a69c95ecdc..92528b33934 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_jwt_JwtProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_jwt_JwtProvider.adoc @@ -56,36 +56,34 @@ This type provides the following service implementations: |key |type |default value |description |`allow-impersonation` |boolean |`false` |Whether to allow impersonation by explicitly overriding - username from outbound requests using io.helidon.security.EndpointConfig.PROPERTY_OUTBOUND_ID - property. - By default this is not allowed and identity can only be propagated. +username from outbound requests using io.helidon.security.EndpointConfig.PROPERTY_OUTBOUND_ID +property. +By default this is not allowed and identity can only be propagated. |`allow-unsigned` |boolean |`false` |Configure support for unsigned JWT. - If this is set to `true` any JWT that has algorithm - set to `none` and no `kid` defined will be accepted. - Note that this has serious security impact - if JWT can be sent - from a third party, this allows the third party to send ANY JWT - and it would be accpted as valid. +If this is set to `true` any JWT that has algorithm +set to `none` and no `kid` defined will be accepted. +Note that this has serious security impact - if JWT can be sent + from a third party, this allows the third party to send ANY JWT + and it would be accpted as valid. |`atn-token.handler` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |Token handler to extract username from request. |`atn-token.jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |JWK resource used to verify JWTs created by other parties. |`atn-token.jwt-audience` |string |{nbsp} |Audience expected in inbound JWTs. |`atn-token.verify-signature` |boolean |`true` |Configure whether to verify signatures. - Signatures verification is enabled by default. You can configure the provider - not to verify signatures. +Signatures verification is enabled by default. You can configure the provider +not to verify signatures. - Make sure your service is properly secured on network level and only - accessible from a secure endpoint that provides the JWTs when signature verification - is disabled. If signature verification is disabled, this service will accept ANY JWT +*Make sure your service is properly secured on network level and only accessible from a secure endpoint that provides the JWTs when signature verification is disabled. If signature verification is disabled, this service will accept _ANY_ JWT* |`authenticate` |boolean |`true` |Whether to authenticate requests. |`optional` |boolean |`false` |Whether authentication is required. - By default, request will fail if the username cannot be extracted. - If set to false, request will process and this provider will abstain. +By default, request will fail if the username cannot be extracted. +If set to false, request will process and this provider will abstain. |`principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates). |`propagate` |boolean |`true` |Whether to propagate identity. |`sign-token` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundConfig.adoc[OutboundConfig] |{nbsp} |Configuration of outbound rules. |`sign-token.jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |JWK resource used to sign JWTs created by us. |`sign-token.jwt-issuer` |string |{nbsp} |Issuer used to create new JWTs. |`use-jwt-groups` |boolean |`true` |Claim `groups` from JWT will be used to automatically add - groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation). + groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation). |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_OidcProvider.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_OidcProvider.adoc index bdf45263c19..5316da19bab 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_OidcProvider.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_OidcProvider.adoc @@ -56,156 +56,193 @@ This type provides the following service implementations: |key |type |default value |description |`access-token-ip-check` |boolean |`true` |Whether to check if current IP address matches the one access token was issued for. - This check helps with cookie replay attack prevention. +This check helps with cookie replay attack prevention. |`audience` |string |{nbsp} |Audience of issued tokens. |`authorization-endpoint-uri` |URI |{nbsp} |URI of an authorization endpoint used to redirect users to for logging-in. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/authorize. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/authorize. |`base-scopes` |string |`openid` |Configure base scopes. - By default, this is DEFAULT_BASE_SCOPES. - If scope has a qualifier, it must be used here. +By default, this is DEFAULT_BASE_SCOPES. +If scope has a qualifier, it must be used here. |`check-audience` |boolean |`false` |Configure audience claim check. |`client-id` |string |{nbsp} |Client ID as generated by OIDC server. |`client-secret` |string |{nbsp} |Client secret as generated by OIDC server. - Used to authenticate this application with the server when requesting - JWT based on a code. +Used to authenticate this application with the server when requesting +JWT based on a code. |`client-timeout-millis` |Duration |`30000` |Timeout of calls using web client. |`cookie-domain` |string |{nbsp} |Domain the cookie is valid for. - Not used by default. +Not used by default. |`cookie-encryption-enabled` |boolean |`false` |Whether to encrypt token cookie created by this microservice. - Defaults to `false`. +Defaults to `false`. |`cookie-encryption-id-enabled` |boolean |`true` |Whether to encrypt id token cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-name` |string |{nbsp} |Name of the encryption configuration available through Security.encrypt(String, byte[]) and - Security.decrypt(String, String). - If configured and encryption is enabled for any cookie, - Security MUST be configured in global or current `io.helidon.common.context.Context` (this - is done automatically in Helidon MP). +Security.decrypt(String, String). +If configured and encryption is enabled for any cookie, +Security MUST be configured in global or current `io.helidon.common.context.Context` (this +is done automatically in Helidon MP). |`cookie-encryption-password` |char[] |{nbsp} |Master password for encryption/decryption of cookies. This must be configured to the same value on each microservice - using the cookie. +using the cookie. |`cookie-encryption-refresh-enabled` |boolean |`true` |Whether to encrypt refresh token cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-state-enabled` |boolean |`true` |Whether to encrypt state cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-tenant-enabled` |boolean |`true` |Whether to encrypt tenant name cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-http-only` |boolean |`true` |When using cookie, if set to true, the HttpOnly attribute will be configured. - Defaults to OidcCookieHandler.Builder.DEFAULT_HTTP_ONLY. +Defaults to OidcCookieHandler.Builder.DEFAULT_HTTP_ONLY. |`cookie-max-age-seconds` |long |{nbsp} |When using cookie, used to set MaxAge attribute of the cookie, defining how long - the cookie is valid. - Not used by default. +the cookie is valid. +Not used by default. |`cookie-name` |string |`JSESSIONID` |Name of the cookie to use. - Defaults to DEFAULT_COOKIE_NAME. +Defaults to DEFAULT_COOKIE_NAME. |`cookie-name-id-token` |string |`JSESSIONID_2` |Name of the cookie to use for id token. - Defaults to DEFAULT_COOKIE_NAME_2. +Defaults to DEFAULT_COOKIE_NAME_2. - This cookie is only used when logout is enabled, as otherwise it is not needed. - Content of this cookie is encrypted. +This cookie is only used when logout is enabled, as otherwise it is not needed. +Content of this cookie is encrypted. |`cookie-name-refresh-token` |string |`JSESSIONID_3` |The name of the cookie to use for the refresh token. - Defaults to DEFAULT_REFRESH_COOKIE_NAME. +Defaults to DEFAULT_REFRESH_COOKIE_NAME. |`cookie-name-state` |string |`JSESSIONID_3` |The name of the cookie to use for the state storage. - Defaults to DEFAULT_STATE_COOKIE_NAME. +Defaults to DEFAULT_STATE_COOKIE_NAME. |`cookie-name-tenant` |string |`HELIDON_TENANT` |The name of the cookie to use for the tenant name. - Defaults to DEFAULT_TENANT_COOKIE_NAME. +Defaults to DEFAULT_TENANT_COOKIE_NAME. |`cookie-path` |string |`/` |Path the cookie is valid for. - Defaults to "/". +Defaults to "/". |`cookie-same-site` |SameSite (LAX, STRICT, NONE) |`LAX` |When using cookie, used to set the SameSite cookie value. Can be - "Strict" or "Lax". +"Strict" or "Lax". |`cookie-secure` |boolean |`false` |When using cookie, if set to true, the Secure attribute will be configured. - Defaults to false. +Defaults to false. |`cookie-use` |boolean |`true` |Whether to use cookie to store JWT between requests. - Defaults to DEFAULT_COOKIE_USE. +Defaults to DEFAULT_COOKIE_USE. |`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assign cross-origin resource sharing settings. |`force-https-redirects` |boolean |`false` |Force HTTPS for redirects to identity provider. - Defaults to `false`. +Defaults to `false`. |`frontend-uri` |string |{nbsp} |Full URI of this application that is visible from user browser. - Used to redirect request back from identity server after successful login. +Used to redirect request back from identity server after successful login. |`header-token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |A TokenHandler to - process header containing a JWT. - Default is "Authorization" header with a prefix "bearer ". +process header containing a JWT. +Default is "Authorization" header with a prefix "bearer ". |`header-use` |boolean |`true` |Whether to expect JWT in a header field. |`id-token-signature-validation` |boolean |`true` |Whether id token signature check should be enabled. - Signature check is enabled by default, and it is highly recommended to not change that. - Change this setting only when you really know what you are doing, otherwise it could case security issues. +Signature check is enabled by default, and it is highly recommended to not change that. +Change this setting only when you really know what you are doing, otherwise it could case security issues. |`identity-uri` |URI |{nbsp} |URI of the identity server, base used to retrieve OIDC metadata. |`introspect-endpoint-uri` |URI |{nbsp} |Endpoint to use to validate JWT. - Either use this or set signJwk(JwkKeys) or signJwk(Resource). +Either use this or set signJwk(JwkKeys) or signJwk(Resource). |`issuer` |string |{nbsp} |Issuer of issued tokens. |`max-redirects` |int |`5` |Configure maximal number of redirects when redirecting to an OIDC provider within a single authentication - attempt. +attempt. - Defaults to DEFAULT_MAX_REDIRECTS +Defaults to DEFAULT_MAX_REDIRECTS |`oidc-metadata-well-known` |boolean |`true` |If set to true, metadata will be loaded from default (well known) - location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded - even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. - token-endpoint-uri). +location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded +even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. +token-endpoint-uri). |`oidc-metadata.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Resource configuration for OIDC Metadata - containing endpoints to various identity services, as well as information about the identity server. +containing endpoints to various identity services, as well as information about the identity server. |`optional` |boolean |`false` |Whether authentication is required. - By default, request will fail if the authentication cannot be verified. - If set to true, request will process and this provider will abstain. +By default, request will fail if the authentication cannot be verified. +If set to true, request will process and this provider will abstain. |`optional-audience` |boolean |`false` |Allow audience claim to be optional. |`outbound` |xref:{rootdir}/config/io_helidon_security_providers_common_OutboundTarget.adoc[OutboundTarget[]] |{nbsp} |Add a new target configuration. |`propagate` |boolean |`false` |Whether to propagate identity. |`proxy-host` |string |{nbsp} |Proxy host to use. When defined, triggers usage of proxy for HTTP requests. - Setting to empty String has the same meaning as setting to null - disables proxy. +Setting to empty String has the same meaning as setting to null - disables proxy. |`proxy-port` |int |`80` |Proxy port. - Defaults to DEFAULT_PROXY_PORT +Defaults to DEFAULT_PROXY_PORT |`proxy-protocol` |string |`http` |Proxy protocol to use when proxy is used. - Defaults to DEFAULT_PROXY_PROTOCOL. +Defaults to DEFAULT_PROXY_PROTOCOL. |`query-id-token-param-name` |string |`id_token` |Name of a query parameter that contains the JWT id token when parameter is used. |`query-param-name` |string |`accessToken` |Name of a query parameter that contains the JWT access token when parameter is used. |`query-param-tenant-name` |string |`h_tenant` |Name of a query parameter that contains the tenant name when the parameter is used. - Defaults to DEFAULT_TENANT_PARAM_NAME. +Defaults to DEFAULT_TENANT_PARAM_NAME. |`query-param-use` |boolean |`false` |Whether to use a query parameter to send JWT token from application to this - server. +server. |`redirect` |boolean |`false` |By default, the client should redirect to the identity server for the user to log in. - This behavior can be overridden by setting redirect to false. When token is not present in the request, the client - will not redirect and just return appropriate error response code. +This behavior can be overridden by setting redirect to false. When token is not present in the request, the client +will not redirect and just return appropriate error response code. |`redirect-attempt-param` |string |`h_ra` |Configure the parameter used to store the number of attempts in redirect. - Defaults to DEFAULT_ATTEMPT_PARAM +Defaults to DEFAULT_ATTEMPT_PARAM |`redirect-uri` |string |`/oidc/redirect` |URI to register web server component on, used by the OIDC server to - redirect authorization requests to after a user logs in or approves - scopes. - Note that usually the redirect URI configured here must be the - same one as configured on OIDC server. +redirect authorization requests to after a user logs in or approves +scopes. +Note that usually the redirect URI configured here must be the +same one as configured on OIDC server. - Defaults to DEFAULT_REDIRECT_URI +Defaults to DEFAULT_REDIRECT_URI |`relative-uris` |boolean |`false` |Can be set to `true` to force the use of relative URIs in all requests, - regardless of the presence or absence of proxies or no-proxy lists. By default, - requests that use the Proxy will have absolute URIs. Set this flag to `true` - if the host is unable to accept absolute URIs. - Defaults to DEFAULT_RELATIVE_URIS. +regardless of the presence or absence of proxies or no-proxy lists. By default, +requests that use the Proxy will have absolute URIs. Set this flag to `true` +if the host is unable to accept absolute URIs. +Defaults to DEFAULT_RELATIVE_URIS. |`scope-audience` |string |{nbsp} |Audience of the scope required by this application. This is prefixed to - the scope name when requesting scopes from the identity server. - Defaults to empty string. +the scope name when requesting scopes from the identity server. +Defaults to empty string. |`server-type` |string |`@default` |Configure one of the supported types of identity servers. - If the type does not have an explicit mapping, a warning is logged and the default implementation is used. +If the type does not have an explicit mapping, a warning is logged and the default implementation is used. |`sign-jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |A resource pointing to JWK with public keys of signing certificates used - to validate JWT. +to validate JWT. |`tenants` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc[TenantConfig] |{nbsp} |Configurations of the tenants |`token-endpoint-auth` |ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE) |`CLIENT_SECRET_BASIC` |Type of authentication to use when invoking the token endpoint. - Current supported options: +Current supported options: - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_BASIC - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_POST - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.NONE +Allowed values: + +- `CLIENT_SECRET_BASIC`: Clients that have received a client_secret value from the Authorization Server authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] using the HTTP Basic authentication scheme. +This is the default client authentication. +- `CLIENT_SECRET_POST`: Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] by including the Client Credentials in the request body. +- `CLIENT_SECRET_JWT`: Clients that have received a client_secret value from the Authorization Server create a JWT using an HMAC SHA +algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of +the UTF-8 representation of the client_secret as the shared key. +The Client authenticates in accordance with JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and +Authorization Grants [OAuth.JWT] and Assertion Framework for OAuth 2.0 Client Authentication and Authorization +Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `PRIVATE_KEY_JWT`: Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with +JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.JWT] and Assertion +Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `NONE`: The Client does not authenticate itself at the Token Endpoint, either because it uses only the Implicit Flow (and so +does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication +mechanism. |`token-endpoint-uri` |URI |{nbsp} |URI of a token endpoint used to obtain a JWT based on the authentication - code. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/token. +code. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/token. |`token-signature-validation` |boolean |`true` |Whether access token signature check should be enabled. - Signature check is enabled by default, and it is highly recommended to not change that. - Change this setting only when you really know what you are doing, otherwise it could case security issues. +Signature check is enabled by default, and it is highly recommended to not change that. +Change this setting only when you really know what you are doing, otherwise it could case security issues. |`use-jwt-groups` |boolean |`true` |Claim `groups` from JWT will be used to automatically add - groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation). + groups to current subject (may be used with jakarta.annotation.security.RolesAllowed annotation). |`validate-jwt-with-jwk` |boolean |`true` |Use JWK (a set of keys to validate signatures of JWT) to validate tokens. - Use this method when you want to use default values for JWK or introspection endpoint URI. +Use this method when you want to use default values for JWK or introspection endpoint URI. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_BaseBuilder.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_BaseBuilder.adoc index 0d030dac053..becac070edd 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_BaseBuilder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_BaseBuilder.adoc @@ -45,50 +45,87 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.oidc.common/io/helid |`audience` |string |{nbsp} |Audience of issued tokens. |`authorization-endpoint-uri` |URI |{nbsp} |URI of an authorization endpoint used to redirect users to for logging-in. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/authorize. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/authorize. |`base-scopes` |string |`openid` |Configure base scopes. - By default, this is DEFAULT_BASE_SCOPES. - If scope has a qualifier, it must be used here. +By default, this is DEFAULT_BASE_SCOPES. +If scope has a qualifier, it must be used here. |`check-audience` |boolean |`false` |Configure audience claim check. |`client-id` |string |{nbsp} |Client ID as generated by OIDC server. |`client-secret` |string |{nbsp} |Client secret as generated by OIDC server. - Used to authenticate this application with the server when requesting - JWT based on a code. +Used to authenticate this application with the server when requesting +JWT based on a code. |`client-timeout-millis` |Duration |`30000` |Timeout of calls using web client. |`identity-uri` |URI |{nbsp} |URI of the identity server, base used to retrieve OIDC metadata. |`introspect-endpoint-uri` |URI |{nbsp} |Endpoint to use to validate JWT. - Either use this or set signJwk(JwkKeys) or signJwk(Resource). +Either use this or set signJwk(JwkKeys) or signJwk(Resource). |`issuer` |string |{nbsp} |Issuer of issued tokens. |`oidc-metadata-well-known` |boolean |`true` |If set to true, metadata will be loaded from default (well known) - location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded - even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. - token-endpoint-uri). +location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded +even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. +token-endpoint-uri). |`oidc-metadata.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Resource configuration for OIDC Metadata - containing endpoints to various identity services, as well as information about the identity server. +containing endpoints to various identity services, as well as information about the identity server. |`optional-audience` |boolean |`false` |Allow audience claim to be optional. |`scope-audience` |string |{nbsp} |Audience of the scope required by this application. This is prefixed to - the scope name when requesting scopes from the identity server. - Defaults to empty string. +the scope name when requesting scopes from the identity server. +Defaults to empty string. |`server-type` |string |`@default` |Configure one of the supported types of identity servers. - If the type does not have an explicit mapping, a warning is logged and the default implementation is used. +If the type does not have an explicit mapping, a warning is logged and the default implementation is used. |`sign-jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |A resource pointing to JWK with public keys of signing certificates used - to validate JWT. +to validate JWT. |`token-endpoint-auth` |ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE) |`CLIENT_SECRET_BASIC` |Type of authentication to use when invoking the token endpoint. - Current supported options: +Current supported options: - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_BASIC - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_POST - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.NONE +Allowed values: + +- `CLIENT_SECRET_BASIC`: Clients that have received a client_secret value from the Authorization Server authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] using the HTTP Basic authentication scheme. +This is the default client authentication. +- `CLIENT_SECRET_POST`: Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] by including the Client Credentials in the request body. +- `CLIENT_SECRET_JWT`: Clients that have received a client_secret value from the Authorization Server create a JWT using an HMAC SHA +algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of +the UTF-8 representation of the client_secret as the shared key. +The Client authenticates in accordance with JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and +Authorization Grants [OAuth.JWT] and Assertion Framework for OAuth 2.0 Client Authentication and Authorization +Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `PRIVATE_KEY_JWT`: Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with +JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.JWT] and Assertion +Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `NONE`: The Client does not authenticate itself at the Token Endpoint, either because it uses only the Implicit Flow (and so +does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication +mechanism. |`token-endpoint-uri` |URI |{nbsp} |URI of a token endpoint used to obtain a JWT based on the authentication - code. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/token. +code. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/token. |`validate-jwt-with-jwk` |boolean |`true` |Use JWK (a set of keys to validate signatures of JWT) to validate tokens. - Use this method when you want to use default values for JWK or introspection endpoint URI. +Use this method when you want to use default values for JWK or introspection endpoint URI. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc index 2b2f8552905..17742c33dfa 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_OidcConfig.adoc @@ -45,149 +45,186 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.oidc.common/io/helid |key |type |default value |description |`access-token-ip-check` |boolean |`true` |Whether to check if current IP address matches the one access token was issued for. - This check helps with cookie replay attack prevention. +This check helps with cookie replay attack prevention. |`audience` |string |{nbsp} |Audience of issued tokens. |`authorization-endpoint-uri` |URI |{nbsp} |URI of an authorization endpoint used to redirect users to for logging-in. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/authorize. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/authorize. |`base-scopes` |string |`openid` |Configure base scopes. - By default, this is DEFAULT_BASE_SCOPES. - If scope has a qualifier, it must be used here. +By default, this is DEFAULT_BASE_SCOPES. +If scope has a qualifier, it must be used here. |`check-audience` |boolean |`false` |Configure audience claim check. |`client-id` |string |{nbsp} |Client ID as generated by OIDC server. |`client-secret` |string |{nbsp} |Client secret as generated by OIDC server. - Used to authenticate this application with the server when requesting - JWT based on a code. +Used to authenticate this application with the server when requesting +JWT based on a code. |`client-timeout-millis` |Duration |`30000` |Timeout of calls using web client. |`cookie-domain` |string |{nbsp} |Domain the cookie is valid for. - Not used by default. +Not used by default. |`cookie-encryption-enabled` |boolean |`false` |Whether to encrypt token cookie created by this microservice. - Defaults to `false`. +Defaults to `false`. |`cookie-encryption-id-enabled` |boolean |`true` |Whether to encrypt id token cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-name` |string |{nbsp} |Name of the encryption configuration available through Security.encrypt(String, byte[]) and - Security.decrypt(String, String). - If configured and encryption is enabled for any cookie, - Security MUST be configured in global or current `io.helidon.common.context.Context` (this - is done automatically in Helidon MP). +Security.decrypt(String, String). +If configured and encryption is enabled for any cookie, +Security MUST be configured in global or current `io.helidon.common.context.Context` (this +is done automatically in Helidon MP). |`cookie-encryption-password` |char[] |{nbsp} |Master password for encryption/decryption of cookies. This must be configured to the same value on each microservice - using the cookie. +using the cookie. |`cookie-encryption-refresh-enabled` |boolean |`true` |Whether to encrypt refresh token cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-state-enabled` |boolean |`true` |Whether to encrypt state cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-encryption-tenant-enabled` |boolean |`true` |Whether to encrypt tenant name cookie created by this microservice. - Defaults to `true`. +Defaults to `true`. |`cookie-http-only` |boolean |`true` |When using cookie, if set to true, the HttpOnly attribute will be configured. - Defaults to OidcCookieHandler.Builder.DEFAULT_HTTP_ONLY. +Defaults to OidcCookieHandler.Builder.DEFAULT_HTTP_ONLY. |`cookie-max-age-seconds` |long |{nbsp} |When using cookie, used to set MaxAge attribute of the cookie, defining how long - the cookie is valid. - Not used by default. +the cookie is valid. +Not used by default. |`cookie-name` |string |`JSESSIONID` |Name of the cookie to use. - Defaults to DEFAULT_COOKIE_NAME. +Defaults to DEFAULT_COOKIE_NAME. |`cookie-name-id-token` |string |`JSESSIONID_2` |Name of the cookie to use for id token. - Defaults to DEFAULT_COOKIE_NAME_2. +Defaults to DEFAULT_COOKIE_NAME_2. - This cookie is only used when logout is enabled, as otherwise it is not needed. - Content of this cookie is encrypted. +This cookie is only used when logout is enabled, as otherwise it is not needed. +Content of this cookie is encrypted. |`cookie-name-refresh-token` |string |`JSESSIONID_3` |The name of the cookie to use for the refresh token. - Defaults to DEFAULT_REFRESH_COOKIE_NAME. +Defaults to DEFAULT_REFRESH_COOKIE_NAME. |`cookie-name-state` |string |`JSESSIONID_3` |The name of the cookie to use for the state storage. - Defaults to DEFAULT_STATE_COOKIE_NAME. +Defaults to DEFAULT_STATE_COOKIE_NAME. |`cookie-name-tenant` |string |`HELIDON_TENANT` |The name of the cookie to use for the tenant name. - Defaults to DEFAULT_TENANT_COOKIE_NAME. +Defaults to DEFAULT_TENANT_COOKIE_NAME. |`cookie-path` |string |`/` |Path the cookie is valid for. - Defaults to "/". +Defaults to "/". |`cookie-same-site` |SameSite (LAX, STRICT, NONE) |`LAX` |When using cookie, used to set the SameSite cookie value. Can be - "Strict" or "Lax". +"Strict" or "Lax". |`cookie-secure` |boolean |`false` |When using cookie, if set to true, the Secure attribute will be configured. - Defaults to false. +Defaults to false. |`cookie-use` |boolean |`true` |Whether to use cookie to store JWT between requests. - Defaults to DEFAULT_COOKIE_USE. +Defaults to DEFAULT_COOKIE_USE. |`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[CrossOriginConfig] |{nbsp} |Assign cross-origin resource sharing settings. |`force-https-redirects` |boolean |`false` |Force HTTPS for redirects to identity provider. - Defaults to `false`. +Defaults to `false`. |`frontend-uri` |string |{nbsp} |Full URI of this application that is visible from user browser. - Used to redirect request back from identity server after successful login. +Used to redirect request back from identity server after successful login. |`header-token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |{nbsp} |A TokenHandler to - process header containing a JWT. - Default is "Authorization" header with a prefix "bearer ". +process header containing a JWT. +Default is "Authorization" header with a prefix "bearer ". |`header-use` |boolean |`true` |Whether to expect JWT in a header field. |`id-token-signature-validation` |boolean |`true` |Whether id token signature check should be enabled. - Signature check is enabled by default, and it is highly recommended to not change that. - Change this setting only when you really know what you are doing, otherwise it could case security issues. +Signature check is enabled by default, and it is highly recommended to not change that. +Change this setting only when you really know what you are doing, otherwise it could case security issues. |`identity-uri` |URI |{nbsp} |URI of the identity server, base used to retrieve OIDC metadata. |`introspect-endpoint-uri` |URI |{nbsp} |Endpoint to use to validate JWT. - Either use this or set signJwk(JwkKeys) or signJwk(Resource). +Either use this or set signJwk(JwkKeys) or signJwk(Resource). |`issuer` |string |{nbsp} |Issuer of issued tokens. |`max-redirects` |int |`5` |Configure maximal number of redirects when redirecting to an OIDC provider within a single authentication - attempt. +attempt. - Defaults to DEFAULT_MAX_REDIRECTS +Defaults to DEFAULT_MAX_REDIRECTS |`oidc-metadata-well-known` |boolean |`true` |If set to true, metadata will be loaded from default (well known) - location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded - even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. - token-endpoint-uri). +location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded +even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. +token-endpoint-uri). |`oidc-metadata.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Resource configuration for OIDC Metadata - containing endpoints to various identity services, as well as information about the identity server. +containing endpoints to various identity services, as well as information about the identity server. |`optional-audience` |boolean |`false` |Allow audience claim to be optional. |`proxy-host` |string |{nbsp} |Proxy host to use. When defined, triggers usage of proxy for HTTP requests. - Setting to empty String has the same meaning as setting to null - disables proxy. +Setting to empty String has the same meaning as setting to null - disables proxy. |`proxy-port` |int |`80` |Proxy port. - Defaults to DEFAULT_PROXY_PORT +Defaults to DEFAULT_PROXY_PORT |`proxy-protocol` |string |`http` |Proxy protocol to use when proxy is used. - Defaults to DEFAULT_PROXY_PROTOCOL. +Defaults to DEFAULT_PROXY_PROTOCOL. |`query-id-token-param-name` |string |`id_token` |Name of a query parameter that contains the JWT id token when parameter is used. |`query-param-name` |string |`accessToken` |Name of a query parameter that contains the JWT access token when parameter is used. |`query-param-tenant-name` |string |`h_tenant` |Name of a query parameter that contains the tenant name when the parameter is used. - Defaults to DEFAULT_TENANT_PARAM_NAME. +Defaults to DEFAULT_TENANT_PARAM_NAME. |`query-param-use` |boolean |`false` |Whether to use a query parameter to send JWT token from application to this - server. +server. |`redirect` |boolean |`false` |By default, the client should redirect to the identity server for the user to log in. - This behavior can be overridden by setting redirect to false. When token is not present in the request, the client - will not redirect and just return appropriate error response code. +This behavior can be overridden by setting redirect to false. When token is not present in the request, the client +will not redirect and just return appropriate error response code. |`redirect-attempt-param` |string |`h_ra` |Configure the parameter used to store the number of attempts in redirect. - Defaults to DEFAULT_ATTEMPT_PARAM +Defaults to DEFAULT_ATTEMPT_PARAM |`redirect-uri` |string |`/oidc/redirect` |URI to register web server component on, used by the OIDC server to - redirect authorization requests to after a user logs in or approves - scopes. - Note that usually the redirect URI configured here must be the - same one as configured on OIDC server. +redirect authorization requests to after a user logs in or approves +scopes. +Note that usually the redirect URI configured here must be the +same one as configured on OIDC server. - Defaults to DEFAULT_REDIRECT_URI +Defaults to DEFAULT_REDIRECT_URI |`relative-uris` |boolean |`false` |Can be set to `true` to force the use of relative URIs in all requests, - regardless of the presence or absence of proxies or no-proxy lists. By default, - requests that use the Proxy will have absolute URIs. Set this flag to `true` - if the host is unable to accept absolute URIs. - Defaults to DEFAULT_RELATIVE_URIS. +regardless of the presence or absence of proxies or no-proxy lists. By default, +requests that use the Proxy will have absolute URIs. Set this flag to `true` +if the host is unable to accept absolute URIs. +Defaults to DEFAULT_RELATIVE_URIS. |`scope-audience` |string |{nbsp} |Audience of the scope required by this application. This is prefixed to - the scope name when requesting scopes from the identity server. - Defaults to empty string. +the scope name when requesting scopes from the identity server. +Defaults to empty string. |`server-type` |string |`@default` |Configure one of the supported types of identity servers. - If the type does not have an explicit mapping, a warning is logged and the default implementation is used. +If the type does not have an explicit mapping, a warning is logged and the default implementation is used. |`sign-jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |A resource pointing to JWK with public keys of signing certificates used - to validate JWT. +to validate JWT. |`tenants` |xref:{rootdir}/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc[TenantConfig] |{nbsp} |Configurations of the tenants |`token-endpoint-auth` |ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE) |`CLIENT_SECRET_BASIC` |Type of authentication to use when invoking the token endpoint. - Current supported options: +Current supported options: - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_BASIC - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_POST - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.NONE +Allowed values: + +- `CLIENT_SECRET_BASIC`: Clients that have received a client_secret value from the Authorization Server authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] using the HTTP Basic authentication scheme. +This is the default client authentication. +- `CLIENT_SECRET_POST`: Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] by including the Client Credentials in the request body. +- `CLIENT_SECRET_JWT`: Clients that have received a client_secret value from the Authorization Server create a JWT using an HMAC SHA +algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of +the UTF-8 representation of the client_secret as the shared key. +The Client authenticates in accordance with JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and +Authorization Grants [OAuth.JWT] and Assertion Framework for OAuth 2.0 Client Authentication and Authorization +Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `PRIVATE_KEY_JWT`: Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with +JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.JWT] and Assertion +Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `NONE`: The Client does not authenticate itself at the Token Endpoint, either because it uses only the Implicit Flow (and so +does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication +mechanism. |`token-endpoint-uri` |URI |{nbsp} |URI of a token endpoint used to obtain a JWT based on the authentication - code. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/token. +code. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/token. |`token-signature-validation` |boolean |`true` |Whether access token signature check should be enabled. - Signature check is enabled by default, and it is highly recommended to not change that. - Change this setting only when you really know what you are doing, otherwise it could case security issues. +Signature check is enabled by default, and it is highly recommended to not change that. +Change this setting only when you really know what you are doing, otherwise it could case security issues. |`validate-jwt-with-jwk` |boolean |`true` |Use JWK (a set of keys to validate signatures of JWT) to validate tokens. - Use this method when you want to use default values for JWK or introspection endpoint URI. +Use this method when you want to use default values for JWK or introspection endpoint URI. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc index 633a3eeac59..eb160f72a0e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_security_providers_oidc_common_TenantConfig.adoc @@ -56,50 +56,87 @@ Type: link:{javadoc-base-url}/io.helidon.security.providers.oidc.common/io/helid |`audience` |string |{nbsp} |Audience of issued tokens. |`authorization-endpoint-uri` |URI |{nbsp} |URI of an authorization endpoint used to redirect users to for logging-in. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/authorize. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/authorize. |`base-scopes` |string |`openid` |Configure base scopes. - By default, this is DEFAULT_BASE_SCOPES. - If scope has a qualifier, it must be used here. +By default, this is DEFAULT_BASE_SCOPES. +If scope has a qualifier, it must be used here. |`check-audience` |boolean |`false` |Configure audience claim check. |`client-id` |string |{nbsp} |Client ID as generated by OIDC server. |`client-secret` |string |{nbsp} |Client secret as generated by OIDC server. - Used to authenticate this application with the server when requesting - JWT based on a code. +Used to authenticate this application with the server when requesting +JWT based on a code. |`client-timeout-millis` |Duration |`30000` |Timeout of calls using web client. |`identity-uri` |URI |{nbsp} |URI of the identity server, base used to retrieve OIDC metadata. |`introspect-endpoint-uri` |URI |{nbsp} |Endpoint to use to validate JWT. - Either use this or set signJwk(JwkKeys) or signJwk(Resource). +Either use this or set signJwk(JwkKeys) or signJwk(Resource). |`issuer` |string |{nbsp} |Issuer of issued tokens. |`oidc-metadata-well-known` |boolean |`true` |If set to true, metadata will be loaded from default (well known) - location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded - even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. - token-endpoint-uri). +location, unless it is explicitly defined using oidc-metadata-resource. If set to false, it would not be loaded +even if oidc-metadata-resource is not defined. In such a case all URIs must be explicitly defined (e.g. +token-endpoint-uri). |`oidc-metadata.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Resource configuration for OIDC Metadata - containing endpoints to various identity services, as well as information about the identity server. +containing endpoints to various identity services, as well as information about the identity server. |`optional-audience` |boolean |`false` |Allow audience claim to be optional. |`scope-audience` |string |{nbsp} |Audience of the scope required by this application. This is prefixed to - the scope name when requesting scopes from the identity server. - Defaults to empty string. +the scope name when requesting scopes from the identity server. +Defaults to empty string. |`server-type` |string |`@default` |Configure one of the supported types of identity servers. - If the type does not have an explicit mapping, a warning is logged and the default implementation is used. +If the type does not have an explicit mapping, a warning is logged and the default implementation is used. |`sign-jwk.resource` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |A resource pointing to JWK with public keys of signing certificates used - to validate JWT. +to validate JWT. |`token-endpoint-auth` |ClientAuthentication (CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, NONE) |`CLIENT_SECRET_BASIC` |Type of authentication to use when invoking the token endpoint. - Current supported options: +Current supported options: - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_BASIC - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.CLIENT_SECRET_POST - io.helidon.security.providers.oidc.common.OidcConfig.ClientAuthentication.NONE +Allowed values: + +- `CLIENT_SECRET_BASIC`: Clients that have received a client_secret value from the Authorization Server authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] using the HTTP Basic authentication scheme. +This is the default client authentication. +- `CLIENT_SECRET_POST`: Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization +Server in accordance with Section 2.3.1 of OAuth 2.0 [RFC6749] by including the Client Credentials in the request body. +- `CLIENT_SECRET_JWT`: Clients that have received a client_secret value from the Authorization Server create a JWT using an HMAC SHA +algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of +the UTF-8 representation of the client_secret as the shared key. +The Client authenticates in accordance with JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and +Authorization Grants [OAuth.JWT] and Assertion Framework for OAuth 2.0 Client Authentication and Authorization +Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `PRIVATE_KEY_JWT`: Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with +JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.JWT] and Assertion +Framework for OAuth 2.0 Client Authentication and Authorization Grants [OAuth.Assertions]. + +The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following +OPTIONAL Claim Values. + +Required: +`iss, sub, aud, jti, exp` + +Optional: +`iat` +- `NONE`: The Client does not authenticate itself at the Token Endpoint, either because it uses only the Implicit Flow (and so +does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication +mechanism. |`token-endpoint-uri` |URI |{nbsp} |URI of a token endpoint used to obtain a JWT based on the authentication - code. - If not defined, it is obtained from oidcMetadata(Resource), if that is not defined - an attempt is made to use identityUri(URI)/oauth2/v1/token. +code. +If not defined, it is obtained from oidcMetadata(Resource), if that is not defined +an attempt is made to use identityUri(URI)/oauth2/v1/token. |`validate-jwt-with-jwk` |boolean |`true` |Use JWK (a set of keys to validate signatures of JWT) to validate tokens. - Use this method when you want to use default values for JWK or introspection endpoint URI. +Use this method when you want to use default values for JWK or introspection endpoint URI. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_tracing_Tracer.adoc b/docs/src/main/asciidoc/config/io_helidon_tracing_Tracer.adoc index 60019ba1ad4..0ea887603a7 100644 --- a/docs/src/main/asciidoc/config/io_helidon_tracing_Tracer.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_tracing_Tracer.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2023 Oracle and/or its affiliates. + Copyright (c) 2023, 2024 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -52,12 +52,33 @@ This is a standalone configuration type, prefix from configuration root: `tracin |`max-queue-size` |int |`2048` |Maximum Queue Size of exporter requests. |`private-key-pem` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Private key in PEM format. |`propagation` |PropagationFormat[] (B3, B3_SINGLE, JAEGER, W3C) |`JAEGER` |Add propagation format to use. + +Allowed values: + +- `B3`: The Zipkin B3 trace context propagation format using multiple headers. +- `B3_SINGLE`: B3 trace context propagation using a single header. +- `JAEGER`: The Jaeger trace context propagation format. +- `W3C`: The W3C trace context propagation format. + |`sampler-param` |Number |`1` |The sampler parameter (number). |`sampler-type` |SamplerType (CONSTANT, RATIO) |`CONSTANT` |Sampler type. - See Sampler types. +See https://www.jaegertracing.io/docs/latest/sampling/#client-sampling-configuration[Sampler types]. + +Allowed values: + +- `CONSTANT`: Constant sampler always makes the same decision for all traces. +It either samples all traces `1` or none of them `0`. +- `RATIO`: Ratio of the requests to sample, double value. + |`schedule-delay` |Duration |`PT5S` |Schedule Delay of exporter requests. |`span-processor-type` |SpanProcessorType (SIMPLE, BATCH) |`batch` |Span Processor type used. + +Allowed values: + +- `SIMPLE`: Simple Span Processor. +- `BATCH`: Batch Span Processor. + |`trusted-cert-pem` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Trusted certificates in PEM format. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_tracing_providers_jaeger_JaegerTracerBuilder.adoc b/docs/src/main/asciidoc/config/io_helidon_tracing_providers_jaeger_JaegerTracerBuilder.adoc index 60019ba1ad4..0ea887603a7 100644 --- a/docs/src/main/asciidoc/config/io_helidon_tracing_providers_jaeger_JaegerTracerBuilder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_tracing_providers_jaeger_JaegerTracerBuilder.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2023 Oracle and/or its affiliates. + Copyright (c) 2023, 2024 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -52,12 +52,33 @@ This is a standalone configuration type, prefix from configuration root: `tracin |`max-queue-size` |int |`2048` |Maximum Queue Size of exporter requests. |`private-key-pem` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Private key in PEM format. |`propagation` |PropagationFormat[] (B3, B3_SINGLE, JAEGER, W3C) |`JAEGER` |Add propagation format to use. + +Allowed values: + +- `B3`: The Zipkin B3 trace context propagation format using multiple headers. +- `B3_SINGLE`: B3 trace context propagation using a single header. +- `JAEGER`: The Jaeger trace context propagation format. +- `W3C`: The W3C trace context propagation format. + |`sampler-param` |Number |`1` |The sampler parameter (number). |`sampler-type` |SamplerType (CONSTANT, RATIO) |`CONSTANT` |Sampler type. - See Sampler types. +See https://www.jaegertracing.io/docs/latest/sampling/#client-sampling-configuration[Sampler types]. + +Allowed values: + +- `CONSTANT`: Constant sampler always makes the same decision for all traces. +It either samples all traces `1` or none of them `0`. +- `RATIO`: Ratio of the requests to sample, double value. + |`schedule-delay` |Duration |`PT5S` |Schedule Delay of exporter requests. |`span-processor-type` |SpanProcessorType (SIMPLE, BATCH) |`batch` |Span Processor type used. + +Allowed values: + +- `SIMPLE`: Simple Span Processor. +- `BATCH`: Batch Span Processor. + |`trusted-cert-pem` |xref:{rootdir}/config/io_helidon_common_configurable_Resource.adoc[Resource] |{nbsp} |Trusted certificates in PEM format. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_tracing_providers_zipkin_ZipkinTracerBuilder.adoc b/docs/src/main/asciidoc/config/io_helidon_tracing_providers_zipkin_ZipkinTracerBuilder.adoc index f8e347a05fa..42bed06586c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_tracing_providers_zipkin_ZipkinTracerBuilder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_tracing_providers_zipkin_ZipkinTracerBuilder.adoc @@ -47,7 +47,13 @@ This is a standalone configuration type, prefix from configuration root: `tracin |key |type |default value |description |`api-version` |Version (V1, V2) |`V2` |Version of Zipkin API to use. - Defaults to Version.V2. +Defaults to Version.V2. + +Allowed values: + +- `V1`: Version 1. +- `V2`: Version 2. + |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpClientConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpClientConfig.adoc index 80fc3cff6d5..2cc17d11de9 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpClientConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpClientConfig.adoc @@ -44,97 +44,97 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.api/io/helidon/webclient/api/ |`base-uri` |ClientUri |{nbsp} |Base uri used by the client in all requests. - Base uri of the client requests +Base uri of the client requests |`connect-timeout` |Duration |{nbsp} |Connect timeout. - Connect timeout - See io.helidon.common.socket.SocketOptions.connectTimeout() +Connect timeout +See io.helidon.common.socket.SocketOptions.connectTimeout() |`connection-cache-size` |int |`256` |Maximal size of the connection cache. - For most HTTP protocols, we may cache connections to various endpoints for keep alive (or stream reuse in case of HTTP/2). - This option limits the size. Setting this number lower than the "usual" number of target services will cause connections - to be closed and reopened frequently. +For most HTTP protocols, we may cache connections to various endpoints for keep alive (or stream reuse in case of HTTP/2). +This option limits the size. Setting this number lower than the "usual" number of target services will cause connections +to be closed and reopened frequently. |`content-encoding` |xref:{rootdir}/config/io_helidon_http_encoding_ContentEncodingContext.adoc[ContentEncodingContext] |{nbsp} |Configure the listener specific io.helidon.http.encoding.ContentEncodingContext. - This method discards all previously registered ContentEncodingContext. - If no content encoding context is registered, default encoding context is used. +This method discards all previously registered ContentEncodingContext. +If no content encoding context is registered, default encoding context is used. - Content encoding context +Content encoding context |`cookie-manager` |xref:{rootdir}/config/io_helidon_webclient_api_WebClientCookieManager.adoc[WebClientCookieManager] |{nbsp} |WebClient cookie manager. - Cookie manager to use +Cookie manager to use |`default-headers` |Map<string, string> |{nbsp} |Default headers to be used in every request from configuration. - Default headers +Default headers |`follow-redirects` |boolean |`true` |Whether to follow redirects. - Whether to follow redirects +Whether to follow redirects |`keep-alive` |boolean |`true` |Determines if connection keep alive is enabled (NOT socket keep alive, but HTTP connection keep alive, to re-use - the same connection for multiple requests). +the same connection for multiple requests). - Keep alive for this connection - See io.helidon.common.socket.SocketOptions.socketKeepAlive() +Keep alive for this connection +See io.helidon.common.socket.SocketOptions.socketKeepAlive() |`max-in-memory-entity` |int |`131072` |If the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize performance. - If bigger, streaming will be used. +If bigger, streaming will be used. - Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such - cases, this option is ignored. Default is 128Kb. +Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such +cases, this option is ignored. Default is 128Kb. - Maximal number of bytes to buffer in memory for supported writers +Maximal number of bytes to buffer in memory for supported writers |`max-redirects` |int |`10` |Max number of followed redirects. - This is ignored if followRedirects() option is `false`. +This is ignored if followRedirects() option is `false`. - Max number of followed redirects +Max number of followed redirects |`media-context` |xref:{rootdir}/config/io_helidon_http_media_MediaContext.adoc[MediaContext] |`create()` |Configure the listener specific io.helidon.http.media.MediaContext. - This method discards all previously registered MediaContext. - If no media context is registered, default media context is used. +This method discards all previously registered MediaContext. +If no media context is registered, default media context is used. - Media context -|`media-type-parser-mode` |ParserMode |`ParserMode.STRICT` |Configure media type parsing mode for HTTP `Content-Type` header. +Media context +|`media-type-parser-mode` |ParserMode (STRICT, RELAXED) |`ParserMode.STRICT` |Configure media type parsing mode for HTTP `Content-Type` header. - Media type parsing mode +Media type parsing mode |`properties` |Map<string, string> |{nbsp} |Properties configured for this client. These properties are propagated through client request, to be used by - services (and possibly for other purposes). +services (and possibly for other purposes). - Map of client properties +Map of client properties |`proxy` |xref:{rootdir}/config/io_helidon_webclient_api_Proxy.adoc[Proxy] |{nbsp} |Proxy configuration to be used for requests. - Proxy to use, defaults to Proxy.noProxy() +Proxy to use, defaults to Proxy.noProxy() |`read-continue-timeout` |Duration |`PT1S` |Socket 100-Continue read timeout. Default is 1 second. - This read timeout is used when 100-Continue is sent by the client, before it sends an entity. +This read timeout is used when 100-Continue is sent by the client, before it sends an entity. - Read 100-Continue timeout duration +Read 100-Continue timeout duration |`read-timeout` |Duration |{nbsp} |Read timeout. - Read timeout - See io.helidon.common.socket.SocketOptions.readTimeout() +Read timeout +See io.helidon.common.socket.SocketOptions.readTimeout() |`relative-uris` |boolean |`false` |Can be set to `true` to force the use of relative URIs in all requests, - regardless of the presence or absence of proxies or no-proxy lists. +regardless of the presence or absence of proxies or no-proxy lists. - Relative URIs flag +Relative URIs flag |`send-expect-continue` |boolean |`true` |Whether Expect-100-Continue header is sent to verify server availability before sending an entity. - Defaults to `true`. - +Defaults to `true`. - Whether Expect:100-Continue header should be sent on streamed transfers + +Whether Expect:100-Continue header should be sent on streamed transfers |`services` |io.helidon.webclient.spi.WebClientService[] (service provider interface) |{nbsp} |WebClient services. - Services to use with this web client +Services to use with this web client |`share-connection-cache` |boolean |`true` |Whether to share connection cache between all the WebClient instances in JVM. - True if connection cache is shared +True if connection cache is shared |`socket-options` |xref:{rootdir}/config/io_helidon_common_socket_SocketOptions.adoc[SocketOptions] |{nbsp} |Socket options for connections opened by this client. - If there is a value explicitly configured on this type and on the socket options, - the one configured on this type's builder will win: +If there is a value explicitly configured on this type and on the socket options, +the one configured on this type's builder will win: - readTimeout() - connectTimeout() Socket options |`tls` |xref:{rootdir}/config/io_helidon_common_tls_Tls.adoc[Tls] |{nbsp} |TLS configuration for any TLS request from this client. - TLS can also be configured per request. - TLS is used when the protocol is set to `https`. +TLS can also be configured per request. +TLS is used when the protocol is set to `https`. - TLS configuration to use +TLS configuration to use |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpConfigBase.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpConfigBase.adoc index a073af63be0..e111041267e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpConfigBase.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_api_HttpConfigBase.adoc @@ -44,36 +44,36 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.api/io/helidon/webclient/api/ |`connect-timeout` |Duration |{nbsp} |Connect timeout. - Connect timeout - See io.helidon.common.socket.SocketOptions.connectTimeout() +Connect timeout +See io.helidon.common.socket.SocketOptions.connectTimeout() |`follow-redirects` |boolean |`true` |Whether to follow redirects. - Whether to follow redirects +Whether to follow redirects |`keep-alive` |boolean |`true` |Determines if connection keep alive is enabled (NOT socket keep alive, but HTTP connection keep alive, to re-use - the same connection for multiple requests). +the same connection for multiple requests). - Keep alive for this connection - See io.helidon.common.socket.SocketOptions.socketKeepAlive() +Keep alive for this connection +See io.helidon.common.socket.SocketOptions.socketKeepAlive() |`max-redirects` |int |`10` |Max number of followed redirects. - This is ignored if followRedirects() option is `false`. +This is ignored if followRedirects() option is `false`. - Max number of followed redirects +Max number of followed redirects |`properties` |Map<string, string> |{nbsp} |Properties configured for this client. These properties are propagated through client request, to be used by - services (and possibly for other purposes). +services (and possibly for other purposes). - Map of client properties +Map of client properties |`proxy` |xref:{rootdir}/config/io_helidon_webclient_api_Proxy.adoc[Proxy] |{nbsp} |Proxy configuration to be used for requests. - Proxy to use, defaults to Proxy.noProxy() +Proxy to use, defaults to Proxy.noProxy() |`read-timeout` |Duration |{nbsp} |Read timeout. - Read timeout - See io.helidon.common.socket.SocketOptions.readTimeout() +Read timeout +See io.helidon.common.socket.SocketOptions.readTimeout() |`tls` |xref:{rootdir}/config/io_helidon_common_tls_Tls.adoc[Tls] |{nbsp} |TLS configuration for any TLS request from this client. - TLS can also be configured per request. - TLS is used when the protocol is set to `https`. +TLS can also be configured per request. +TLS is used when the protocol is set to `https`. - TLS configuration to use +TLS configuration to use |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_api_Proxy.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_api_Proxy.adoc index 0ba4f37b433..d475c6b29d6 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_api_Proxy.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_api_Proxy.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2023 Oracle and/or its affiliates. + Copyright (c) 2023, 2024 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -45,7 +45,7 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.api/io/helidon/webclient/api/ |`host` |string |{nbsp} |Sets a new host value. |`no-proxy` |string[] |{nbsp} |Configure a host pattern that is not going through a proxy. - Options are: +Options are: - IP Address, such as `192.168.1.1` - IP V6 Address, such as `[2001:db8:85a3:8d3:1319:8a2e:370:7348]` @@ -58,6 +58,13 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.api/io/helidon/webclient/api/ |`password` |string |{nbsp} |Sets a new password for the proxy. |`port` |int |{nbsp} |Sets a port value. |`type` |ProxyType (NONE, SYSTEM, HTTP) |`HTTP` |Sets a new proxy type. + +Allowed values: + +- `NONE`: No proxy. +- `SYSTEM`: Proxy obtained from system. +- `HTTP`: HTTP proxy. + |`username` |string |{nbsp} |Sets a new username for the proxy. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClient.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClient.adoc index b00d5d8f6b2..c629ec6c50c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClient.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClient.adoc @@ -46,100 +46,100 @@ This is a standalone configuration type, prefix from configuration root: `client |`base-uri` |ClientUri |{nbsp} |Base uri used by the client in all requests. - Base uri of the client requests +Base uri of the client requests |`connect-timeout` |Duration |{nbsp} |Connect timeout. - Connect timeout - See io.helidon.common.socket.SocketOptions.connectTimeout() +Connect timeout +See io.helidon.common.socket.SocketOptions.connectTimeout() |`connection-cache-size` |int |`256` |Maximal size of the connection cache. - For most HTTP protocols, we may cache connections to various endpoints for keep alive (or stream reuse in case of HTTP/2). - This option limits the size. Setting this number lower than the "usual" number of target services will cause connections - to be closed and reopened frequently. +For most HTTP protocols, we may cache connections to various endpoints for keep alive (or stream reuse in case of HTTP/2). +This option limits the size. Setting this number lower than the "usual" number of target services will cause connections +to be closed and reopened frequently. |`content-encoding` |xref:{rootdir}/config/io_helidon_http_encoding_ContentEncodingContext.adoc[ContentEncodingContext] |{nbsp} |Configure the listener specific io.helidon.http.encoding.ContentEncodingContext. - This method discards all previously registered ContentEncodingContext. - If no content encoding context is registered, default encoding context is used. +This method discards all previously registered ContentEncodingContext. +If no content encoding context is registered, default encoding context is used. - Content encoding context +Content encoding context |`cookie-manager` |xref:{rootdir}/config/io_helidon_webclient_api_WebClientCookieManager.adoc[WebClientCookieManager] |{nbsp} |WebClient cookie manager. - Cookie manager to use +Cookie manager to use |`default-headers` |Map<string, string> |{nbsp} |Default headers to be used in every request from configuration. - Default headers +Default headers |`follow-redirects` |boolean |`true` |Whether to follow redirects. - Whether to follow redirects +Whether to follow redirects |`keep-alive` |boolean |`true` |Determines if connection keep alive is enabled (NOT socket keep alive, but HTTP connection keep alive, to re-use - the same connection for multiple requests). +the same connection for multiple requests). - Keep alive for this connection - See io.helidon.common.socket.SocketOptions.socketKeepAlive() +Keep alive for this connection +See io.helidon.common.socket.SocketOptions.socketKeepAlive() |`max-in-memory-entity` |int |`131072` |If the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize performance. - If bigger, streaming will be used. +If bigger, streaming will be used. - Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such - cases, this option is ignored. Default is 128Kb. +Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such +cases, this option is ignored. Default is 128Kb. - Maximal number of bytes to buffer in memory for supported writers +Maximal number of bytes to buffer in memory for supported writers |`max-redirects` |int |`10` |Max number of followed redirects. - This is ignored if followRedirects() option is `false`. +This is ignored if followRedirects() option is `false`. - Max number of followed redirects +Max number of followed redirects |`media-context` |xref:{rootdir}/config/io_helidon_http_media_MediaContext.adoc[MediaContext] |`create()` |Configure the listener specific io.helidon.http.media.MediaContext. - This method discards all previously registered MediaContext. - If no media context is registered, default media context is used. +This method discards all previously registered MediaContext. +If no media context is registered, default media context is used. - Media context -|`media-type-parser-mode` |ParserMode |`ParserMode.STRICT` |Configure media type parsing mode for HTTP `Content-Type` header. +Media context +|`media-type-parser-mode` |ParserMode (STRICT, RELAXED) |`ParserMode.STRICT` |Configure media type parsing mode for HTTP `Content-Type` header. - Media type parsing mode +Media type parsing mode |`properties` |Map<string, string> |{nbsp} |Properties configured for this client. These properties are propagated through client request, to be used by - services (and possibly for other purposes). +services (and possibly for other purposes). - Map of client properties +Map of client properties |`protocol-configs` |io.helidon.webclient.spi.ProtocolConfig[] (service provider interface) |{nbsp} |Configuration of client protocols. - Client protocol configurations +Client protocol configurations |`proxy` |xref:{rootdir}/config/io_helidon_webclient_api_Proxy.adoc[Proxy] |{nbsp} |Proxy configuration to be used for requests. - Proxy to use, defaults to Proxy.noProxy() +Proxy to use, defaults to Proxy.noProxy() |`read-continue-timeout` |Duration |`PT1S` |Socket 100-Continue read timeout. Default is 1 second. - This read timeout is used when 100-Continue is sent by the client, before it sends an entity. +This read timeout is used when 100-Continue is sent by the client, before it sends an entity. - Read 100-Continue timeout duration +Read 100-Continue timeout duration |`read-timeout` |Duration |{nbsp} |Read timeout. - Read timeout - See io.helidon.common.socket.SocketOptions.readTimeout() +Read timeout +See io.helidon.common.socket.SocketOptions.readTimeout() |`relative-uris` |boolean |`false` |Can be set to `true` to force the use of relative URIs in all requests, - regardless of the presence or absence of proxies or no-proxy lists. +regardless of the presence or absence of proxies or no-proxy lists. - Relative URIs flag +Relative URIs flag |`send-expect-continue` |boolean |`true` |Whether Expect-100-Continue header is sent to verify server availability before sending an entity. - Defaults to `true`. - +Defaults to `true`. - Whether Expect:100-Continue header should be sent on streamed transfers + +Whether Expect:100-Continue header should be sent on streamed transfers |`services` |io.helidon.webclient.spi.WebClientService[] (service provider interface) |{nbsp} |WebClient services. - Services to use with this web client +Services to use with this web client |`share-connection-cache` |boolean |`true` |Whether to share connection cache between all the WebClient instances in JVM. - True if connection cache is shared +True if connection cache is shared |`socket-options` |xref:{rootdir}/config/io_helidon_common_socket_SocketOptions.adoc[SocketOptions] |{nbsp} |Socket options for connections opened by this client. - If there is a value explicitly configured on this type and on the socket options, - the one configured on this type's builder will win: +If there is a value explicitly configured on this type and on the socket options, +the one configured on this type's builder will win: - readTimeout() - connectTimeout() Socket options |`tls` |xref:{rootdir}/config/io_helidon_common_tls_Tls.adoc[Tls] |{nbsp} |TLS configuration for any TLS request from this client. - TLS can also be configured per request. - TLS is used when the protocol is set to `https`. +TLS can also be configured per request. +TLS is used when the protocol is set to `https`. - TLS configuration to use +TLS configuration to use |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClientCookieManager.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClientCookieManager.adoc index 19bf5de5341..7e5c19093f2 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClientCookieManager.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_api_WebClientCookieManager.adoc @@ -44,13 +44,13 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.api/io/helidon/webclient/api/ |`automatic-store-enabled` |boolean |`false` |Whether automatic cookie store is enabled or not. - Status of cookie store +Status of cookie store |`cookie-policy` |CookiePolicy |`java.net.CookiePolicy.ACCEPT_ORIGINAL_SERVER` |Current cookie policy for this client. - The cookie policy +The cookie policy |`default-cookies` |Map<string, string> |{nbsp} |Map of default cookies to include in all requests if cookies enabled. - Map of default cookies +Map of default cookies |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClient.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClient.adoc index 5fc378bd783..f02664d8442 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClient.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClient.adoc @@ -44,7 +44,7 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.grpc/io/helidon/webclient/grp |`protocol-config` |xref:{rootdir}/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc[GrpcClientProtocolConfig] |`create()` |gRPC specific configuration. - Protocol specific configuration +Protocol specific configuration |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc index b6b42c07985..00a6250c879 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_grpc_GrpcClientProtocolConfig.adoc @@ -43,28 +43,28 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.grpc/io/helidon/webclient/grp |key |type |default value |description |`abort-poll-time-expired` |boolean |`false` |Whether to continue retrying after a poll wait timeout expired or not. If a read - operation timeouts out and this flag is set to `false`, the event is logged - and the client will retry. Otherwise, an exception is thrown. +operation timeouts out and this flag is set to `false`, the event is logged +and the client will retry. Otherwise, an exception is thrown. - Abort timeout flag +Abort timeout flag |`heartbeat-period` |Duration |`PT0S` |How often to send a heartbeat (HTTP/2 ping) to check if the connection is still - alive. This is useful for long-running, streaming gRPC calls. It is turned off by - default but can be enabled by setting the period to a value greater than 0. +alive. This is useful for long-running, streaming gRPC calls. It is turned off by +default but can be enabled by setting the period to a value greater than 0. - Heartbeat period +Heartbeat period |`init-buffer-size` |int |`2048` |Initial buffer size used to serialize gRPC request payloads. Buffers shall grow - according to the payload size, but setting this initial buffer size to a larger value - may improve performance for certain applications. +according to the payload size, but setting this initial buffer size to a larger value +may improve performance for certain applications. - Initial buffer size +Initial buffer size |`name` |string |`grpc` |Name identifying this client protocol. Defaults to type. - Name of client protocol +Name of client protocol |`poll-wait-time` |Duration |`PT10S` |How long to wait for the next HTTP/2 data frame to arrive in underlying stream. - Whether this is a fatal error or not is controlled by abortPollTimeExpired(). +Whether this is a fatal error or not is controlled by abortPollTimeExpired(). - Poll time as a duration - See io.helidon.common.socket.SocketOptions.readTimeout() +Poll time as a duration +See io.helidon.common.socket.SocketOptions.readTimeout() |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_http1_Http1ClientProtocolConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_http1_Http1ClientProtocolConfig.adoc index 8e05c9db49d..e83a2cb8eeb 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_http1_Http1ClientProtocolConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_http1_Http1ClientProtocolConfig.adoc @@ -44,27 +44,27 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.http1/io/helidon/webclient/ht |`default-keep-alive` |boolean |`true` |Whether to use keep alive by default. - `true` for keeping connections alive and re-using them for multiple requests (default), `false` - to create a new connection for each request +`true` for keeping connections alive and re-using them for multiple requests (default), `false` + to create a new connection for each request |`max-header-size` |int |`16384` |Configure the maximum allowed header size of the response. - maximum header size +Maximum header size |`max-status-line-length` |int |`256` |Configure the maximum allowed length of the status line from the response. - Maximum status line length +Maximum status line length |`name` |string |`http_1_1` | |`validate-request-headers` |boolean |`false` |Sets whether the request header format is validated or not. - Defaults to `false` as user has control on the header creation. - + Defaults to `false` as user has control on the header creation. - Whether request header validation should be enabled + +Whether request header validation should be enabled |`validate-response-headers` |boolean |`true` |Sets whether the response header format is validated or not. - Defaults to `true`. - + Defaults to `true`. + - Whether response header validation should be enabled +Whether response header validation should be enabled |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_http2_Http2ClientProtocolConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_http2_Http2ClientProtocolConfig.adoc index 9e0e74061d0..a5f7112df8b 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_http2_Http2ClientProtocolConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_http2_Http2ClientProtocolConfig.adoc @@ -44,45 +44,49 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.http2/io/helidon/webclient/ht |`flow-control-block-timeout` |Duration |`PT0.1S` |Timeout for blocking between windows size check iterations. - Timeout +Timeout |`initial-window-size` |int |`65535` |Configure INITIAL_WINDOW_SIZE setting for new HTTP/2 connections. - Sends to the server the size of the largest frame payload client is willing to receive. - Defaults to io.helidon.http.http2.WindowSize.DEFAULT_WIN_SIZE. +Sends to the server the size of the largest frame payload client is willing to receive. +Defaults to io.helidon.http.http2.WindowSize.DEFAULT_WIN_SIZE. - Units of octets +Units of octets |`max-frame-size` |int |`16384` |Configure initial MAX_FRAME_SIZE setting for new HTTP/2 connections. - Maximum size of data frames in bytes the client is prepared to accept from the server. - Default value is 2^14(16_384). +Maximum size of data frames in bytes the client is prepared to accept from the server. +Default value is 2^14(16_384). - Data frame size in bytes between 2^14(16_384) and 2^24-1(16_777_215) +Data frame size in bytes between 2^14(16_384) and 2^24-1(16_777_215) |`max-header-list-size` |long |`-1` |Configure initial MAX_HEADER_LIST_SIZE setting for new HTTP/2 connections. - Sends to the server the maximum header field section size client is prepared to accept. - Defaults to `-1`, which means "unconfigured". +Sends to the server the maximum header field section size client is prepared to accept. +Defaults to `-1`, which means "unconfigured". - Units of octets +Units of octets |`name` |string |`h2` | |`ping` |boolean |`false` |Check healthiness of cached connections with HTTP/2.0 ping frame. - Defaults to `false`. +Defaults to `false`. - Use ping if true +Use ping if true |`ping-timeout` |Duration |`PT0.5S` |Timeout for ping probe used for checking healthiness of cached connections. - Defaults to `PT0.5S`, which means 500 milliseconds. +Defaults to `PT0.5S`, which means 500 milliseconds. - Timeout +Timeout |`prior-knowledge` |boolean |`false` |Prior knowledge of HTTP/2 capabilities of the server. If server we are connecting to does not - support HTTP/2 and prior knowledge is set to `false`, only features supported by HTTP/1 will be available - and attempts to use HTTP/2 specific will throw an UnsupportedOperationException. -

Plain text connection

- If prior knowledge is set to `true`, we will not attempt an upgrade of connection and use prior knowledge. - If prior knowledge is set to `false`, we will initiate an HTTP/1 connection and upgrade it to HTTP/2, - if supported by the server. - plaintext connection (`h2c`). -

TLS protected connection

- If prior knowledge is set to `true`, we will negotiate protocol using HTTP/2 only, failing if not supported. - if prior knowledge is set to `false`, we will negotiate protocol using both HTTP/2 and HTTP/1, using the protocol - supported by server. - - Whether to use prior knowledge of HTTP/2 +support HTTP/2 and prior knowledge is set to `false`, only features supported by HTTP/1 will be available +and attempts to use HTTP/2 specific will throw an UnsupportedOperationException. + +[.underline]#Plain text connection# + +If prior knowledge is set to `true`, we will not attempt an upgrade of connection and use prior knowledge. +If prior knowledge is set to `false`, we will initiate an HTTP/1 connection and upgrade it to HTTP/2, +if supported by the server. +plaintext connection (`h2c`). + +[.underline]#TLS protected connection# + +If prior knowledge is set to `true`, we will negotiate protocol using HTTP/2 only, failing if not supported. +if prior knowledge is set to `false`, we will negotiate protocol using both HTTP/2 and HTTP/1, using the protocol +supported by server. + +Whether to use prior knowledge of HTTP/2 |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webclient_websocket_WsClient.adoc b/docs/src/main/asciidoc/config/io_helidon_webclient_websocket_WsClient.adoc index cde9c2dc9ae..d6a01499062 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webclient_websocket_WsClient.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webclient_websocket_WsClient.adoc @@ -44,7 +44,7 @@ Type: link:{javadoc-base-url}/io.helidon.webclient.websocket/io/helidon/webclien |`protocol-config` |xref:{rootdir}/config/io_helidon_webclient_websocket_WsClientProtocolConfig.adoc[WsClientProtocolConfig] |`create()` |WebSocket specific configuration. - Protocol specific configuration +Protocol specific configuration |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_ConnectionConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_ConnectionConfig.adoc index c2918e61ad4..1f61d668819 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_ConnectionConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_ConnectionConfig.adoc @@ -43,40 +43,40 @@ Type: link:{javadoc-base-url}/io.helidon.webserver/io/helidon/webserver/Connecti |key |type |default value |description |`connect-timeout` |Duration |`PT10S` |Connect timeout. - Default is DEFAULT_CONNECT_TIMEOUT_DURATION. +Default is DEFAULT_CONNECT_TIMEOUT_DURATION. - Connect timeout +Connect timeout |`keep-alive` |boolean |`true` |Configure socket keep alive. - Default is `true`. +Default is `true`. - Keep alive - See java.net.StandardSocketOptions.SO_KEEPALIVE +Keep alive +See java.net.StandardSocketOptions.SO_KEEPALIVE |`read-timeout` |Duration |`PT30S` |Read timeout. - Default is DEFAULT_READ_TIMEOUT_DURATION +Default is DEFAULT_READ_TIMEOUT_DURATION - Read timeout +Read timeout |`receive-buffer-size` |int |`32768` |Socket receive buffer size. - Default is DEFAULT_SO_BUFFER_SIZE. +Default is DEFAULT_SO_BUFFER_SIZE. - Buffer size, in bytes - See java.net.StandardSocketOptions.SO_RCVBUF +Buffer size, in bytes +See java.net.StandardSocketOptions.SO_RCVBUF |`reuse-address` |boolean |`true` |Socket reuse address. - Default is `true`. +Default is `true`. - Whether to reuse address - See java.net.StandardSocketOptions.SO_REUSEADDR +Whether to reuse address +See java.net.StandardSocketOptions.SO_REUSEADDR |`send-buffer-size` |int |`32768` |Socket send buffer size. - Default is DEFAULT_SO_BUFFER_SIZE. +Default is DEFAULT_SO_BUFFER_SIZE. - Buffer size, in bytes - See java.net.StandardSocketOptions.SO_SNDBUF -|`tcp-no-delay` |boolean |`false` |Disable Nagle's algorithm by setting - TCP_NODELAY to true. This can result in better performance on Mac or newer linux kernels for some - payload types. - Default is `false`. +Buffer size, in bytes +See java.net.StandardSocketOptions.SO_SNDBUF +|`tcp-no-delay` |boolean |`false` |Disable https://en.wikipedia.org/wiki/Nagle%27s_algorithm[Nagle's algorithm] by setting +TCP_NODELAY to true. This can result in better performance on Mac or newer linux kernels for some +payload types. +Default is `false`. - Whether to use TCP_NODELAY, defaults to `false` - See java.net.StandardSocketOptions.TCP_NODELAY +Whether to use TCP_NODELAY, defaults to `false` +See java.net.StandardSocketOptions.TCP_NODELAY |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_ListenerConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_ListenerConfig.adoc index a77b8f500ba..d491bf59fa4 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_ListenerConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_ListenerConfig.adoc @@ -44,72 +44,72 @@ Type: link:{javadoc-base-url}/io.helidon.webserver/io/helidon/webserver/Listener |`backlog` |int |`1024` |Accept backlog. - Backlog +Backlog |`connection-config` |xref:{rootdir}/config/io_helidon_webserver_ConnectionConfig.adoc[ConnectionConfig] |{nbsp} |Configuration of a connection (established from client against our server). - Connection configuration +Connection configuration |`connection-options` |xref:{rootdir}/config/io_helidon_common_socket_SocketOptions.adoc[SocketOptions] |{nbsp} |Options for connections accepted by this listener. - This is not used to setup server connection. +This is not used to setup server connection. - Socket options +Socket options |`content-encoding` |xref:{rootdir}/config/io_helidon_http_encoding_ContentEncodingContext.adoc[ContentEncodingContext] |{nbsp} |Configure the listener specific io.helidon.http.encoding.ContentEncodingContext. - This method discards all previously registered ContentEncodingContext. - If no content encoding context is registered, content encoding context of the webserver would be used. +This method discards all previously registered ContentEncodingContext. +If no content encoding context is registered, content encoding context of the webserver would be used. - Content encoding context +Content encoding context |`host` |string |`0.0.0.0` |Host of the default socket. Defaults to all host addresses (`0.0.0.0`). - Host address to listen on (for the default socket) +Host address to listen on (for the default socket) |`idle-connection-period` |Duration |`PT2M` |How often should we check for idleConnectionTimeout(). - Defaults to `PT2M` (2 minutes). +Defaults to `PT2M` (2 minutes). - Period of checking for idle connections +Period of checking for idle connections |`idle-connection-timeout` |Duration |`PT5M` |How long should we wait before closing a connection that has no traffic on it. - Defaults to `PT5M` (5 minutes). Note that the timestamp is refreshed max. once per second, so this setting - would be useless if configured for shorter periods of time (also not a very good support for connection keep alive, - if the connections are killed so soon anyway). +Defaults to `PT5M` (5 minutes). Note that the timestamp is refreshed max. once per second, so this setting +would be useless if configured for shorter periods of time (also not a very good support for connection keep alive, +if the connections are killed so soon anyway). - Timeout of idle connections +Timeout of idle connections |`max-concurrent-requests` |int |`-1` |Limits the number of requests that can be executed at the same time (the number of active virtual threads of requests). - Defaults to `-1`, meaning "unlimited" - what the system allows. - Also make sure that this number is higher than the expected time it takes to handle a single request in your application, - as otherwise you may stop in-progress requests. +Defaults to `-1`, meaning "unlimited" - what the system allows. +Also make sure that this number is higher than the expected time it takes to handle a single request in your application, +as otherwise you may stop in-progress requests. - Number of requests that can be processed on this listener, regardless of protocol +Number of requests that can be processed on this listener, regardless of protocol |`max-in-memory-entity` |int |`131072` |If the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize - performance when writing it. - If bigger, streaming will be used. +performance when writing it. +If bigger, streaming will be used. - Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such - cases, this option is ignored. +Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such +cases, this option is ignored. - Default is 128Kb. +Default is 128Kb. - Maximal number of bytes to buffer in memory for supported writers +Maximal number of bytes to buffer in memory for supported writers |`max-payload-size` |long |`-1` |Maximal number of bytes an entity may have. - If io.helidon.http.HeaderNames.CONTENT_LENGTH is used, this is checked immediately, - if io.helidon.http.HeaderValues.TRANSFER_ENCODING_CHUNKED is used, we will fail when the - number of bytes read would exceed the max payload size. - Defaults to unlimited (`-1`). +If io.helidon.http.HeaderNames.CONTENT_LENGTH is used, this is checked immediately, +if io.helidon.http.HeaderValues.TRANSFER_ENCODING_CHUNKED is used, we will fail when the +number of bytes read would exceed the max payload size. +Defaults to unlimited (`-1`). - Maximal number of bytes of entity +Maximal number of bytes of entity |`max-tcp-connections` |int |`-1` |Limits the number of connections that can be opened at a single point in time. - Defaults to `-1`, meaning "unlimited" - what the system allows. +Defaults to `-1`, meaning "unlimited" - what the system allows. - Number of TCP connections that can be opened to this listener, regardless of protocol +Number of TCP connections that can be opened to this listener, regardless of protocol |`media-context` |xref:{rootdir}/config/io_helidon_http_media_MediaContext.adoc[MediaContext] |{nbsp} |Configure the listener specific io.helidon.http.media.MediaContext. - This method discards all previously registered MediaContext. - If no media context is registered, media context of the webserver would be used. +This method discards all previously registered MediaContext. +If no media context is registered, media context of the webserver would be used. - Media context +Media context |`name` |string |`@default` |Name of this socket. Defaults to `@default`. - Must be defined if more than one socket is needed. +Must be defined if more than one socket is needed. - Name of the socket +Name of the socket |`port` |int |`0` |Port of the default socket. - If configured to `0` (the default), server starts on a random port. +If configured to `0` (the default), server starts on a random port. - Port to listen on (for the default socket) +Port to listen on (for the default socket) |`protocols` |io.helidon.webserver.spi.ProtocolConfig[] (service provider interface) Such as: @@ -120,41 +120,45 @@ Such as: - xref:{rootdir}/config/io_helidon_webserver_http1_Http1Config.adoc[http_1_1 (Http1Config)] |{nbsp} |Configuration of protocols. This may be either protocol selectors, or protocol upgraders from HTTP/1.1. - As the order is not important (providers are ordered by weight by default), we can use a configuration as an object, - such as: - 
- protocols:
-   providers:
-     http_1_1:
-       max-prologue-length: 8192
-     http_2:
-       max-frame-size: 4096
-     websocket:
-       ....
-
- - All defined protocol configurations, loaded from service loader by default +As the order is not important (providers are ordered by weight by default), we can use a configuration as an object, +such as: + +---- + +protocols: + providers: + http_1_1: + max-prologue-length: 8192 + http_2: + max-frame-size: 4096 + websocket: + .... + +---- + + +All defined protocol configurations, loaded from service loader by default |`receive-buffer-size` |int |{nbsp} |Listener receive buffer size. - Buffer size in bytes +Buffer size in bytes |`requested-uri-discovery` |xref:{rootdir}/config/io_helidon_http_RequestedUriDiscoveryContext.adoc[RequestedUriDiscoveryContext] |{nbsp} |Requested URI discovery context. - Discovery context +Discovery context |`shutdown-grace-period` |Duration |`PT0.5S` |Grace period in ISO 8601 duration format to allow running tasks to complete before listener's shutdown. - Default is `500` milliseconds. +Default is `500` milliseconds. Configuration file values example: `PT0.5S`, `PT2S`. - Grace period +Grace period |`tls` |xref:{rootdir}/config/io_helidon_common_tls_Tls.adoc[Tls] |{nbsp} |Listener TLS configuration. - Tls of this configuration +Tls of this configuration |`write-buffer-size` |int |`512` |Initial buffer size in bytes of java.io.BufferedOutputStream created internally to - write data to a socket connection. Default is `512`. +write data to a socket connection. Default is `512`. - Initial buffer size used for writing +Initial buffer size used for writing |`write-queue-length` |int |`0` |Number of buffers queued for write operations. - Maximal number of queued writes, defaults to 0 +Maximal number of queued writes, defaults to 0 |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_WebServer.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_WebServer.adoc index 666d8727631..1053294af48 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_WebServer.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_WebServer.adoc @@ -46,19 +46,19 @@ This is a standalone configuration type, prefix from configuration root: `server |`backlog` |int |`1024` |Accept backlog. - Backlog +Backlog |`connection-config` |xref:{rootdir}/config/io_helidon_webserver_ConnectionConfig.adoc[ConnectionConfig] |{nbsp} |Configuration of a connection (established from client against our server). - Connection configuration +Connection configuration |`connection-options` |xref:{rootdir}/config/io_helidon_common_socket_SocketOptions.adoc[SocketOptions] |{nbsp} |Options for connections accepted by this listener. - This is not used to setup server connection. +This is not used to setup server connection. - Socket options +Socket options |`content-encoding` |xref:{rootdir}/config/io_helidon_http_encoding_ContentEncodingContext.adoc[ContentEncodingContext] |{nbsp} |Configure the listener specific io.helidon.http.encoding.ContentEncodingContext. - This method discards all previously registered ContentEncodingContext. - If no content encoding context is registered, content encoding context of the webserver would be used. +This method discards all previously registered ContentEncodingContext. +If no content encoding context is registered, content encoding context of the webserver would be used. - Content encoding context +Content encoding context |`features` |io.helidon.webserver.spi.ServerFeature[] (service provider interface) Such as: @@ -72,60 +72,60 @@ Such as: |{nbsp} |Server features allow customization of the server, listeners, or routings. - Server features +Server features |`host` |string |`0.0.0.0` |Host of the default socket. Defaults to all host addresses (`0.0.0.0`). - Host address to listen on (for the default socket) +Host address to listen on (for the default socket) |`idle-connection-period` |Duration |`PT2M` |How often should we check for idleConnectionTimeout(). - Defaults to `PT2M` (2 minutes). +Defaults to `PT2M` (2 minutes). - Period of checking for idle connections +Period of checking for idle connections |`idle-connection-timeout` |Duration |`PT5M` |How long should we wait before closing a connection that has no traffic on it. - Defaults to `PT5M` (5 minutes). Note that the timestamp is refreshed max. once per second, so this setting - would be useless if configured for shorter periods of time (also not a very good support for connection keep alive, - if the connections are killed so soon anyway). +Defaults to `PT5M` (5 minutes). Note that the timestamp is refreshed max. once per second, so this setting +would be useless if configured for shorter periods of time (also not a very good support for connection keep alive, +if the connections are killed so soon anyway). - Timeout of idle connections +Timeout of idle connections |`max-concurrent-requests` |int |`-1` |Limits the number of requests that can be executed at the same time (the number of active virtual threads of requests). - Defaults to `-1`, meaning "unlimited" - what the system allows. - Also make sure that this number is higher than the expected time it takes to handle a single request in your application, - as otherwise you may stop in-progress requests. +Defaults to `-1`, meaning "unlimited" - what the system allows. +Also make sure that this number is higher than the expected time it takes to handle a single request in your application, +as otherwise you may stop in-progress requests. - Number of requests that can be processed on this listener, regardless of protocol +Number of requests that can be processed on this listener, regardless of protocol |`max-in-memory-entity` |int |`131072` |If the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize - performance when writing it. - If bigger, streaming will be used. +performance when writing it. +If bigger, streaming will be used. - Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such - cases, this option is ignored. +Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such +cases, this option is ignored. - Default is 128Kb. +Default is 128Kb. - Maximal number of bytes to buffer in memory for supported writers +Maximal number of bytes to buffer in memory for supported writers |`max-payload-size` |long |`-1` |Maximal number of bytes an entity may have. - If io.helidon.http.HeaderNames.CONTENT_LENGTH is used, this is checked immediately, - if io.helidon.http.HeaderValues.TRANSFER_ENCODING_CHUNKED is used, we will fail when the - number of bytes read would exceed the max payload size. - Defaults to unlimited (`-1`). +If io.helidon.http.HeaderNames.CONTENT_LENGTH is used, this is checked immediately, +if io.helidon.http.HeaderValues.TRANSFER_ENCODING_CHUNKED is used, we will fail when the +number of bytes read would exceed the max payload size. +Defaults to unlimited (`-1`). - Maximal number of bytes of entity +Maximal number of bytes of entity |`max-tcp-connections` |int |`-1` |Limits the number of connections that can be opened at a single point in time. - Defaults to `-1`, meaning "unlimited" - what the system allows. +Defaults to `-1`, meaning "unlimited" - what the system allows. - Number of TCP connections that can be opened to this listener, regardless of protocol +Number of TCP connections that can be opened to this listener, regardless of protocol |`media-context` |xref:{rootdir}/config/io_helidon_http_media_MediaContext.adoc[MediaContext] |{nbsp} |Configure the listener specific io.helidon.http.media.MediaContext. - This method discards all previously registered MediaContext. - If no media context is registered, media context of the webserver would be used. +This method discards all previously registered MediaContext. +If no media context is registered, media context of the webserver would be used. - Media context +Media context |`name` |string |`@default` |Name of this socket. Defaults to `@default`. - Must be defined if more than one socket is needed. +Must be defined if more than one socket is needed. - Name of the socket +Name of the socket |`port` |int |`0` |Port of the default socket. - If configured to `0` (the default), server starts on a random port. +If configured to `0` (the default), server starts on a random port. - Port to listen on (for the default socket) +Port to listen on (for the default socket) |`protocols` |io.helidon.webserver.spi.ProtocolConfig[] (service provider interface) Such as: @@ -136,51 +136,55 @@ Such as: - xref:{rootdir}/config/io_helidon_webserver_http1_Http1Config.adoc[http_1_1 (Http1Config)] |{nbsp} |Configuration of protocols. This may be either protocol selectors, or protocol upgraders from HTTP/1.1. - As the order is not important (providers are ordered by weight by default), we can use a configuration as an object, - such as: - 
- protocols:
-   providers:
-     http_1_1:
-       max-prologue-length: 8192
-     http_2:
-       max-frame-size: 4096
-     websocket:
-       ....
-
- - All defined protocol configurations, loaded from service loader by default +As the order is not important (providers are ordered by weight by default), we can use a configuration as an object, +such as: + +---- + +protocols: + providers: + http_1_1: + max-prologue-length: 8192 + http_2: + max-frame-size: 4096 + websocket: + .... + +---- + + +All defined protocol configurations, loaded from service loader by default |`receive-buffer-size` |int |{nbsp} |Listener receive buffer size. - Buffer size in bytes +Buffer size in bytes |`requested-uri-discovery` |xref:{rootdir}/config/io_helidon_http_RequestedUriDiscoveryContext.adoc[RequestedUriDiscoveryContext] |{nbsp} |Requested URI discovery context. - Discovery context +Discovery context |`shutdown-grace-period` |Duration |`PT0.5S` |Grace period in ISO 8601 duration format to allow running tasks to complete before listener's shutdown. - Default is `500` milliseconds. +Default is `500` milliseconds. Configuration file values example: `PT0.5S`, `PT2S`. - Grace period +Grace period |`shutdown-hook` |boolean |`true` |When true the webserver registers a shutdown hook with the JVM Runtime. - Defaults to true. Set this to false such that a shutdown hook is not registered. +Defaults to true. Set this to false such that a shutdown hook is not registered. - Whether to register a shutdown hook +Whether to register a shutdown hook |`sockets` |xref:{rootdir}/config/io_helidon_webserver_ListenerConfig.adoc[Map<string, ListenerConfig>] |{nbsp} |Socket configurations. - Note that socket named WebServer.DEFAULT_SOCKET_NAME cannot be used, - configure the values on the server directly. +Note that socket named WebServer.DEFAULT_SOCKET_NAME cannot be used, +configure the values on the server directly. - Map of listener configurations, except for the default one +Map of listener configurations, except for the default one |`tls` |xref:{rootdir}/config/io_helidon_common_tls_Tls.adoc[Tls] |{nbsp} |Listener TLS configuration. - Tls of this configuration +Tls of this configuration |`write-buffer-size` |int |`512` |Initial buffer size in bytes of java.io.BufferedOutputStream created internally to - write data to a socket connection. Default is `512`. +write data to a socket connection. Default is `512`. - Initial buffer size used for writing +Initial buffer size used for writing |`write-queue-length` |int |`0` |Number of buffers queued for write operations. - Maximal number of queued writes, defaults to 0 +Maximal number of queued writes, defaults to 0 |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogConfig.adoc index 56eca6ce309..20f7eac049f 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogConfig.adoc @@ -54,79 +54,79 @@ This type provides the following service implementations: |`enabled` |boolean |`true` |Whether this feature will be enabled. - Whether enabled +Whether enabled |`format` |string |{nbsp} |The format for log entries (similar to the Apache `LogFormat`). - + ++++ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Log format elements
%hIP address of the remote hostHostLogEntry
%lThe client identity. This is always undefined in Helidon.UserIdLogEntry
%uUser ID as asserted by Helidon Security.UserLogEntry
%tThe timestampTimestampLogEntry
%rThe request line (`"GET /favicon.ico HTTP/1.0"`)RequestLineLogEntry
%sThe status code returned to the clientStatusLogEntry
%bThe entity size in bytesSizeLogEntry
%DThe time taken in microseconds (start of request until last byte written)TimeTakenLogEntry
%TThe time taken in seconds (start of request until last byte written), integerTimeTakenLogEntry
%{header-name}iValue of header `header-name`HeaderLogEntry
+ Log format elements + + %h + IP address of the remote host + HostLogEntry + + + %l + The client identity. This is always undefined in Helidon. + UserIdLogEntry + + + %u + User ID as asserted by Helidon Security. + UserLogEntry + + + %t + The timestamp + TimestampLogEntry + + + %r + The request line (`"GET /favicon.ico HTTP/1.0"`) + RequestLineLogEntry + + + %s + The status code returned to the client + StatusLogEntry + + + %b + The entity size in bytes + SizeLogEntry + + + %D + The time taken in microseconds (start of request until last byte written) + TimeTakenLogEntry + + + %T + The time taken in seconds (start of request until last byte written), integer + TimeTakenLogEntry + + + %{header-name}i + Value of header `header-name` + HeaderLogEntry + + ++++ - Format string, such as `%h %l %u %t %r %b %{Referer`i} +Format string, such as `%h %l %u %t %r %b %{Referer`i} |`logger-name` |string |`io.helidon.webserver.AccessLog` |Name of the logger used to obtain access log logger from System.getLogger(String). - Defaults to AccessLogFeature.DEFAULT_LOGGER_NAME. +Defaults to AccessLogFeature.DEFAULT_LOGGER_NAME. - Name of the logger to use +Name of the logger to use |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - The logger used will have the expected logger with a suffix of the socket name. +The logger used will have the expected logger with a suffix of the socket name. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`weight` |double |`1000.0` |Weight of the access log feature. We need to log access for anything happening on the server, so weight is high: - io.helidon.webserver.accesslog.AccessLogFeature.WEIGHT. +io.helidon.webserver.accesslog.AccessLogFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogFeature.adoc index 56eca6ce309..20f7eac049f 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_accesslog_AccessLogFeature.adoc @@ -54,79 +54,79 @@ This type provides the following service implementations: |`enabled` |boolean |`true` |Whether this feature will be enabled. - Whether enabled +Whether enabled |`format` |string |{nbsp} |The format for log entries (similar to the Apache `LogFormat`). - + ++++ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Log format elements
%hIP address of the remote hostHostLogEntry
%lThe client identity. This is always undefined in Helidon.UserIdLogEntry
%uUser ID as asserted by Helidon Security.UserLogEntry
%tThe timestampTimestampLogEntry
%rThe request line (`"GET /favicon.ico HTTP/1.0"`)RequestLineLogEntry
%sThe status code returned to the clientStatusLogEntry
%bThe entity size in bytesSizeLogEntry
%DThe time taken in microseconds (start of request until last byte written)TimeTakenLogEntry
%TThe time taken in seconds (start of request until last byte written), integerTimeTakenLogEntry
%{header-name}iValue of header `header-name`HeaderLogEntry
+ Log format elements + + %h + IP address of the remote host + HostLogEntry + + + %l + The client identity. This is always undefined in Helidon. + UserIdLogEntry + + + %u + User ID as asserted by Helidon Security. + UserLogEntry + + + %t + The timestamp + TimestampLogEntry + + + %r + The request line (`"GET /favicon.ico HTTP/1.0"`) + RequestLineLogEntry + + + %s + The status code returned to the client + StatusLogEntry + + + %b + The entity size in bytes + SizeLogEntry + + + %D + The time taken in microseconds (start of request until last byte written) + TimeTakenLogEntry + + + %T + The time taken in seconds (start of request until last byte written), integer + TimeTakenLogEntry + + + %{header-name}i + Value of header `header-name` + HeaderLogEntry + + ++++ - Format string, such as `%h %l %u %t %r %b %{Referer`i} +Format string, such as `%h %l %u %t %r %b %{Referer`i} |`logger-name` |string |`io.helidon.webserver.AccessLog` |Name of the logger used to obtain access log logger from System.getLogger(String). - Defaults to AccessLogFeature.DEFAULT_LOGGER_NAME. +Defaults to AccessLogFeature.DEFAULT_LOGGER_NAME. - Name of the logger to use +Name of the logger to use |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - The logger used will have the expected logger with a suffix of the socket name. +The logger used will have the expected logger with a suffix of the socket name. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`weight` |double |`1000.0` |Weight of the access log feature. We need to log access for anything happening on the server, so weight is high: - io.helidon.webserver.accesslog.AccessLogFeature.WEIGHT. +io.helidon.webserver.accesslog.AccessLogFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_context_ContextFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_context_ContextFeature.adoc index 47a1a21772a..9af38b286ed 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_context_ContextFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_context_ContextFeature.adoc @@ -54,11 +54,11 @@ This type provides the following service implementations: |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`weight` |double |`1100.0` |Weight of the context feature. As it is used by other features, the default is quite high: - io.helidon.webserver.context.ContextFeature.WEIGHT. +io.helidon.webserver.context.ContextFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsConfig.adoc index c57c843420d..ee25c9fcf1e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsConfig.adoc @@ -51,7 +51,7 @@ This type provides the following service implementations: |`enabled` |boolean |{nbsp} |This feature can be disabled. - Whether the feature is enabled +Whether the feature is enabled |=== @@ -65,11 +65,11 @@ This type provides the following service implementations: |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`weight` |double |`850.0` |Weight of the CORS feature. As it is used by other features, the default is quite high: - CorsFeature.WEIGHT. +CorsFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsFeature.adoc index c57c843420d..ee25c9fcf1e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_cors_CorsFeature.adoc @@ -51,7 +51,7 @@ This type provides the following service implementations: |`enabled` |boolean |{nbsp} |This feature can be disabled. - Whether the feature is enabled +Whether the feature is enabled |=== @@ -65,11 +65,11 @@ This type provides the following service implementations: |`sockets` |string[] |{nbsp} |List of sockets to register this feature on. If empty, it would get registered on all sockets. - Socket names to register on, defaults to empty (all available sockets) +Socket names to register on, defaults to empty (all available sockets) |`weight` |double |`850.0` |Weight of the CORS feature. As it is used by other features, the default is quite high: - CorsFeature.WEIGHT. +CorsFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ComponentMetricsSettings_Builder.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_grpc_GrpcTracingConfig.adoc similarity index 63% rename from docs/src/main/asciidoc/config/io_helidon_metrics_api_ComponentMetricsSettings_Builder.adoc rename to docs/src/main/asciidoc/config/io_helidon_webserver_grpc_GrpcTracingConfig.adoc index 7fb5649a7df..3bfc5e60bf7 100644 --- a/docs/src/main/asciidoc/config/io_helidon_metrics_api_ComponentMetricsSettings_Builder.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_grpc_GrpcTracingConfig.adoc @@ -17,25 +17,19 @@ /////////////////////////////////////////////////////////////////////////////// ifndef::rootdir[:rootdir: {docdir}/..] -:description: Configuration of io.helidon.metrics.api.ComponentMetricsSettings.Builder -:keywords: helidon, config, io.helidon.metrics.api.ComponentMetricsSettings.Builder -:basic-table-intro: The table below lists the configuration keys that configure io.helidon.metrics.api.ComponentMetricsSettings.Builder +:description: Configuration of io.helidon.webserver.grpc.GrpcTracingConfig +:keywords: helidon, config, io.helidon.webserver.grpc.GrpcTracingConfig +:basic-table-intro: The table below lists the configuration keys that configure io.helidon.webserver.grpc.GrpcTracingConfig include::{rootdir}/includes/attributes.adoc[] -= Builder (metrics.api.ComponentMetricsSettings) Configuration += GrpcTracingConfig (webserver.grpc) Configuration // tag::config[] -Type: link:{javadoc-base-url}/io.helidon.metrics.api.ComponentMetricsSettings/io/helidon/metrics/api/ComponentMetricsSettings/Builder.html[io.helidon.metrics.api.ComponentMetricsSettings.Builder] +Type: link:{javadoc-base-url}/io.helidon.webserver.grpc/io/helidon/webserver/grpc/GrpcTracingConfig.html[io.helidon.webserver.grpc.GrpcTracingConfig] -[source,text] -.Config key ----- -metrics ----- - == Configuration options @@ -48,7 +42,9 @@ metrics |=== |key |type |default value |description -|`enabled` |boolean |{nbsp} |Sets whether metrics should be enabled for the component. +|`enabled` |boolean |`true` |A flag indicating if tracing is enabled. +|`streaming` |boolean |`false` |A flag indicating streaming logging. +|`verbose` |boolean |`false` |A flag indicating verbose logging. |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_http1_Http1Config.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_http1_Http1Config.adoc index a72c8fbf80c..dfbd09abf48 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_http1_Http1Config.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_http1_Http1Config.adoc @@ -53,49 +53,49 @@ This type provides the following service implementations: |key |type |default value |description |`continue-immediately` |boolean |`false` |When true WebServer answers to expect continue with 100 continue immediately, - not waiting for user to actually request the data. +not waiting for user to actually request the data. - If `true` answer with 100 continue immediately after expect continue +If `true` answer with 100 continue immediately after expect continue |`max-headers-size` |int |`16384` |Maximal size of received headers in bytes. - Maximal header size -|`max-prologue-length` |int |`2048` |Maximal size of received HTTP prologue (GET /path HTTP/1.1). +Maximal header size +|`max-prologue-length` |int |`4096` |Maximal size of received HTTP prologue (GET /path HTTP/1.1). - Maximal size in bytes +Maximal size in bytes |`recv-log` |boolean |`true` |Logging of received packets. Uses trace and debug levels on logger of - Http1LoggingConnectionListener with suffix of `.recv``. +Http1LoggingConnectionListener with suffix of `.recv``. - `true` if logging should be enabled for received packets, `false` if no logging should be done +`true` if logging should be enabled for received packets, `false` if no logging should be done |`requested-uri-discovery` |xref:{rootdir}/config/io_helidon_http_RequestedUriDiscoveryContext.adoc[RequestedUriDiscoveryContext] |{nbsp} |Requested URI discovery settings. - Settings for computing the requested URI +Settings for computing the requested URI |`send-log` |boolean |`true` |Logging of sent packets. Uses trace and debug levels on logger of - Http1LoggingConnectionListener with suffix of `.send``. +Http1LoggingConnectionListener with suffix of `.send``. - `true` if logging should be enabled for sent packets, `false` if no logging should be done +`true` if logging should be enabled for sent packets, `false` if no logging should be done |`validate-path` |boolean |`true` |If set to false, any path is accepted (even containing illegal characters). - Whether to validate path +Whether to validate path |`validate-request-headers` |boolean |`true` |Whether to validate headers. - If set to false, any value is accepted, otherwise validates headers + known headers - are validated by format - (content length is always validated as it is part of protocol processing (other headers may be validated if - features use them)). +If set to false, any value is accepted, otherwise validates headers + known headers +are validated by format +(content length is always validated as it is part of protocol processing (other headers may be validated if +features use them)). - Defaults to `true`. - + Defaults to `true`. - Whether to validate headers + +Whether to validate headers |`validate-response-headers` |boolean |`false` |Whether to validate headers. - If set to false, any value is accepted, otherwise validates headers + known headers - are validated by format - (content length is always validated as it is part of protocol processing (other headers may be validated if - features use them)). +If set to false, any value is accepted, otherwise validates headers + known headers +are validated by format +(content length is always validated as it is part of protocol processing (other headers may be validated if +features use them)). + + Defaults to `false` as user has control on the header creation. - Defaults to `false` as user has control on the header creation. - - Whether to validate headers +Whether to validate headers |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_http2_Http2Config.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_http2_Http2Config.adoc index bb471c1a91b..fd1e8bee832 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_http2_Http2Config.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_http2_Http2Config.adoc @@ -53,75 +53,75 @@ This type provides the following service implementations: |key |type |default value |description |`flow-control-timeout` |Duration |`PT0.1S` |Outbound flow control blocking timeout configured as java.time.Duration - or text in ISO-8601 format. - Blocking timeout defines an interval to wait for the outbound window size changes(incoming window updates) - before the next blocking iteration. - Default value is `PT0.1S`. +or text in ISO-8601 format. +Blocking timeout defines an interval to wait for the outbound window size changes(incoming window updates) +before the next blocking iteration. +Default value is `PT0.1S`. + - ++++ - - - - -
ISO_8601 format examples:
PT0.1S100 milliseconds
PT0.5S500 milliseconds
PT2S2 seconds
+ *ISO_8601 format examples:* + PT0.1S100 milliseconds + PT0.5S500 milliseconds + PT2S2 seconds + ++++ - Duration - See ISO_8601 Durations +Duration +See https://en.wikipedia.org/wiki/ISO_8601.Durations[ISO_8601 Durations] |`initial-window-size` |int |`1048576` |This setting indicates the sender's maximum window size in bytes for stream-level flow control. - Default and maximum value is 231-1 = 2147483647 bytes. This setting affects the window size - of HTTP/2 connection. - Any value greater than 2147483647 causes an error. Any value smaller than initial window size causes an error. - See RFC 9113 section 6.9.1 for details. +Default and maximum value is 2^31^-1 = 2147483647 bytes. This setting affects the window size +of HTTP/2 connection. +Any value greater than 2147483647 causes an error. Any value smaller than initial window size causes an error. +See RFC 9113 section 6.9.1 for details. - Maximum window size in bytes +Maximum window size in bytes |`max-concurrent-streams` |long |`8192` |Maximum number of concurrent streams that the server will allow. - Defaults to `8192`. This limit is directional: it applies to the number of streams that the sender - permits the receiver to create. - It is recommended that this value be no smaller than 100 to not unnecessarily limit parallelism - See RFC 9113 section 6.5.2 for details. +Defaults to `8192`. This limit is directional: it applies to the number of streams that the sender +permits the receiver to create. +It is recommended that this value be no smaller than 100 to not unnecessarily limit parallelism +See RFC 9113 section 6.5.2 for details. - Maximal number of concurrent streams +Maximal number of concurrent streams |`max-empty-frames` |int |`10` |Maximum number of consecutive empty frames allowed on connection. - Max number of consecutive empty frames +Max number of consecutive empty frames |`max-frame-size` |int |`16384` |The size of the largest frame payload that the sender is willing to receive in bytes. - Default value is `16384` and maximum value is 224-1 = 16777215 bytes. - See RFC 9113 section 6.5.2 for details. +Default value is `16384` and maximum value is 2^24^-1 = 16777215 bytes. +See RFC 9113 section 6.5.2 for details. - Maximal frame size +Maximal frame size |`max-header-list-size` |long |`8192` |The maximum field section size that the sender is prepared to accept in bytes. - See RFC 9113 section 6.5.2 for details. - Default is 8192. +See RFC 9113 section 6.5.2 for details. +Default is 8192. - Maximal header list size in bytes +Maximal header list size in bytes |`max-rapid-resets` |int |`100` |Maximum number of rapid resets(stream RST sent by client before any data have been sent by server). - When reached within rapidResetCheckPeriod(), GOAWAY is sent to client and connection is closed. - Default value is `100`. +When reached within rapidResetCheckPeriod(), GOAWAY is sent to client and connection is closed. +Default value is `100`. - Maximum number of rapid resets - See CVE-2023-44487 +Maximum number of rapid resets +See https://nvd.nist.gov/vuln/detail/CVE-2023-44487[CVE-2023-44487] |`rapid-reset-check-period` |Duration |`PT10S` |Period for counting rapid resets(stream RST sent by client before any data have been sent by server). - Default value is `PT10S`. +Default value is `PT10S`. - Duration - See CVE-2023-44487 - See ISO_8601 Durations +Duration +See https://nvd.nist.gov/vuln/detail/CVE-2023-44487[CVE-2023-44487] +See https://en.wikipedia.org/wiki/ISO_8601.Durations[ISO_8601 Durations] |`requested-uri-discovery` |xref:{rootdir}/config/io_helidon_http_RequestedUriDiscoveryContext.adoc[RequestedUriDiscoveryContext] |{nbsp} |Requested URI discovery settings. - Settings for computing the requested URI +Settings for computing the requested URI |`send-error-details` |boolean |`false` |Whether to send error message over HTTP to client. - Defaults to `false`, as exception message may contain internal information that could be used as an - attack vector. Use with care and in cases where both server and clients are under your full control (such as for - testing). +Defaults to `false`, as exception message may contain internal information that could be used as an +attack vector. Use with care and in cases where both server and clients are under your full control (such as for +testing). - Whether to send error messages over the network +Whether to send error messages over the network |`validate-path` |boolean |`true` |If set to false, any path is accepted (even containing illegal characters). - Whether to validate path +Whether to validate path |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserveFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserveFeature.adoc index 2559f02848a..5244d9fc584 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserveFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserveFeature.adoc @@ -54,18 +54,18 @@ This type provides the following service implementations: |`cors` |xref:{rootdir}/config/io_helidon_cors_CrossOriginConfig.adoc[CrossOriginConfig] |`@io.helidon.cors.CrossOriginConfig@.create()` |Cors support inherited by each observe provider, unless explicitly configured. - Cors support to use +Cors support to use |`enabled` |boolean |`true` |Whether the observe support is enabled. - `false` to disable observe feature +`false` to disable observe feature |`endpoint` |string |`/observe` |Root endpoint to use for observe providers. By default, all observe endpoint are under this root endpoint. - Example: -
- If root endpoint is `/observe` (the default), and default health endpoint is `health` (relative), - health endpoint would be `/observe/health`. +Example: - Endpoint to use +If root endpoint is `/observe` (the default), and default health endpoint is `health` (relative), +health endpoint would be `/observe/health`. + +Endpoint to use |`observers` |io.helidon.webserver.observe.spi.Observer[] (service provider interface) Such as: @@ -78,18 +78,18 @@ Such as: - xref:{rootdir}/config/io_helidon_webserver_observe_health_HealthObserver.adoc[health (HealthObserver)] |{nbsp} |Observers to use with this observe features. - Each observer type is registered only once, unless it uses a custom name (default name is the same as the type). +Each observer type is registered only once, unless it uses a custom name (default name is the same as the type). - List of observers to use in this feature +List of observers to use in this feature |`sockets` |string[] |{nbsp} |Sockets the observability endpoint should be exposed on. If not defined, defaults to the default socket - (io.helidon.webserver.WebServer.DEFAULT_SOCKET_NAME. - Each observer may have its own configuration of sockets that are relevant to it, this only controls the endpoints! +(io.helidon.webserver.WebServer.DEFAULT_SOCKET_NAME. +Each observer may have its own configuration of sockets that are relevant to it, this only controls the endpoints! - List of sockets to register observe endpoint on +List of sockets to register observe endpoint on |`weight` |double |`80.0` |Change the weight of this feature. This may change the order of registration of this feature. - By default, observability weight is ObserveFeature.WEIGHT so it is registered after routing. +By default, observability weight is ObserveFeature.WEIGHT so it is registered after routing. - Weight to use +Weight to use |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserverConfigBase.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserverConfigBase.adoc index 2419abb5a7c..36a34c8816e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserverConfigBase.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_ObserverConfigBase.adoc @@ -44,7 +44,7 @@ Type: link:{javadoc-base-url}/io.helidon.webserver.observe/io/helidon/webserver/ |`enabled` |boolean |`true` |Whether this observer is enabled. - `false` to disable observer +`false` to disable observer |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_config_ConfigObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_config_ConfigObserver.adoc index ed70f806692..1fb7e003355 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_config_ConfigObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_config_ConfigObserver.adoc @@ -55,11 +55,11 @@ This type provides the following service implementations: |`endpoint` |string |`config` | |`permit-all` |boolean |{nbsp} |Permit all access, even when not authorized. - Whether to permit access for anybody +Whether to permit access for anybody |`secrets` |string[] |`.*password, .*passphrase, .*secret` |Secret patterns (regular expressions) to exclude from output. - Any pattern that matches a key will cause the output to be obfuscated and not contain the value. +Any pattern that matches a key will cause the output to be obfuscated and not contain the value. - Patterns always added: +Patterns always added: - `.*password` - `.*passphrase` diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_health_HealthObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_health_HealthObserver.adoc index 6af7c2322a1..a90b9b1a25e 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_health_HealthObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_health_HealthObserver.adoc @@ -49,19 +49,19 @@ This type provides the following service implementations: |key |type |default value |description |`details` |boolean |`false` |Whether details should be printed. - By default, health only returns a io.helidon.http.Status.NO_CONTENT_204 for success, - io.helidon.http.Status.SERVICE_UNAVAILABLE_503 for health down, - and io.helidon.http.Status.INTERNAL_SERVER_ERROR_500 in case of error with no entity. - When details are enabled, health returns io.helidon.http.Status.OK_200 for success, same codes - otherwise - and a JSON entity with detailed information about each health check executed. - - Set to `true` to enable details +By default, health only returns a io.helidon.http.Status.NO_CONTENT_204 for success, +io.helidon.http.Status.SERVICE_UNAVAILABLE_503 for health down, +and io.helidon.http.Status.INTERNAL_SERVER_ERROR_500 in case of error with no entity. +When details are enabled, health returns io.helidon.http.Status.OK_200 for success, same codes +otherwise +and a JSON entity with detailed information about each health check executed. + +Set to `true` to enable details |`endpoint` |string |`health` | |`use-system-services` |boolean |`true` |Whether to use services discovered by java.util.ServiceLoader. - By default, all io.helidon.health.spi.HealthCheckProvider based health checks are added. +By default, all io.helidon.health.spi.HealthCheckProvider based health checks are added. - Set to `false` to disable discovery +Set to `false` to disable discovery |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_info_InfoObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_info_InfoObserver.adoc index e56c148a15a..6872c65ac7d 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_info_InfoObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_info_InfoObserver.adoc @@ -55,7 +55,7 @@ This type provides the following service implementations: |`endpoint` |string |`info` | |`values` |Map<string, string> |{nbsp} |Values to be exposed using this observability endpoint. - Value map +Value map |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogObserver.adoc index ff1d897bf07..d025673dd62 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogObserver.adoc @@ -55,10 +55,10 @@ This type provides the following service implementations: |`endpoint` |string |`log` | |`permit-all` |boolean |{nbsp} |Permit all access, even when not authorized. - Whether to permit access for anybody +Whether to permit access for anybody |`stream` |xref:{rootdir}/config/io_helidon_webserver_observe_log_LogStreamConfig.adoc[LogStreamConfig] |`@io.helidon.webserver.observe.log.LogStreamConfig@.create()` |Configuration of log stream. - Log stream configuration +Log stream configuration |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogStreamConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogStreamConfig.adoc index 8d1c4ecd18a..bdfbe38769d 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogStreamConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_log_LogStreamConfig.adoc @@ -45,20 +45,20 @@ Type: link:{javadoc-base-url}/io.helidon.webserver.observe.log/io/helidon/webser |`content-type` |HttpMediaType |`@io.helidon.http.HttpMediaTypes@.PLAINTEXT_UTF_8` | |`enabled` |boolean |`true` |Whether stream is enabled. - Whether to allow streaming of log statements +Whether to allow streaming of log statements |`idle-message-timeout` |Duration |`PT5S` |How long to wait before we send the idle message, to make sure we keep the stream alive. - If no messages appear within this duration, and idle message will be sent - See idleString() +If no messages appear within this duration, and idle message will be sent +See idleString() |`idle-string` |string |`% ` |String sent when there are no log messages within the idleMessageTimeout(). - String to write over the network when no log messages are received +String to write over the network when no log messages are received |`queue-size` |int |`100` |Length of the in-memory queue that buffers log messages from loggers before sending them over the network. - If the messages are produced faster than we can send them to client, excess messages are DISCARDED, and will not - be sent. +If the messages are produced faster than we can send them to client, excess messages are DISCARDED, and will not +be sent. - Size of the in-memory queue for log messages +Size of the in-memory queue for log messages |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_metrics_MetricsObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_metrics_MetricsObserver.adoc index c46b8bd9267..3a288e15edb 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_metrics_MetricsObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_metrics_MetricsObserver.adoc @@ -50,33 +50,33 @@ This type provides the following service implementations: |`app-name` |string |{nbsp} |Value for the application tag to be added to each meter ID. - Application tag value +Application tag value |`app-tag-name` |string |{nbsp} |Name for the application tag to be added to each meter ID. - Application tag name +Application tag name |`enabled` |boolean |`true` |Whether metrics functionality is enabled. - If metrics are configured to be enabled +If metrics are configured to be enabled |`endpoint` |string |`metrics` | |`key-performance-indicators` |xref:{rootdir}/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsConfig.adoc[KeyPerformanceIndicatorMetricsConfig] |{nbsp} |Key performance indicator metrics settings. - Key performance indicator metrics settings +Key performance indicator metrics settings |`permit-all` |boolean |`true` |Whether to allow anybody to access the endpoint. - Whether to permit access to metrics endpoint to anybody, defaults to `true` - See roles() -|`rest-request-enabled` |boolean |{nbsp} |Whether automatic REST request metrics should be measured. +Whether to permit access to metrics endpoint to anybody, defaults to `true` +See roles() +|`rest-request-enabled` |boolean |`false` |Whether automatic REST request metrics should be measured. - True/false +True/false |`roles` |string[] |`observe` |Hints for role names the user is expected to be in. - List of hints +List of hints |`scoping` |xref:{rootdir}/config/io_helidon_metrics_api_ScopingConfig.adoc[ScopingConfig] |{nbsp} |Settings related to scoping management. - Scoping settings +Scoping settings |`tags` |xref:{rootdir}/config/io_helidon_metrics_api_Tag.adoc[Tag[]] |{nbsp} |Global tags. - Name/value pairs for global tags +Name/value pairs for global tags |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_tracing_TracingObserver.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_tracing_TracingObserver.adoc index feea2ca6abc..a20fec9e836 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_observe_tracing_TracingObserver.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_observe_tracing_TracingObserver.adoc @@ -54,7 +54,7 @@ This type provides the following service implementations: |`env-config` |TracingConfig |`TracingConfig.ENABLED` |Use the provided configuration as a default for any request. - Default web server tracing configuration +Default web server tracing configuration |`paths` |PathTracingConfig[] |`new @java.util.ArrayList@(@java.util.List@.of(PathTracingConfig.builder() .path("/metrics/*") .tracingConfig(TracingConfig.DISABLED) @@ -80,12 +80,12 @@ This type provides the following service implementations: .tracingConfig(TracingConfig.DISABLED) .build()))` |Path specific configuration of tracing. - Configuration of tracing for specific paths +Configuration of tracing for specific paths |`weight` |double |`900.0` |Weight of the feature registered with WebServer. - Changing weight may cause tracing to be executed at a different time (such as after security, or even after - all routes). Please understand feature weights before changing this order. +Changing weight may cause tracing to be executed at a different time (such as after security, or even after +all routes). Please understand feature weights before changing this order. - Weight of tracing feature +Weight of tracing feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_security_PathsConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_security_PathsConfig.adoc index c8edd4ef024..b653473b436 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_security_PathsConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_security_PathsConfig.adoc @@ -44,45 +44,45 @@ Type: link:{javadoc-base-url}/io.helidon.webserver.security/io/helidon/webserver |`audit` |boolean |{nbsp} |Whether to audit this request - defaults to false, if enabled, request is audited with event type "request". - Whether to audit +Whether to audit |`audit-event-type` |string |{nbsp} |Override for event-type, defaults to SecurityHandler.DEFAULT_AUDIT_EVENT_TYPE. - Audit event type to use +Audit event type to use |`audit-message-format` |string |{nbsp} |Override for audit message format, defaults to SecurityHandler.DEFAULT_AUDIT_MESSAGE_FORMAT. - Audit message format to use +Audit message format to use |`authenticate` |boolean |{nbsp} |If called, request will go through authentication process - defaults to false (even if authorize is true). - Whether to authenticate or not +Whether to authenticate or not |`authentication-optional` |boolean |{nbsp} |If called, authentication failure will not abort request and will continue as anonymous (defaults to false). - Whether authn is optional +Whether authn is optional |`authenticator` |string |{nbsp} |Use a named authenticator (as supported by security - if not defined, default authenticator is used). - Will enable authentication. +Will enable authentication. - Name of authenticator as configured in io.helidon.security.Security +Name of authenticator as configured in io.helidon.security.Security |`authorize` |boolean |{nbsp} |Enable authorization for this route. - Whether to authorize +Whether to authorize |`authorizer` |string |{nbsp} |Use a named authorizer (as supported by security - if not defined, default authorizer is used, if none defined, all is - permitted). - Will enable authorization. +permitted). +Will enable authorization. - Name of authorizer as configured in io.helidon.security.Security +Name of authorizer as configured in io.helidon.security.Security |`methods` |Method[] |{nbsp} | |`path` |string |{nbsp} | |`roles-allowed` |string[] |{nbsp} |An array of allowed roles for this path - must have a security provider supporting roles (either authentication - or authorization provider). - This method enables authentication and authorization (you can disable them again by calling - SecurityHandler.skipAuthorization() - and authenticationOptional() if needed). +or authorization provider). +This method enables authentication and authorization (you can disable them again by calling +SecurityHandler.skipAuthorization() +and authenticationOptional() if needed). - If subject is any of these roles, allow access +If subject is any of these roles, allow access |`sockets` |string[] |`@default` | |`sockets` |string[] |{nbsp} |List of sockets this configuration should be applied to. - If empty, the configuration is applied to all configured sockets. +If empty, the configuration is applied to all configured sockets. - List of sockets +List of sockets |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityFeature.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityFeature.adoc index 4b294500092..ae75399478c 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityFeature.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityFeature.adoc @@ -54,22 +54,22 @@ This type provides the following service implementations: |`defaults` |xref:{rootdir}/config/io_helidon_webserver_security_SecurityHandler.adoc[SecurityHandler] |`SecurityHandler.create()` |The default security handler. - Security handler defaults +Security handler defaults |`paths` |xref:{rootdir}/config/io_helidon_webserver_security_PathsConfig.adoc[PathsConfig[]] |{nbsp} |Configuration for webserver paths. - Path configuration +Path configuration |`security` |xref:{rootdir}/config/io_helidon_security_Security.adoc[Security] |{nbsp} |Security associated with this feature. - If not specified here, the feature uses security registered with - io.helidon.common.context.Contexts.globalContext(), if not found, it creates a new - instance from root of configuration (using `security` key). +If not specified here, the feature uses security registered with +io.helidon.common.context.Contexts.globalContext(), if not found, it creates a new +instance from root of configuration (using `security` key). - This configuration allows usage of a different security instance for a specific security feature setup. +This configuration allows usage of a different security instance for a specific security feature setup. - Security instance to be used to handle security in this feature configuration +Security instance to be used to handle security in this feature configuration |`weight` |double |`800.0` |Weight of the security feature. Value is: - io.helidon.webserver.security.SecurityFeature.WEIGHT. +io.helidon.webserver.security.SecurityFeature.WEIGHT. - Weight of the feature +Weight of the feature |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityHandler.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityHandler.adoc index 413683d1227..24e592fb2bb 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityHandler.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_security_SecurityHandler.adoc @@ -44,42 +44,42 @@ Type: link:{javadoc-base-url}/io.helidon.webserver.security/io/helidon/webserver |`audit` |boolean |{nbsp} |Whether to audit this request - defaults to false, if enabled, request is audited with event type "request". - Whether to audit +Whether to audit |`audit-event-type` |string |{nbsp} |Override for event-type, defaults to SecurityHandler.DEFAULT_AUDIT_EVENT_TYPE. - Audit event type to use +Audit event type to use |`audit-message-format` |string |{nbsp} |Override for audit message format, defaults to SecurityHandler.DEFAULT_AUDIT_MESSAGE_FORMAT. - Audit message format to use +Audit message format to use |`authenticate` |boolean |{nbsp} |If called, request will go through authentication process - defaults to false (even if authorize is true). - Whether to authenticate or not +Whether to authenticate or not |`authentication-optional` |boolean |{nbsp} |If called, authentication failure will not abort request and will continue as anonymous (defaults to false). - Whether authn is optional +Whether authn is optional |`authenticator` |string |{nbsp} |Use a named authenticator (as supported by security - if not defined, default authenticator is used). - Will enable authentication. +Will enable authentication. - Name of authenticator as configured in io.helidon.security.Security +Name of authenticator as configured in io.helidon.security.Security |`authorize` |boolean |{nbsp} |Enable authorization for this route. - Whether to authorize +Whether to authorize |`authorizer` |string |{nbsp} |Use a named authorizer (as supported by security - if not defined, default authorizer is used, if none defined, all is - permitted). - Will enable authorization. +permitted). +Will enable authorization. - Name of authorizer as configured in io.helidon.security.Security +Name of authorizer as configured in io.helidon.security.Security |`roles-allowed` |string[] |{nbsp} |An array of allowed roles for this path - must have a security provider supporting roles (either authentication - or authorization provider). - This method enables authentication and authorization (you can disable them again by calling - SecurityHandler.skipAuthorization() - and authenticationOptional() if needed). +or authorization provider). +This method enables authentication and authorization (you can disable them again by calling +SecurityHandler.skipAuthorization() +and authenticationOptional() if needed). - If subject is any of these roles, allow access +If subject is any of these roles, allow access |`sockets` |string[] |{nbsp} |List of sockets this configuration should be applied to. - If empty, the configuration is applied to all configured sockets. +If empty, the configuration is applied to all configured sockets. - List of sockets +List of sockets |=== diff --git a/docs/src/main/asciidoc/config/io_helidon_webserver_websocket_WsConfig.adoc b/docs/src/main/asciidoc/config/io_helidon_webserver_websocket_WsConfig.adoc index 304bd316def..f5f49945de5 100644 --- a/docs/src/main/asciidoc/config/io_helidon_webserver_websocket_WsConfig.adoc +++ b/docs/src/main/asciidoc/config/io_helidon_webserver_websocket_WsConfig.adoc @@ -53,15 +53,15 @@ This type provides the following service implementations: |key |type |default value |description |`max-frame-length` |int |`1048576` |Max WebSocket frame size supported by the server on a read operation. - Default is 1 MB. +Default is 1 MB. - Max frame size to read +Max frame size to read |`name` |string |`websocket` |Name of this configuration. - Configuration name +Configuration name |`origins` |string[] |{nbsp} |WebSocket origins. - Origins +Origins |=== diff --git a/docs/src/main/asciidoc/config/io_opentracing_Tracer.adoc b/docs/src/main/asciidoc/config/io_opentracing_Tracer.adoc index f8e347a05fa..42bed06586c 100644 --- a/docs/src/main/asciidoc/config/io_opentracing_Tracer.adoc +++ b/docs/src/main/asciidoc/config/io_opentracing_Tracer.adoc @@ -47,7 +47,13 @@ This is a standalone configuration type, prefix from configuration root: `tracin |key |type |default value |description |`api-version` |Version (V1, V2) |`V2` |Version of Zipkin API to use. - Defaults to Version.V2. +Defaults to Version.V2. + +Allowed values: + +- `V1`: Version 1. +- `V2`: Version 2. + |=== diff --git a/docs/src/main/asciidoc/mp/jwt.adoc b/docs/src/main/asciidoc/mp/jwt.adoc index 9bd621144c7..6b28fcae36c 100644 --- a/docs/src/main/asciidoc/mp/jwt.adoc +++ b/docs/src/main/asciidoc/mp/jwt.adoc @@ -77,7 +77,7 @@ The following interfaces and annotations are used to work with JWT in Helidon MP == Configuration -include::{rootdir}/config/io_helidon_microprofile_jwt.adoc[leveloffset=+1,tag=config] +include::{rootdir}/config/io_helidon_microprofile_jwt_auth_JwtAuthProvider.adoc[leveloffset=+1,tag=config] A configuration example in `microprofile-config.properties`: [source, properties]