Additional documentation for OAuth 0.15.0 features and how to use Service Accounts #10317

mstruk · 2024-07-08T15:57:39Z

Type of change

Documentation

Description

This PR adds documentation for features introduced in #9970

Checklist

Please go through this checklist and make sure all applicable tasks have been done

Write tests
Make sure all tests pass
Update documentation
Check RBAC rights for Kubernetes / OpenShift roles
Try your changes from Pod inside your Kubernetes and OpenShift cluster, not just locally
Reference relevant issue(s) and close them after merging
Update CHANGELOG.md
Supply screenshots for visual changes, such as Grafana dashboards

PaulRMellor

Thanks Marko. I left a few suggestions, including removing repeating callout descriptions that we already describe earlier in particular sections to be a bit more streamline.

...in/java/io/strimzi/api/kafka/model/common/authentication/KafkaClientAuthenticationOAuth.java

...rc/main/java/io/strimzi/api/kafka/model/kafka/listener/KafkaListenerAuthenticationOAuth.java

documentation/modules/oauth/proc-oauth-kafka-config.adoc

PaulRMellor · 2024-07-10T13:50:40Z

documentation/modules/oauth/proc-oauth-kafka-config.adoc

+      - secretName: oauth-server-cert
+        pattern: "*.crt"
+----
+<1> Authentication type set to `oauth`.


I think we can drop 1, 2 and 4 callouts as we described the properties in the previous example.

documentation/modules/oauth/proc-oauth-kafka-config.adoc

PaulRMellor · 2024-07-10T14:06:55Z

documentation/modules/oauth/proc-oauth-kafka-config.adoc

+    type: oauth # <1>
+    accessTokenLocation: /var/run/secrets/kubernetes.io/serviceaccount/token # <2>
+----
+<1> Authentication type set to `oauth`.


we can remove callout 1.

mstruk

Made additional changes suggested in the review

mstruk · 2024-07-11T11:26:55Z

documentation/modules/oauth/con-oauth-authentication-broker.adoc

+    maxSecondsWithoutReauthentication: 3600 # <8>
+    customClaimCheck: "@.['kubernetes.io'] && @.['kubernetes.io'].['namespace'] in ['example']" # <9>
+----
+<1> Listener type set to `oauth`.


mstruk · 2024-07-11T11:30:33Z

documentation/modules/oauth/con-oauth-authentication-broker.adoc

+<7> Certificates stored in X.509 format within the specified secrets for TLS connection to the authorization server.
+<8> Activates the Kafka re-authentication mechanism that enforces session expiry to the same length of time as the access token. If the specified value is less than the time left for the access token to expire, then the client will have to re-authenticate before the actual token expiry. By default, the session does not expire when the access token expires, and the client does not attempt re-authentication.


Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

PaulRMellor

Thanks Marko. Just a couple of suggestions

...ion/api/io.strimzi.api.kafka.model.common.authentication.KafkaClientAuthenticationOAuth.adoc

documentation/modules/oauth/con-oauth-authentication-client.adoc

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

scholzj · 2024-07-18T13:29:42Z

documentation/modules/oauth/con-oauth-authentication-broker.adoc

+    tlsTrustedCertificates:
+      - secretName: oauth-server-cert
+        pattern: "*.crt"


Where do I get this Secret? I guess it should be using /var/run/secrets/kubernetes.io/serviceaccount/ca.crt? But it is not present in any Secret by default :-/. It might be in the ConfigMap, but not sure if it applies to all environments .

scholzj · 2024-07-18T13:41:25Z

documentation/modules/oauth/con-oauth-authentication-broker.adoc

+Note that the `tlsTrustedCertificates` is configured to point to a manually created Secret that contains the Kubernetes API server public certificate, which is mounted to the running pods under `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`.
+The Secret can be created using the following command:
+[source,shell,subs=attributes+]
+----
+kubectl get cm kube-root-ca.crt -o jsonpath="{['data']['ca\.crt']}" > /tmp/ca.crt
+kubectl create secret generic oauth-server-cert --from-file=ca.crt=/tmp/ca.crt
+----


Ok, you describe it here -> that should be in a callout of the example above.

We also might need to address it in some better way. Can't we configure the path to the CA directly? If not, we might need add support for loading the public keys from a CM as requested in #10308. (not necessarily blocker for this PR)

I opened #10354 to track this.

Within current CRD functionality I didn't find a way to specify this as a path to the file on the disk - basically a passthrough String rather than a Secret, with the expectation that the file is provided to the container by the infrastructure or another operator.

@scholzj I don't think you can add a code block to the content of the callout. Best I can do is refer to the further section that explains it in more detail.

Have you tried something like this? That should work:

<6> Trusted certificates to connect to authorization server. This should point to a manually created Secret that contains the Kubernetes API server public certificate, which is mounted to the running pods under `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. You can use the following commend to create the Secret: + [source,shell,subs=attributes+] ---- kubectl get cm kube-root-ca.crt -o jsonpath="{['data']['ca\.crt']}" > /tmp/ca.crt kubectl create secret generic oauth-server-cert --from-file=ca.crt=/tmp/ca.crt ----

Thanks, I modified it as you suggested. Looks like the plus does the trick.

documentation/modules/oauth/con-oauth-authentication-broker.adoc

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

scholzj · 2024-07-26T16:37:29Z

Thanks @mstruk

mstruk requested a review from PaulRMellor July 8, 2024 15:57

mstruk added this to the 0.43.0 milestone Jul 8, 2024

PaulRMellor reviewed Jul 10, 2024

View reviewed changes

mstruk commented Jul 11, 2024

View reviewed changes

mstruk force-pushed the serviceaccount-docs branch from 2e205dc to d9c65ba Compare July 15, 2024 10:54

mstruk and others added 14 commits July 17, 2024 10:30

Cleanup the docs and the tests

5141d5f

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Fix CHANGELOG.md

7723586

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Revert invalid CHANGELOG 'fix'

a0b7dd7

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Document using the service accounts for OAuth authentication

4f3aee2

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Document the usage of client assertion

4f843f2

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Fix 'unterminated open block' issue

e081b34

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Apply suggestions from code review

aa342e9

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Apply suggestions from code review

3d320b8

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Make additional changes proposed in PR review

c5d77a2

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Make default accessTokenLocation point to the service account token file

6fcce61

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Additional suggested changes

ef2ebef

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Commit updated CRD yaml and adoc files

1d599c8

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Fix rebase

a45ea1e

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Additional docs changes

eddbc1a

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

mstruk force-pushed the serviceaccount-docs branch from d9c65ba to eddbc1a Compare July 17, 2024 09:44

mstruk marked this pull request as ready for review July 17, 2024 11:15

mstruk requested a review from PaulRMellor July 17, 2024 11:15

Additional docs improvements

fb233ac

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

PaulRMellor approved these changes Jul 18, 2024

View reviewed changes

...ion/api/io.strimzi.api.kafka.model.common.authentication.KafkaClientAuthenticationOAuth.adoc Outdated Show resolved Hide resolved

documentation/modules/oauth/con-oauth-authentication-client.adoc Outdated Show resolved Hide resolved

Apply suggestions from code review

2777f1e

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com> Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

scholzj self-requested a review July 18, 2024 12:50

This was referenced Jul 18, 2024

Add way to manage ACLs and Quotas for Service Accounts through the User Operator #10353

Open

Make it easier to handle TLS trust in service account based authentication #10354

Open

scholzj reviewed Jul 18, 2024

View reviewed changes

Improvements based on review comments

de6c4f9

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

mstruk added 2 commits July 25, 2024 12:19

Add a callout to creating a CA secret manually

2640d32

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Fix the callout as suggested in the review

5fd0da7

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

scholzj approved these changes Jul 26, 2024

View reviewed changes

scholzj merged commit fd0ad18 into strimzi:main Jul 26, 2024
13 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Additional documentation for OAuth 0.15.0 features and how to use Service Accounts #10317

Additional documentation for OAuth 0.15.0 features and how to use Service Accounts #10317

mstruk commented Jul 8, 2024

PaulRMellor left a comment

PaulRMellor Jul 10, 2024

PaulRMellor Jul 10, 2024

mstruk left a comment

mstruk Jul 11, 2024

mstruk Jul 11, 2024

PaulRMellor left a comment

scholzj Jul 18, 2024

scholzj Jul 18, 2024

mstruk Jul 19, 2024

mstruk Jul 25, 2024 •

edited

Loading

scholzj Jul 25, 2024

scholzj Jul 25, 2024

mstruk Jul 26, 2024

scholzj Jul 26, 2024

scholzj commented Jul 26, 2024

		<7> Certificates stored in X.509 format within the specified secrets for TLS connection to the authorization server.
		<8> Activates the Kafka re-authentication mechanism that enforces session expiry to the same length of time as the access token. If the specified value is less than the time left for the access token to expire, then the client will have to re-authenticate before the actual token expiry. By default, the session does not expire when the access token expires, and the client does not attempt re-authentication.

Additional documentation for OAuth 0.15.0 features and how to use Service Accounts #10317

Additional documentation for OAuth 0.15.0 features and how to use Service Accounts #10317

Conversation

mstruk commented Jul 8, 2024

Type of change

Description

Checklist

PaulRMellor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mstruk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PaulRMellor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mstruk Jul 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scholzj commented Jul 26, 2024

mstruk Jul 25, 2024 •

edited

Loading