Add docs for AuthenticationClass and TLS

docs/modules/ROOT/examples/authenticationclass-ldap-full.yaml

@@ -0,0 +1,30 @@
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: ldap-full
+spec:
+  provider:
+    ldap:
+      hostname: my.ldap.server # <1>
+      port: 389 # <2>
+      searchBase: ou=users,dc=example,dc=org # <3>
+      searchFilter: (memberOf=cn=myTeam,ou=teams,dc=example,dc=org) # <4>
+      ldapFieldNames: # <5>
+        uid: uid
+        group: memberof
+        givenName: givenName
+        surname: sn
+        email: mail
+      bindCredentials:
+        secretClass: ldap-full-bind # <6>
+        scope: # <7>
+          pod: true
+          node: false
+          services:
+            - ldap-full
+      tls: # <8>
+        verification:
+          server:
+            caCert:
+              secretClass: ldap-full-ca-cert

docs/modules/ROOT/examples/authenticationclass-ldap-openldap-simple.yaml

@@ -0,0 +1,33 @@
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: openldap-simple
+spec:
+  provider:
+    ldap:
+      hostname: my.openldap.server
+      port: 1389
+      searchBase: ou=users,dc=example,dc=org
+      bindCredentials:
+        secretClass: openldap-simple-bind # <1>
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: openldap-simple-bind # <2>
+spec:
+  backend:
+    k8sSearch:
+      searchNamespace:
+        pod: {} # <3>
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: openldap-simple-bind # <4>
+  labels:
+    secrets.stackable.tech/class: openldap-simple-bind # <5>
+stringData:
+  user: cn=admin,dc=example,dc=org
+  password: admin

docs/modules/ROOT/examples/authenticationclass-ldap-simple.yaml

@@ -0,0 +1,11 @@
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: ldap-simple
+spec:
+  provider:
+    ldap:
+      hostname: my.ldap.server # <1>
+      port: 389 # <2>
+      searchBase: ou=users,dc=example,dc=org # <3>

docs/modules/ROOT/examples/tls-mutual-verification.yaml

@@ -0,0 +1,5 @@
+---
+tls:
+  verification:
+    mutual:
+      certSecretClass: openldap-tls

docs/modules/ROOT/examples/tls-no-verification.yaml

@@ -0,0 +1,4 @@
+---
+tls:
+  verification:
+    none: {}

docs/modules/ROOT/examples/tls-server-verification-custom-ca.yaml

@@ -0,0 +1,6 @@
+---
+tls:
+  verification:
+    server:
+      caCert:
+        secretClass: openldap-tls-ca

docs/modules/ROOT/examples/tls-server-verification-webpki.yaml

@@ -0,0 +1,6 @@
+---
+tls:
+  verification:
+    server:
+      caCert:
+        webPki: {}

docs/modules/ROOT/examples/tls-simple.yaml

@@ -0,0 +1,5 @@
+---
+# [...]
+tls:
+  verification:
+    none: {}

docs/modules/ROOT/images/authenticationclass.plantuml

@@ -0,0 +1,27 @@
+allowmixing
+
+database LDAP
+
+map "Secret openldap-simple-bind" as secret_openldap_simple_bind {
+    user => cn=admin,dc=example,dc=org
+    password => admin
+}
+
+map "Secret openldap-simple-ca" as secret_openldap_simple_ca {
+    caCert => <ca certificate content>
+}
+
+map "SecretClass openldap-simple-bind" as secret_class_openldap_simple_bind {
+    k8sSearch *-> secret_openldap_simple_bind
+}
+
+map "SecretClass openldap-simple-ca" as secret_class_openldap_simple_ca {
+    k8sSearch *-> secret_openldap_simple_ca
+}
+
+map "AuthenticationClass openldap-simple" as authentication_class_openldap_simple {
+    ldapHost *--> LDAP
+    tlsServerVerification *--> secret_class_openldap_simple_ca
+    bindCredentials *--> secret_class_openldap_simple_bind
+    ldapSearchBase => ou=users,dc=example,dc=org
+}

docs/modules/ROOT/nav.adoc

@@ -3,4 +3,5 @@
 * xref:usage.adoc[]
 * Concepts
 ** xref:authenticationclass.adoc[]
+** xref:tls.adoc[]
 ** xref:reloader.adoc[]

docs/modules/ROOT/pages/authenticationclass.adoc

@@ -1,3 +1,55 @@
 = `AuthenticationClass`
 
-TODO
+`AuthenticationClass` is a CRD describing a generic authentication method like LDAP or Kerberos.
+Multiple operators use this CRD as a way to express the authentication of the product.
+
+At the moment the following Authentication providers are supported:
+
+* <<LDAP>>
+
+== LDAP
+A very simple `AuthenticationClass` with LDAP Authentication looks like this:
+
+[source,yaml]
+----
+include::example$authenticationclass-ldap-simple.yaml[]
+----
+<1> The hostname of the LDAP server without any protocol or port
+<2> The port of the LDAP server. If TLS is used it defaults to `636` otherwise to `389`
+<3> An optional searchBase where the users should be searched
+
+=== OpenLDAP
+Here is an example that is tuned for an OpenLDAP LDAP server and is configured to read bind user credentials from a secret:
+
+[source,yaml]
+----
+include::example$authenticationclass-ldap-openldap-simple.yaml[]
+----
+<1> The name of the xref:secret-operator::secretclass.adoc[] providing the bind credentials (username and password). Must match the name of the xref:secret-operator::secretclass.adoc[] in this example in ②
+<2> The name of the xref:secret-operator::secretclass.adoc[] we are creating that is referred to by ➀. See xref:secret-operator::secretclass.adoc[]
+<3> This determines the namespace in which the referenced `Secret` will be looked for. In this case it searches for a `Secret` in the same namespace as the product runs in. See xref:secret-operator::secretclass.adoc#backend-k8ssearch[the documentation of SecretClass]
+<4> The `Secret` containing the actual bind credentials. Please keep in mind that the `Secret` needs to be in the same namespace as the product
+<5> The name of the xref:secret-operator::secretclass.adoc[] that wants to refer to this `Secret`. Must match the name of the xref:secret-operator::secretclass.adoc[] in this example in ②
+
+The following diagram describes the relationship between the created CRDs
+
+[plantuml]
+----
+include::image$authenticationclass.plantuml[]
+----
+
+=== All possible attributes
+The following example shows all possible attributes:
+
+[source,yaml]
+----
+include::example$authenticationclass-ldap-full.yaml[]
+----
+<1> The hostname of the LDAP server without any protocol or port
+<2> The port of the LDAP server. If TLS is used defaults to `636` otherwise to `389`
+<3> The searchBase where the users should be searched
+<4> Additional filter that filters the allowed users
+<5> The name of the corresponding field names in the LDAP objects
+<6> The name of the xref:secret-operator::secretclass.adoc[] providing the bind credentials (username and password)
+<7> The xref:secret-operator::scope.adoc[] of the xref:secret-operator::secretclass.adoc[]
+<8> xref:tls.adoc[] connection to the LDAP server

docs/modules/ROOT/pages/installation.adoc

@@ -26,7 +26,7 @@ Helm will deploy the operator in Kubernetes and apply the CRDs.
 
 == Building the operator from source
 
-After cloning the commons-operator repor you can use the following command to apply the CRDs:
+After cloning the commons-operator repo you can use the following command to apply the CRDs:
 
 [source,console]
 ----

docs/modules/ROOT/pages/tls.adoc

@@ -0,0 +1,57 @@
+= TLS
+
+A TLS section is part of Stackable CRDs and describes how to connect to a TLS enabled system like LDAP or S3.
+
+If the `tls` attribute is set to `null` (or is not specifed) no TLS will be used for the connection.
+
+A simple TLS section looks like this:
+
+[source,yaml]
+----
+include::example$tls-simple.yaml[]
+----
+
+== Verification
+The parties participating at an TLS connection can be verified using certificates.
+At the moment the following verification methods are supported
+
+* <<No verification>>
+* <<Server verification>>
+* <<Mutual verification>>
+
+=== No verification
+This example will use TLS but not perform any checks on the certificate presented by the server or present a client certificate if asked for one by the server.
+
+[source,yaml]
+----
+include::example$tls-no-verification.yaml[]
+----
+
+=== Server verification
+This example will use TLS and verify the server using the ca certificates that are trusted by common web browsers.
+This can be useful when you e.g. use public AWS S3 or other public available services.
+
+[source,yaml]
+----
+include::example$tls-server-verification-webpki.yaml[]
+----
+
+This example will use TLS and verify the server using the provided ca certificate.
+For this to work you need to create a xref:secret-operator::secretclass.adoc[] that - at least - contains the ca certificate.
+Note that a SecretClass does not need to have a key but can also work with just a ca cert.
+So if you got provided with a ca cert but don't have access to the key you can still use this method.
+
+[source,yaml]
+----
+include::example$tls-server-verification-custom-ca.yaml[]
+----
+
+=== Mutual verification
+This example will use TLS and verify both - the server and the client using certificates.
+For this to work you need to create a xref:secret-operator::secretclass.adoc[] containing the ca certificate and a key to create new client-certificates.
+The xref:secret-operator::index.adoc[] will automatically provide the product with a `ca.crt`, `tls.crt` and `tls.key` so that the product can authenticate the server and it can authenticate itself at the server.
+
+[source,yaml]
+----
+include::example$tls-mutual-verification.yaml[]
+----

docs/modules/ROOT/pages/usage.adoc

@@ -5,12 +5,22 @@ The commons-operator is used for multiple purposes:
 
 [%autowidth.stretch]
 |===
-|Component|Purpose
+|Concept|Purpose
 
 |xref:authenticationclass.adoc[]
-|An CRD describing an generic authentication method like LDAP or Kerberos.
-Multiple operators use this CRD as a way to express the autentication of the product.
+|CRD describing a generic authentication method like LDAP or Kerberos.
+Multiple operators use this CRD as a way to express the authentication of the product
+
+|xref:tls.adoc[]
+|Section of a CRD describing how to connect to a TLS enabled system
 
 |xref:reloader.adoc[]
 |An operator that watches `StatefulSets` and restarts them if mounted `ConfigMap` or `Secret` changes
 |===
+
+The following diagram describes the relationship between the CRDs
+
+[plantuml]
+----
+include::image$authenticationclass.plantuml[]
+----