Security Providers Documentation (#4557)

Security Providers Documentation

Signed-off-by: David Kral <david.k.kral@oracle.com>

docs/config/config_reference.adoc

@@ -32,11 +32,21 @@ The following section lists all configurable types in Helidon.
 - xref:{rootdir}/config/io_helidon_security_providers_httpauth_ConfigUserStore_ConfigUser.adoc[ConfigUser (security.providers.httpauth.ConfigUserStore)]
 - xref:{rootdir}/config/io_helidon_webserver_cors_CrossOriginConfig.adoc[CrossOriginConfig (webserver.cors)]
 - xref:{rootdir}/config/io_helidon_faulttolerance_Retry_DelayingRetryPolicy.adoc[DelayingRetryPolicy (faulttolerance.Retry)]
+- xref:{rootdir}/config/io_helidon_security_providers_common_EvictableCache.adoc[EvictableCache (security.providers.common)]
+- xref:{rootdir}/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc[GoogleTokenProvider (security.providers.google.login)]
+- 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_health_HealthSupport.adoc[HealthSupport (health)]
 - xref:{rootdir}/config/io_helidon_servicecommon_rest_HelidonRestServiceSupport.adoc[HelidonRestServiceSupport (servicecommon.rest)]
 - xref:{rootdir}/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc[HttpBasicAuthProvider (security.providers.httpauth)]
+- xref:{rootdir}/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc[HttpDigestAuthProvider (security.providers.httpauth)]
+- xref:{rootdir}/config/io_helidon_security_providers_httpsign_HttpSignProvider.adoc[HttpSignProvider (security.providers.httpsign)]
+- xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsMtRoleMapperRxProvider.adoc[IdcsMtRoleMapperRxProvider (security.providers.idcs.mapper)]
+- xref:{rootdir}/config/io_helidon_security_providers_idcs_mapper_IdcsRoleMapperRxProvider.adoc[IdcsRoleMapperRxProvider (security.providers.idcs.mapper)]
+- xref:{rootdir}/config/io_helidon_security_providers_httpsign_InboundClientDefinition.adoc[InboundClientDefinition (security.providers.httpsign)]
 - xref:{rootdir}/config/io_helidon_tracing_jaeger_JaegerTracerBuilder.adoc[JaegerTracer (tracing.jaeger)]
 - xref:{rootdir}/config/io_helidon_faulttolerance_Retry_JitterRetryPolicy.adoc[JitterRetryPolicy (faulttolerance.Retry)]
+- xref:{rootdir}/config/io_helidon_security_providers_jwt_JwtProvider.adoc[JwtProvider (security.providers.jwt)]
 - xref:{rootdir}/config/io_helidon_common_pki_KeyConfig.adoc[KeyConfig (common.pki)]
 - xref:{rootdir}/config/io_helidon_metrics_api_KeyPerformanceIndicatorMetricsSettings.adoc[KeyPerformanceIndicatorMetricsSettings (metrics.api)]
 - xref:{rootdir}/config/io_helidon_common_pki_KeyConfig_KeystoreBuilder.adoc[KeystoreBuilder (common.pki.KeyConfig)]

docs/config/io_helidon_security_providers_common_EvictableCache.adoc

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.common.EvictableCache
+:keywords: helidon, config, io.helidon.security.providers.common.EvictableCache
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.common.EvictableCache
+include::{rootdir}/includes/attributes.adoc[]
+
+= EvictableCache (security.providers.common) Configuration
+
+// tag::config[]
+
+
+Type: link:{javadoc-base-url}/io.helidon.security.providers.common/io/helidon/security/providers/common/EvictableCache.html[io.helidon.security.providers.common.EvictableCache]
+
+
+
+
+== Configuration options
+
+
+
+Optional configuration options:
+[cols="3,3,2,5a"]
+
+|===
+|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.
+|`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.
+|`max-size` |long |`100000` |Configure maximal cache size.
+|`parallelism-threshold` |long |`10000` |Configure parallelism threshold.
+
+|===
+
+// end::config[]

docs/config/io_helidon_security_providers_google_login_GoogleTokenProvider.adoc

@@ -0,0 +1,70 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.google.login.GoogleTokenProvider
+:keywords: helidon, config, io.helidon.security.providers.google.login.GoogleTokenProvider
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.google.login.GoogleTokenProvider
+include::{rootdir}/includes/attributes.adoc[]
+
+= GoogleTokenProvider (security.providers.google.login) Configuration
+
+// tag::config[]
+
+Google Authentication provider
+
+
+Type: link:{javadoc-base-url}/io.helidon.security.providers.google.login/io/helidon/security/providers/google/login/GoogleTokenProvider.html[io.helidon.security.providers.google.login.GoogleTokenProvider]
+
+
+[source,text]
+.Config key
+----
+google-login
+----
+
+
+This type provides the following service implementations:
+
+- `io.helidon.security.spi.SecurityProvider`
+- `io.helidon.security.spi.AuthenticationProvider`
+
+
+== Configuration options
+
+
+
+Optional configuration options:
+[cols="3,3,2,5a"]
+
+|===
+|key |type |default value |description
+
+|`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.
+|`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.
+|`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".
+|`token` |xref:{rootdir}/config/io_helidon_security_util_TokenHandler.adoc[TokenHandler] |``Authorization` header with `bearer` prefix` |Token provider to extract Google access token from request, defaults to "Authorization" header with a "bearer " prefix.
+
+|===
+
+// end::config[]

docs/config/io_helidon_security_providers_header_HeaderAtnProvider.adoc

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.header.HeaderAtnProvider
+:keywords: helidon, config, io.helidon.security.providers.header.HeaderAtnProvider
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.header.HeaderAtnProvider
+include::{rootdir}/includes/attributes.adoc[]
+
+= HeaderAtnProvider (security.providers.header) Configuration
+
+// tag::config[]
+
+Security provider that extracts a username (or service name) from a header.
+
+
+Type: link:{javadoc-base-url}/io.helidon.security.providers.header/io/helidon/security/providers/header/HeaderAtnProvider.html[io.helidon.security.providers.header.HeaderAtnProvider]
+
+
+[source,text]
+.Config key
+----
+header-atn
+----
+
+
+This type provides the following service implementations:
+
+- `io.helidon.security.spi.SecurityProvider`
+- `io.helidon.security.spi.AuthenticationProvider`
+
+
+== Configuration options
+
+
+
+Optional configuration options:
+[cols="3,3,2,5a"]
+
+|===
+|key |type |default value |description
+
+|`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.
+|`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.
+|`principal-type` |SubjectType (USER, SERVICE) |`USER` |Principal type this provider extracts (and also propagates).
+|`propagate` |boolean |`false` |Whether to propagate identity.
+
+|===
+
+// end::config[]

docs/config/io_helidon_security_providers_httpauth_HttpBasicAuthProvider.adoc

@@ -58,6 +58,7 @@ Optional configuration options:
 |`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.
+|`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.

docs/config/io_helidon_security_providers_httpauth_HttpDigestAuthProvider.adoc

@@ -0,0 +1,75 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 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.httpauth.HttpDigestAuthProvider
+:keywords: helidon, config, io.helidon.security.providers.httpauth.HttpDigestAuthProvider
+:basic-table-intro: The table below lists the configuration keys that configure io.helidon.security.providers.httpauth.HttpDigestAuthProvider
+include::{rootdir}/includes/attributes.adoc[]
+
+= HttpDigestAuthProvider (security.providers.httpauth) Configuration
+
+// tag::config[]
+
+Http digest authentication security provider
+
+
+Type: link:{javadoc-base-url}/io.helidon.security.providers.httpauth/io/helidon/security/providers/httpauth/HttpDigestAuthProvider.html[io.helidon.security.providers.httpauth.HttpDigestAuthProvider]
+
+
+[source,text]
+.Config key
+----
+http-digest-auth
+----
+
+
+This type provides the following service implementations:
+
+- `io.helidon.security.spi.SecurityProvider`
+- `io.helidon.security.spi.AuthenticationProvider`
+
+
+== Configuration options
+
+
+
+Optional configuration options:
+[cols="3,3,2,5a"]
+
+|===
+|key |type |default value |description
+
+|`algorithm` |Algorithm (MD5) |`MD5` |Digest algorithm to use.
+|`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.
+|`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.
+|`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.
+|`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.
+
+|===
+
+// end::config[]