Clarify tls settings for OIDC providers (#659)

* Clarify tls settings for oidc prodivers

* Configure yamllint

* Update modules/concepts/pages/authentication.adoc

Co-authored-by: Sebastian Bernauer <[email protected]>

---------

Co-authored-by: Sebastian Bernauer <[email protected]>

Author: NickLarsenNZ

.yamllint.yaml

@@ -7,3 +7,8 @@ rules:
     check-keys: false
   comments:
     min-spaces-from-content: 1  # Needed due to https://github.com/adrienverge/yamllint/issues/443
+  document-start:
+    ignore:
+    - modules/**/examples/**  # We don't want the `---` in doc includes.
+  indentation:
+    indent-sequences: consistent

modules/concepts/examples/authenticationclass-keycloak.yaml

@@ -14,3 +14,8 @@ spec:
       - profile
       principalClaim: preferred_username  # <5>
       providerHint: Keycloak              # <6>
+      tls:                                # <7>
+        verification:
+          server:
+            caCert:
+              webPki: {}                  # <8>

modules/concepts/pages/authentication.adoc

@@ -54,6 +54,8 @@ include::example$authenticationclass-keycloak.yaml[]
 <4> Scopes to request from your identity provider. It is recommended to request the `openid`, `email`, and `profile` scopes.
 <5> If a product extracts some sort of "effective user" that is represented by a string internally, this config determines which claim is used to extract that string.
 <6> This is a hint about which identity provider is used by the AuthenticationClass.
+<7> Optionally enable TLS and configure verification. When present, connections to the idP will use `https://` instead of `http://`. See xref:tls-server-verification.adoc[].
+<8> Trust certificates signed by commonly trusted Certificate Authorities.
 
 NOTE: Get a full overview of all the properties in the {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/#spec-provider-oidc[AuthenticationClass OIDC provider CRD reference].