From 6b6f0be0ae971bf53607f9decec9d8e91a7475af Mon Sep 17 00:00:00 2001
From: Chris Bono <cbono@vmware.com>
Date: Mon, 19 Feb 2024 00:29:50 -0600
Subject: [PATCH] Document workaround for env var auth params (#581)

Also fix collapsible section on authentication.adoc
---
 .../ROOT/pages/reference/authentication.adoc  | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/authentication.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/authentication.adoc
index cb217f9c..0475823f 100644
--- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/authentication.adoc
+++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/authentication.adoc
@@ -13,6 +13,28 @@ For example, if you want to configure the issuer url for the `AuthenticationOAut
 If you use other forms, such as `issuerurl` or `issuer-url`, the setting will not be applied to the plugin.
 ====
 
+[TIP]
+====
+Using environment variables for auth parameters is typically problematic because the case sensitivity is lost during translation.
+For example, consider the following `issuerUrl` auth parameter set via an environment variable:
+[source,properties]
+----
+SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com
+----
+When Spring Boot loads this property it will use `issuerurl` (lower-cased) rather than the expected `issuerUrl` (camel-cased).
+You can get around this limitation by using the value of the env var as the value of the related auth property in your application.yml.
+Continuing the example above:
+[source,yaml]
+----
+spring:
+  pulsar:
+    client:
+      authentication:
+        param:
+          issuerUrl: ${SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL}
+----
+====
+
 When **not using Spring Boot** auto-configuration, you can use the `org.apache.pulsar.client.api.AuthenticationFactory` to create the authentication and then set it directly on the Pulsar client builder in a client customizer that you provide to the client factory.
 
 
@@ -22,6 +44,7 @@ The following listings show how to configure each of the supported authenticatio
 .[.underline]#Click ##here## for **Athenz**#
 [%collapsible]
 [source, yaml]
+====
 ----
 spring:
   pulsar:
@@ -36,11 +59,13 @@ spring:
           keyId: ...
 ----
 NOTE: This also requires xref:reference/pulsar.adoc#tls-encryption[TLS encryption].
+====
 
 [[Token]]
 .[.underline]#Click ##here## for **Token**#
 [%collapsible]
 [source, yaml]
+====
 ----
 spring:
   pulsar:
@@ -50,11 +75,13 @@ spring:
         param:
           token: some-token-goes-here
 ----
+====
 
 [[Basic]]
 .[.underline]#Click ##here## for **Basic**#
 [%collapsible]
 [source, yaml]
+====
 ----
 spring:
   pulsar:
@@ -65,11 +92,13 @@ spring:
           userId: ...
           password: ...
 ----
+====
 
 [[OAuth2]]
 .[.underline]#Click ##here## for **OAuth2**#
 [%collapsible]
 [source, yaml]
+====
 ----
 spring:
   pulsar:
@@ -82,11 +111,13 @@ spring:
           audience: ...
           scope: ...
 ----
+====
 
 [[Sasl]]
 .[.underline]#Click ##here## for **Sasl**#
 [%collapsible]
 [source, yaml]
+====
 ----
 spring:
   pulsar:
@@ -97,6 +128,7 @@ spring:
           saslJaasClientSectionName: ...
           serverType: ...
 ----
+====
 
 [[mTlS-pem]]
 .[.underline]#Click ##here## for **mTLS (PEM)**#