This is an automated email from the ASF dual-hosted git repository.
mmarshall pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 348701a5566 Document connecting through a proxy (#408)
348701a5566 is described below
commit 348701a55662318f7c7ad59a818605e2ec8b4495
Author: Michael Marshall <[email protected]>
AuthorDate: Tue Feb 14 22:04:31 2023 -0600
Document connecting through a proxy (#408)
* Add binary protocol doc for CommandConnect
* Document proxyRoles
Adding docs for apache/pulsar#19455
---
docs/developing-binary-protocol.md | 3 +++
docs/security-authorization.md | 2 ++
2 files changed, 5 insertions(+)
diff --git a/docs/developing-binary-protocol.md
b/docs/developing-binary-protocol.md
index bbbc70f9f27..798015f734f 100644
--- a/docs/developing-binary-protocol.md
+++ b/docs/developing-binary-protocol.md
@@ -142,6 +142,9 @@ Fields:
* `auth_method_name`: *(optional)* Name of the authentication plugin if auth
is enabled.
* `auth_data`: *(optional)* Plugin specific authentication data.
* `protocol_version`: Indicates the protocol version supported by the client.
Broker will not send commands introduced in newer revisions of the protocol.
Broker might be enforcing a minimum version.
+ * `original_principal`: Added by the proxy. Regular clients are not expected
to supply this value. When set and when authorization is enabled, the
`auth_data` must map to one of the `proxyRoles` in the broker.conf.
+ * `original_auth_method`: Added by the proxy. Regular clients are not
expected to supply this value.
+ * `original_auth_data`: Added by the proxy when configured to do so. Regular
clients are not expected to supply this value.
```protobuf
message CommandConnected {
diff --git a/docs/security-authorization.md b/docs/security-authorization.md
index a9c286b6a63..f11c85b165b 100644
--- a/docs/security-authorization.md
+++ b/docs/security-authorization.md
@@ -35,6 +35,8 @@ By default, the broker treats the connection between a proxy
and the broker as a
Pulsar uses *Proxy roles* to enable the authentication. Proxy roles are
specified in the broker configuration file,
[`conf/broker.conf`](reference-configuration.md#broker). If a client that is
authenticated with a broker is one of its `proxyRoles`, all requests from that
client must also carry information about the role of the client that is
authenticated with the proxy. This information is called the *original
principal*. If the *original principal* is absent, the client is not able to
[...]
+Note that if a Proxy is not correctly configured to use a role that is in the
`proxyRoles`, the connection will get rejected.
+
You must authorize both the *proxy role* and the *original principal* to
access a resource to ensure that the resource is accessible via the proxy.
Administrators can take two approaches to authorize the *proxy role* and the
*original principal*.
The more secure approach is to grant access to the proxy roles each time you
grant access to a resource. For example, if you have a proxy role named
`proxy1`, when the superuser creates a tenant, you should specify `proxy1` as
one of the admin roles. When a role is granted permission to produce or consume
from a namespace, if that client wants to produce or consume through a proxy,
you should also grant `proxy1` the same permissions.
