From 5c28f8decccf3f4569ac63f31f036f557ea40c58 Mon Sep 17 00:00:00 2001 From: Chris Bono Date: Wed, 13 Sep 2023 11:02:21 -0500 Subject: [PATCH] Add SSL docs and update authentication samples accordingly. (#443) --- .../main/asciidoc/attributes-variables.adoc | 2 +- .../src/main/asciidoc/authentication.adoc | 130 +++++++++--------- .../src/main/asciidoc/pulsar.adoc | 4 + .../src/main/asciidoc/tls-encryption.adoc | 20 +++ 4 files changed, 91 insertions(+), 65 deletions(-) create mode 100644 spring-pulsar-docs/src/main/asciidoc/tls-encryption.adoc diff --git a/spring-pulsar-docs/src/main/asciidoc/attributes-variables.adoc b/spring-pulsar-docs/src/main/asciidoc/attributes-variables.adoc index ee95b5cf..b16c9037 100644 --- a/spring-pulsar-docs/src/main/asciidoc/attributes-variables.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/attributes-variables.adoc @@ -15,7 +15,7 @@ :spring-cloud-stream-docs: https://docs.spring.io/spring-cloud-stream/docs/{spring-cloud-stream-version}/reference/html/ :spring-cloud-function: https://spring.io/projects/spring-cloud-function -:apache-pulsar-docs: https://pulsar.apache.org/docs/3.0.x +:apache-pulsar-docs: https://pulsar.apache.org/docs/3.1.x :apache-pulsar-cient-docs: {apache-pulsar-docs}/client-libraries-java :apache-pulsar-io-docs: {apache-pulsar-docs}/io-connectors :apache-pulsar-function-docs: {apache-pulsar-docs}/functions-overview diff --git a/spring-pulsar-docs/src/main/asciidoc/authentication.adoc b/spring-pulsar-docs/src/main/asciidoc/authentication.adoc index cdd2f207..aa7c354d 100644 --- a/spring-pulsar-docs/src/main/asciidoc/authentication.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/authentication.adoc @@ -1,32 +1,20 @@ include::attributes.adoc[] -To connect to a Pulsar cluster that requires authentication, you need to set the `authPluginClassName` and any parameters required by the authentication plugin. You can set the parameters as a single JSON-encoded string or as map of parameter names to parameter values. The following listings show both approaches: +To connect to a Pulsar cluster that requires authentication, you need to specify which authentication plugin to use and any parameters required by the specified plugin. +When **using Spring Boot** auto-configuration, you can set the plugin and the plugin parameters via configuration properties (in most cases). -[source,yaml,indent=0,role="primary"] -.[.small]#Map# ----- -spring: - pulsar: - client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 - authentication: - issuer-url: https://auth.server.cloud/ - private-key: file:///Users/some-key.json - audience: urn:sn:acme:dev:my-instance ----- +[NOTE] +==== +You need to ensure that names defined under `+spring.pulsar.client.authentication.param.*+` exactly match those expected by your auth plugin (which is typically camel cased). +Spring Boot will not attempt any kind of relaxed binding for these entries. -.[.small]#JSON encoded string# -[source,yaml,indent=0,role="secondary"] ----- -spring: - pulsar: - client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 - auth-params: "{\"privateKey\":\"file:///Users/some-key.json\",\"issuerUrl\":\"https://auth.server.cloud/", \"audience\":\"urn:sn:acme:dev:my-instance"}" ----- +For example, if you want to configure the issuer url for the `AuthenticationOAuth2` auth plugin you must use `+spring.pulsar.client.authentication.param.issuerUrl+`. +If you use other forms, such as `issuerurl` or `issuer-url`, the setting will not be applied to the plugin. +==== + +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. -TIP: Using a map is the recommended approach as it is less error-prone and easier to read. The following listings show how to configure each of the supported authentication mechanisms. @@ -39,15 +27,31 @@ The following listings show how to configure each of the supported authenticatio spring: pulsar: client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz authentication: - tenant-domain: ... - tenant-service: ... - provider-domain: ... - private-key: ... - key-id: ... - enable-tls: true - tls-trust-certs-file: /path/to/cacert.pem + plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz + param: + tenantDomain: ... + tenantService: ... + providerDomain: ... + privateKey: ... + keyId: ... +---- +NOTE: This also requires TLS encryption as described in <>. +==== + +[[Token]] +.[.underline]#Click ##here## for **Token**# +[%collapsible] +==== +[source, yaml] +---- +spring: + pulsar: + client: + authentication: + plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken + param: + token: some-token-goes-here ---- ==== @@ -60,10 +64,11 @@ spring: spring: pulsar: client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic authentication: - user-id: ... - password: ... + plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic + param: + userId: ... + password: ... ---- ==== @@ -76,12 +81,13 @@ spring: spring: pulsar: client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationFactoryOAuth2 authentication: - issuer-url: ... - private-key: ... - audience: ... - scope: ... + plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationFactoryOAuth2 + param: + issuerUrl: ... + privateKey: ... + audience: ... + scope: ... ---- ==== @@ -94,44 +100,40 @@ spring: spring: pulsar: client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl authentication: - sasl-jaas-client-section-name: ... - server-type: ... + plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl + param: + saslJaasClientSectionName: ... + serverType: ... ---- ==== -[[Tls]] -.[.underline]#Click ##here## for **Tls**# +[[mTlS-pem]] +.[.underline]#Click ##here## for **mTLS (PEM)**# [%collapsible] ==== -[source, yaml] +NOTE: Because this option requires TLS encryption, which already requires you to <>, it is recommended to simply add the authentication directly on the client builder in your provided TLS customizer. +You can use the `org.apache.pulsar.client.api.AuthenticationFactory` to help create the authentication object as follows: +[source,java] ---- -spring: - pulsar: - client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationTls - authentication: - tls-cert-file: /path/to/my-role.cert.pem - tls-key-file: /path/to/my-role.key-pk8.pem - enable-tls: true - tls-trust-certs-file: /path/to/cacert.pem +Authentication auth = AuthenticationFactory.TLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem"); ---- +See the official Pulsar documentation on {apache-pulsar-docs}/security-tls-authentication/#configure-mtls-authentication-in-pulsar-clients[mTLS (PEM)]. ==== -[[Token]] -.[.underline]#Click ##here## for **Token**# +[[mTLS-jks]] +.[.underline]#Click ##here## for **mTLS (JKS)**# [%collapsible] ==== -[source, yaml] +NOTE: Because this option requires TLS encryption, which already requires you to <>, it is recommended to simply add the authentication directly on the client builder in your provided TLS customizer. +You can use the `org.apache.pulsar.client.api.AuthenticationFactory` to help create the authentication object as follows: +[source,java] ---- -spring: - pulsar: - client: - auth-plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken - authentication: - token: some-token-goes-here +Authentication auth = AuthenticationFactory.create( + "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls", + Map.of("keyStoreType", "JKS", "keyStorePath", "/path/to/my/keystore.jks", "keyStorePassword", "clientpw")); ---- +See the official Pulsar documentation on {apache-pulsar-docs}/security-tls-authentication/#configure-clients[mTLS (JKS)]. ==== -NOTE: You can find more information on each of the schemes and their required properties in the official {apache-pulsar-docs}/security-overview#authentication-providers[Pulsar security] documentation. +You can find more information on each of the support plugins and their required properties in the official {apache-pulsar-docs}/security-overview#authentication-providers[Pulsar security] documentation. diff --git a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc index 3e89cb34..e1d568c4 100644 --- a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc @@ -27,6 +27,10 @@ You can further configure the client by specifying any of the {spring-boot-pulsa NOTE: If you are not using the starter, you will need to configure and register the `PulsarClient` yourself. There is a `DefaultPulsarClientFactory` that accepts a builder customizer that can be used to help with this. +[[tls-encryption]] +=== TLS Encryption (SSL) +include::tls-encryption.adoc[] + [[client-authentication]] === Authentication include::authentication.adoc[] diff --git a/spring-pulsar-docs/src/main/asciidoc/tls-encryption.adoc b/spring-pulsar-docs/src/main/asciidoc/tls-encryption.adoc new file mode 100644 index 00000000..ad443962 --- /dev/null +++ b/spring-pulsar-docs/src/main/asciidoc/tls-encryption.adoc @@ -0,0 +1,20 @@ + +include::attributes.adoc[] + +By default, Pulsar clients communicate with Pulsar services in plain text. +The following section describes how to configure Pulsar clients to use TLS encryption (SSL). +A pre-requisite is that the Broker has also been configured to use TLS encryption. + +The Spring Boot auto-configuration does not currently support any TLS/SSL configuration properties. +You can instead provide a `PulsarClientBuilderCustomizer` that sets the necessary properties on the Pulsar client builder. +Pulsar supports both Privacy Enhanced Mail (PEM) and Java KeyStore (JKS) certificate formats. + +Follow these steps to configure TLS: + +1. Adjust the Pulsar client service url to use the `pulsar+ssl://` scheme and TLS port (typically `6651`). +2. Adjust the admin client service url to use the `https://` scheme and TLS web port (typically `8443`). +3. Provide client builder customizer(s) that sets the relevant properties on the builder. + - {github}/blob/02730275e8d0291525eed9db5babe880c555a7bd/integration-tests/src/intTest/java/org/springframework/pulsar/inttest/app/SamplePemBasedSslConfig.java#L30-L49[PEM based sample] + - {github}/blob/02730275e8d0291525eed9db5babe880c555a7bd/integration-tests/src/intTest/java/org/springframework/pulsar/inttest/app/SampleJksBasedSslConfig.java#L30-L57[JKS based sample] + +You can find more information on the above in the official {apache-pulsar-docs}/security-tls-transport/[Pulsar TLS Encryption] documentation.