Skip to content

Commit 2f64937

Browse files
sbernauermaltesander
sbernauer
and
maltesander
authored
Add concepts page on AuthenticationClass and TLS server verification (#323)
* Add concepts page on AuthenticationClass and TLS server verification * Update modules/concepts/pages/authenticationclass.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/authenticationclass.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/authenticationclass.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/tls_server_verification.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/tls_server_verification.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/tls_server_verification.adoc Co-authored-by: Malte Sander <[email protected]> * Update modules/concepts/pages/tls_server_verification.adoc Co-authored-by: Malte Sander <[email protected]> * simple-trino-users -> simple-users * Add section on TLS Co-authored-by: Malte Sander <[email protected]>
1 parent 1a3ac94 commit 2f64937

15 files changed

+303
-4
lines changed

‎modules/concepts/examples/authenticationclass-ldap-full.yaml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
apiVersion: authentication.stackable.tech/v1alpha1
2+
kind: AuthenticationClass
3+
metadata:
4+
name: ldap-full
5+
spec:
6+
provider:
7+
ldap:
8+
hostname: my.ldap.server # <1>
9+
port: 389 # <2>
10+
searchBase: ou=users,dc=example,dc=org # <3>
11+
searchFilter: (memberOf=cn=myTeam,ou=teams,dc=example,dc=org) # <4>
12+
ldapFieldNames: # <5>
13+
uid: uid
14+
group: memberof
15+
givenName: givenName
16+
surname: sn
17+
email: mail
18+
bindCredentials:
19+
secretClass: ldap-full-bind # <6>
20+
scope: # <7>
21+
pod: true
22+
node: false
23+
services:
24+
- ldap-full
25+
tls: # <8>
26+
verification:
27+
server:
28+
caCert:
29+
secretClass: ldap-full-ca-cert

‎modules/concepts/examples/authenticationclass-ldap-openldap-simple.yaml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
apiVersion: authentication.stackable.tech/v1alpha1
2+
kind: AuthenticationClass
3+
metadata:
4+
name: openldap-simple
5+
spec:
6+
provider:
7+
ldap:
8+
hostname: my.openldap.server
9+
port: 1389
10+
searchBase: ou=users,dc=example,dc=org
11+
bindCredentials:
12+
secretClass: openldap-simple-bind # <1>
13+
---
14+
apiVersion: secrets.stackable.tech/v1alpha1
15+
kind: SecretClass
16+
metadata:
17+
name: openldap-simple-bind # <2>
18+
spec:
19+
backend:
20+
k8sSearch:
21+
searchNamespace:
22+
pod: {} # <3>
23+
---
24+
apiVersion: v1
25+
kind: Secret
26+
metadata:
27+
name: openldap-simple-bind # <4>
28+
labels:
29+
secrets.stackable.tech/class: openldap-simple-bind # <5>
30+
stringData:
31+
user: cn=admin,dc=example,dc=org
32+
password: admin

‎modules/concepts/examples/authenticationclass-ldap-simple.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
apiVersion: authentication.stackable.tech/v1alpha1
2+
kind: AuthenticationClass
3+
metadata:
4+
name: ldap-simple
5+
spec:
6+
provider:
7+
ldap:
8+
hostname: my.ldap.server # <1>
9+
port: 389 # <2>
10+
searchBase: ou=users,dc=example,dc=org # <3>

‎modules/concepts/examples/authenticationclass-static-authenticationclass.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
apiVersion: authentication.stackable.tech/v1alpha1
2+
kind: AuthenticationClass
3+
metadata:
4+
name: simple-users
5+
spec:
6+
provider:
7+
static:
8+
userCredentialsSecret:
9+
name: simple-users-credentials # <1>

‎modules/concepts/examples/authenticationclass-static-secret.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
apiVersion: v1
2+
kind: Secret
3+
metadata:
4+
name: simple-users-credentials # <1>
5+
namespace: default # <2>
6+
type: kubernetes.io/opaque
7+
stringData:
8+
admin: admin
9+
alice: superpass
10+
bob: secret

‎modules/concepts/examples/authenticationclass-tls.yaml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
apiVersion: authentication.stackable.tech/v1alpha1
2+
kind: AuthenticationClass
3+
metadata:
4+
name: client-auth-tls
5+
spec:
6+
provider:
7+
tls:
8+
clientCertSecretClass: client-auth-tls

‎modules/concepts/examples/tls-mutual-verification.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
tls:
2+
verification:
3+
mutual:
4+
certSecretClass: openldap-tls

‎modules/concepts/examples/tls-no-verification.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
tls:
2+
verification:
3+
none: {}

‎modules/concepts/examples/tls-server-verification-custom-ca.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
tls:
2+
verification:
3+
server:
4+
caCert:
5+
secretClass: openldap-tls-ca

‎modules/concepts/examples/tls-server-verification-webpki.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
tls:
2+
verification:
3+
server:
4+
caCert:
5+
webPki: {}

‎modules/concepts/examples/tls-simple.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# [...]
2+
tls:
3+
verification:
4+
none: {}

‎modules/concepts/images/authenticationclass-ldap.plantuml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
allowmixing
2+
3+
database LDAP
4+
5+
map "Secret openldap-simple-bind" as secret_openldap_simple_bind {
6+
user => cn=admin,dc=example,dc=org
7+
password => admin
8+
}
9+
10+
map "Secret openldap-simple-ca" as secret_openldap_simple_ca {
11+
caCert => <ca certificate content>
12+
}
13+
14+
map "SecretClass openldap-simple-bind" as secret_class_openldap_simple_bind {
15+
k8sSearch *-> secret_openldap_simple_bind
16+
}
17+
18+
map "SecretClass openldap-simple-ca" as secret_class_openldap_simple_ca {
19+
k8sSearch *-> secret_openldap_simple_ca
20+
}
21+
22+
map "AuthenticationClass openldap-simple" as authentication_class_openldap_simple {
23+
ldapHost *--> LDAP
24+
tlsServerVerification *--> secret_class_openldap_simple_ca
25+
bindCredentials *--> secret_class_openldap_simple_bind
26+
ldapSearchBase => ou=users,dc=example,dc=org
27+
}

‎modules/concepts/nav.adoc

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
* xref:concepts:index.adoc[]
2-
** xref:roles-and-role-groups.adoc[]
3-
** xref:service_discovery.adoc[]
2+
** xref:authenticationclass.adoc[]
43
** xref:opa.adoc[]
5-
** xref:s3.adoc[]
4+
** xref:product_image_selection.adoc[]
65
** xref:pvc.adoc[]
76
** xref:resources.adoc[]
8-
** xref:product_image_selection.adoc[]
7+
** xref:roles-and-role-groups.adoc[]
8+
** xref:s3.adoc[]
9+
** xref:service_discovery.adoc[]
10+
** xref:tls_server_verification.adoc[]

‎modules/concepts/pages/authenticationclass.adoc

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
= `AuthenticationClass`
2+
3+
`AuthenticationClass` is a CRD describing a generic authentication method like LDAP or Kerberos.
4+
It has `cluster` scope, so it does not belong to a specific namespace.
5+
Multiple operators use this CRD as a way to express and configure the authentication methods of their respective product.
6+
7+
At the moment the following Authentication providers are supported:
8+
9+
* <<LDAP>>
10+
* <<TLS>>
11+
* <<Static>>
12+
13+
== LDAP
14+
A very simple `AuthenticationClass` with LDAP Authentication looks like this:
15+
16+
[source,yaml]
17+
----
18+
include::example$authenticationclass-ldap-simple.yaml[]
19+
----
20+
<1> The hostname of the LDAP server without any protocol or port
21+
<2> The port of the LDAP server. If TLS is used it defaults to `636` otherwise to `389`
22+
<3> An optional searchBase where the users should be searched
23+
24+
=== OpenLDAP
25+
Here is an example that is tuned for an OpenLDAP server and is configured to read bind user credentials from a secret:
26+
27+
[source,yaml]
28+
----
29+
include::example$authenticationclass-ldap-openldap-simple.yaml[]
30+
----
31+
<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 ②
32+
<2> The name of the xref:secret-operator::secretclass.adoc[] we are creating that is referred to by ➀. See xref:secret-operator::secretclass.adoc[]
33+
<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]
34+
<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
35+
<5> The name of the xref:secret-operator::secretclass.adoc[] that refers to this `Secret`. Must match the name of the xref:secret-operator::secretclass.adoc[] in this example in ②
36+
37+
The following diagram describes the relationship between the created CRDs
38+
39+
[plantuml]
40+
----
41+
include::image$authenticationclass-ldap.plantuml[]
42+
----
43+
44+
=== All possible attributes
45+
The following example shows all possible attributes:
46+
47+
[source,yaml]
48+
----
49+
include::example$authenticationclass-ldap-full.yaml[]
50+
----
51+
<1> The hostname of the LDAP server without any protocol or port
52+
<2> The port of the LDAP server. If TLS is used defaults to `636` otherwise to `389`
53+
<3> The searchBase where the users should be searched
54+
<4> Additional filter that filters the allowed users
55+
<5> The name of the corresponding field names in the LDAP objects
56+
<6> The name of the xref:secret-operator::secretclass.adoc[] providing the bind credentials (username and password)
57+
<7> The xref:secret-operator::scope.adoc[] of the xref:secret-operator::secretclass.adoc[]
58+
<8> xref:tls_server_verification.adoc[] of the LDAP server
59+
60+
== TLS
61+
The `TLS` provider configures a product to authenticate users using TLS certificates.
62+
When establishing a connection the client will first validate the certificate of the server.
63+
This step is not influenced by this `AuthenticationClass`, it only affects the next step:
64+
Afterwards the server checks the validity of the certificate the client has provided.
65+
This includes the usual checks - such as checking that it hasn't expired and matches the hostname of the client.
66+
Additionally the client certificate needs to be signed with the `ca` certificate, which is provided by the `SecretClass` specified in `clientCertSecretClass`.
67+
68+
A sample TLS provider looks as follows:
69+
70+
[source,yaml]
71+
----
72+
include::example$authenticationclass-tls.yaml[]
73+
----
74+
75+
== Static
76+
The `static` provider is used to represent a simple - static - set of users.
77+
Users are identified by a username and a password.
78+
79+
First of the `AuthenticationClass` needs to be defined as follows:
80+
81+
[source,yaml]
82+
----
83+
include::example$authenticationclass-static-authenticationclass.yaml[]
84+
----
85+
<1> The name of the `Secret` containing the credentials
86+
87+
Afterwards the referenced `Secret` needs to be created:
88+
89+
[source,yaml]
90+
----
91+
include::example$authenticationclass-static-secret.yaml[]
92+
----
93+
<1> The name of the `Secret`, which needs to match the `Secret` name specified in the `AuthenticationClass` above
94+
<2> The namespace of the `Secret`. The `Secret` needs to be in the same namespace as the product that tries to use the static `AuthenticationClass`

‎modules/concepts/pages/tls_server_verification.adoc

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
= TLS server verification
2+
3+
A TLS section is part of Stackable CRDs and describes how to connect to a TLS enabled system like LDAP or S3.
4+
5+
If the `tls` attribute is set to `null` (or is not specified), no TLS will be used for the connection.
6+
7+
A simple TLS section looks like this:
8+
9+
[source,yaml]
10+
----
11+
include::example$tls-simple.yaml[]
12+
----
13+
14+
== Verification
15+
The parties participating via a TLS connection can be verified using certificates.
16+
At the moment the following verification methods are supported:
17+
18+
* <<No verification>>
19+
* <<Server verification>>
20+
* <<Mutual verification>>
21+
22+
=== No verification
23+
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.
24+
25+
[source,yaml]
26+
----
27+
include::example$tls-no-verification.yaml[]
28+
----
29+
30+
=== Server verification
31+
This example will use TLS and verify the server using the ca certificates that are trusted by common web browsers.
32+
This can be useful when you e.g. use public AWS S3 or other public available services.
33+
34+
[source,yaml]
35+
----
36+
include::example$tls-server-verification-webpki.yaml[]
37+
----
38+
39+
This example will use TLS and verify the server using the provided ca certificate.
40+
For this to work you need to create a xref:secret-operator::secretclass.adoc[] that - at least - contains the ca certificate.
41+
Note that a SecretClass does not need to have a key but can also work with just a ca cert.
42+
So if you were provided with a ca cert but do not have access to the key you can still use this method.
43+
44+
[source,yaml]
45+
----
46+
include::example$tls-server-verification-custom-ca.yaml[]
47+
----
48+
49+
=== Mutual verification
50+
This example will use TLS and verify both - the server and the client using certificates.
51+
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.
52+
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.
53+
54+
[source,yaml]
55+
----
56+
include::example$tls-mutual-verification.yaml[]
57+
----

0 commit comments

Comments
 (0)