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 5530bca4604 Document OpenID Connect Auth Provider (#555)
5530bca4604 is described below
commit 5530bca4604440440d33e6255d34a810b9994c60
Author: Michael Marshall <mmarsh...@apache.org>
AuthorDate: Fri May 5 10:22:13 2023 -0500
Document OpenID Connect Auth Provider (#555)
* Document OpenID Connect Auth Provider
* Update sidebars.json
* Document using openIDAcceptedTimeLeewaySeconds
* Fix build error
* Remove accidentally copied text
* Apply suggestions from code review
Co-authored-by: Jun Ma <60642177+momo-...@users.noreply.github.com>
* Fix note blocks
* Copy docs to 3.0.x
---------
Co-authored-by: Jun Ma <60642177+momo-...@users.noreply.github.com>
---
docs/security-openid-connect.md | 134 +++++++++++++++++++++
docs/security-overview.md | 1 +
sidebars.json | 5 +-
.../version-3.0.x/security-openid-connect.md | 134 +++++++++++++++++++++
versioned_docs/version-3.0.x/security-overview.md | 1 +
versioned_sidebars/version-3.0.x-sidebars.json | 1 +
6 files changed, 274 insertions(+), 2 deletions(-)
diff --git a/docs/security-openid-connect.md b/docs/security-openid-connect.md
new file mode 100644
index 00000000000..b0fa65be3df
--- /dev/null
+++ b/docs/security-openid-connect.md
@@ -0,0 +1,134 @@
+---
+id: security-openid-connect
+title: Authentication using OpenID Connect
+sidebar_label: "Authentication using OpenID Connect"
+---
+
+Apache Pulsar supports authenticating clients using [OpenID
Connect](https://openid.net/connect), which is an implementation of the OAuth
2.0 Protocol. Using an access token obtained from an OpenID Connect compliant
Identity Provider service acting as the token issuer, you can identify a Pulsar
client and associate it with a "principal" (or "role") that is permitted to do
some actions, such as publishing messages to a topic or performing some admin
operation.
+
+The source code for the OpenID Connect implementation is in the
[pulsar-broker-auth-oidc](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-oidc/)
submodule in the Apache Pulsar git repo.
+
+## OpenID Connect Authentication Flow
+
+After authenticating with the Identity Provider, the Pulsar client gets an
access token from the server and passes this access token to Pulsar Server
(Broker, Proxy, WebSocket Proxy, or Function Worker) for authentication. When
using the `AuthenticationProviderOpenID` class, the Pulsar Server performs the
following validations in order:
+
+1. Validate that the token's issuer claim (`iss`) is one of the allowed token
issuers (`openIDAllowedTokenIssuers`).
+2. Retrieve and cache the OpenID Connect discovery document from the issuer
following the [OpenID Connect Discovery
1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) specification.
+3. Verify the resulting JSON document's `issuer` field matches the token's
issuer claim.
+4. Retrieve and cache the public key set from the `jwks_uri` provided by the
discovery document obtained in step 2.
+5. Verify the signature of the token using the public key set obtained in step
4.
+6. Validate the token's claims, like `aud`, `exp`, `iat`, and `nbf`.
+7. When token validation is successful, the Pulsar Server extracts the `sub`
claim from the token (or the configured `openIDRoleClaim`) and uses it as the
principal for authorization.
+8. When the token expires, the Pulsar Server challenges the client to
re-authenticate with the Identity Provider and provide a new access token. If
the client fails to re-authenticate, the Pulsar Server closes the connection.
+
+## Enable OpenID Connect Authentication in the Brokers, Proxies, and WebSocket
Proxies
+
+To configure Pulsar Servers to authenticate clients using OpenID Connect, add
the following parameters to the `conf/broker.conf`, the `conf/proxy.conf`, and
the `conf/websocket.conf` files. If you use a standalone Pulsar, you need to
add these parameters to the `conf/standalone.conf` file:
+
+```properties
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.oidc.AuthenticationProviderOpenID
+
+# Required settings for AuthenticationProviderOpenID
+# A comma separated list of allowed, or trusted, token issuers. The token
issuer is the URL of the token issuer.
+PULSAR_PREFIX_openIDAllowedTokenIssuers=https://my-issuer-1.com,https://my-issuer-2.com
+# The list of allowed audiences for the token. The audience is the intended
recipient of the token. A token with
+# at least one of these audience claims will pass the audience validation
check.
+PULSAR_PREFIX_openIDAllowedAudiences=audience-1,audience-2
+
+# Optional settings (values shown are the defaults)
+# The path to the file containing the trusted certificate(s) of the token
issuer(s). If not set, uses the default
+# trust store of the JVM.
+PULSAR_PREFIX_openIDTokenIssuerTrustCertsFilePath=
+# The JWT's claim to use for the role/principal during authorization.
+PULSAR_PREFIX_openIDRoleClaim=sub
+# The leeway, in seconds, to use when validating the token's expiration time.
+PULSAR_PREFIX_openIDAcceptedTimeLeewaySeconds=0
+
+# Cache settings
+PULSAR_PREFIX_openIDCacheSize=5
+PULSAR_PREFIX_openIDCacheRefreshAfterWriteSeconds=64800
+PULSAR_PREFIX_openIDCacheExpirationSeconds=86400
+PULSAR_PREFIX_openIDHttpConnectionTimeoutMillis=10000
+PULSAR_PREFIX_openIDHttpReadTimeoutMillis=10000
+
+# Whether to require that issuers use HTTPS. It is part of the OIDC spec to
use HTTPS, so the default is true.
+# This setting is for testing purposes and is not recommended for any
production environment.
+PULSAR_PREFIX_openIDRequireIssuersUseHttps=true
+
+# A setting describing how to handle discovery of the OpenID Connect
configuration document when the issuer is not
+# in the list of allowed issuers. This setting is documented below.
+PULSAR_PREFIX_openIDFallbackDiscoveryMode=DISABLED
+```
+
+:::note
+
+When using OIDC for a client connecting through the proxy to the broker, it is
necessary to set the broker's `openIDAcceptedTimeLeewaySeconds` to double the
proxy's `authenticationRefreshCheckSeconds` configuration because the proxy
caches the client's token and only refreshes it when it is expired. As such, in
certain cases, when the proxy initiates a new connection to the broker, the
token may not yet be expired in the proxy, but may be expired when it reaches
the broker. You can mitig [...]
+
+:::
+
+## Enable OpenID Connect Authentication in the Function Worker
+
+To configure the Pulsar Function Worker to authenticate clients using OpenID
Connect, add the following parameters to the `conf/functions_worker.yml` file.
The documentation for these settings is
[above](#enable-openid-connect-authentication-in-the-brokers-proxies-and-websocket-proxies).
+
+```yaml
+# Configuration to enable authentication
+authenticationEnabled: true
+authenticationProviders:
"org.apache.pulsar.broker.authentication.oidc.AuthenticationProviderOpenID"
+properties:
+ openIDAllowedTokenIssuers: "https://my-issuer-1.com,https://my-issuer-2.com";
+ openIDAllowedAudiences: "audience-1,audience-2"
+ openIDTokenIssuerTrustCertsFilePath: ""
+ openIDRoleClaim: "sub"
+ openIDAcceptedTimeLeewaySeconds: 0
+ openIDCacheSize: 5
+ openIDCacheRefreshAfterWriteSeconds: 64800
+ openIDCacheExpirationSeconds: 86400
+ openIDHttpConnectionTimeoutMillis: 10000
+ openIDHttpReadTimeoutMillis: 10000
+ openIDRequireIssuersUseHttps: true
+ openIDFallbackDiscoveryMode: "DISABLED"
+```
+
+## Enable Custom OpenID Connect Integration with Kubernetes
+
+Kubernetes has a built-in OpenID Connect integration where [Service Account
Token Volume
Projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
can easily be mounted into pods as signed JWTs that can be used as OpenID
Connect access tokens. The only drawback is that the [Kubernetes token issuer
discovery](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-iss
[...]
+
+The modes configure how the Open ID Connect Authentication Provider should
handle a JWT that has an issuer claim that is not explicitly in the allowed
issuers set configured by `openIDAllowedTokenIssuers`. The current
implementations rely on using the Kubernetes API Server's Open ID Connect
features to discover an additional issuer or additional public keys to trust.
+
+The available values for `openIDFallbackDiscoveryMode` are: `DISABLED`,
`KUBERNETES_DISCOVER_TRUSTED_ISSUER`, and `KUBERNETES_DISCOVER_PUBLIC_KEYS`.
The quick summary is that EKS requires `KUBERNETES_DISCOVER_TRUSTED_ISSUER`
right now, but GKE and AKS require `KUBERNETES_DISCOVER_PUBLIC_KEYS`. The
implementation details follow.
+
+1. `DISABLED`: There will be no discovery of additional trusted issuers or
public keys. This setting requires that operators explicitly allow all issuers
that will be trusted. For the Kubernetes Service Account Token Projections to
work, the operator must explicitly trust the issuer on the token's `iss` claim.
This is the default setting because it is the only mode that explicitly follows
the OIDC spec for verification of discovered provider configuration.
+2. `KUBERNETES_DISCOVER_TRUSTED_ISSUER`: The Kubernetes API Server will be
used to discover an additional trusted issuer by getting the issuer at the API
Server's `/.well-known/openid-configuration` endpoint, verifying that issuer
matches the `iss` claim on the supplied token, then treating that issuer as a
trusted issuer by discovering the `jwks_uri` via that issuer's
`/.well-known/openid-configuration` endpoint. This mode can be helpful in EKS
environments where the API Server's public [...]
+3. `KUBERNETES_DISCOVER_PUBLIC_KEYS`: The Kubernetes API Server will be used
to discover an additional set of valid public keys by getting the issuer at the
API Server's `/.well-known/openid-configuration` endpoint, verifying that
issuer matches the `iss` claim on the supplied token, then calling the API
Server endpoint to get the public keys using a Kubernetes client. This mode is
currently useful for getting the public keys from the API Server because the
API Server requires custom TLS [...]
+
+:::note
+
+When deploying with either `KUBERNETES_DISCOVER_TRUSTED_ISSUER` or
`KUBERNETES_DISCOVER_PUBLIC_KEYS`, you will likely encounter an error like the
following `forbidden: User \"system:serviceaccount:pulsar:superuser\" cannot
get path \"/.well-known/openid-configuration/\"`. That error is a result of
https://github.com/kubernetes/kubernetes/issues/117455, which happens because
the `AuthenticationProviderOpenID` plugin uses the Java Kubernetes client to
connect to the Kubernetes API Server. [...]
+
+```bash
+kubectl patch clusterrole system:service-account-issuer-discovery --patch
'{"rules":[{"nonResourceURLs":["/.well-known/openid-configuration/","/.well-known/openid-configuration","/openid/v1/jwks/","/openid/v1/jwks"],"verbs":["get"]}]}'
+```
+
+:::
+
+## Configuring Pulsar Components and Applications to use Projected Service
Account Tokens to Authenticate with other Pulsar Components
+
+To leverage [Service Account Token Volume
Projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
in your pulsar components, follow the Kubernetes documentation on mounting
service account tokens and then configure the pulsar components to use the
token with the following config:
+
+```properties
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+brokerClientAuthenticationParameters=file:///path/to/mounted/token
+```
+
+We use the `AuthenticationToken` client plugin because Kubernetes
automatically retrieves and refreshes the token for us. The
`AuthenticationToken` works because it always reads the token from the
filesystem, which ensures that it will always read the latest token.
+
+## Enabling AuthenticationProviderOpenID Connect and
AuthenticationProviderToken Simultaneously
+
+In order to simplify migration from Static JWTs to OIDC Authentication, it is
possible to configure both the `AuthenticationProviderOpenID` and
`AuthenticationProviderToken` simultaneously. This allows for a seamless
transition from static JWTs to OIDC tokens. The `AuthenticationProviderToken`
will be used to authenticate clients that do not provide an OIDC token, and the
`AuthenticationProviderOpenID` will be used to authenticate clients that do
provide an OIDC token.
+
+
+## Configure OIDC authentication in Pulsar Clients and CLI Tools
+
+See the [OAuth2](security-oauth2.md) documentation for configuring clients to
use OAuth2 authentication.
diff --git a/docs/security-overview.md b/docs/security-overview.md
index 7b550ebf5f1..cf5304412af 100644
--- a/docs/security-overview.md
+++ b/docs/security-overview.md
@@ -58,6 +58,7 @@ When you use proxies between clients and brokers, there are
two authentication d
- [Kerberos authentication](security-kerberos.md)
- [JSON Web Token (JWT) authentication](security-jwt.md)
- [OAuth 2.0 authentication](security-oauth2.md)
+ - [OpenID Connect](security-openid-connect.md)
- [HTTP basic authentication](security-basic-auth.md)
- To customize an authentication plugin, read [extended
authentication](security-extending.md).
diff --git a/sidebars.json b/sidebars.json
index 4f539bdd3ae..574c665e8d1 100644
--- a/sidebars.json
+++ b/sidebars.json
@@ -219,7 +219,7 @@
},
"items": [
"deploy-aws",
- "deploy-ibm",
+ "deploy-ibm",
{
"type": "category",
"label": "Kubernetes",
@@ -296,6 +296,7 @@
"security-athenz",
"security-kerberos",
"security-oauth2",
+ "security-openid-connect",
"security-basic-auth"
]
},
@@ -382,7 +383,7 @@
"client-libraries-node-setup",
"client-libraries-node-initialize",
"client-libraries-node-use",
- "client-libraries-node-configs"
+ "client-libraries-node-configs"
]
},
{
diff --git a/versioned_docs/version-3.0.x/security-openid-connect.md
b/versioned_docs/version-3.0.x/security-openid-connect.md
new file mode 100644
index 00000000000..51744d3e7fd
--- /dev/null
+++ b/versioned_docs/version-3.0.x/security-openid-connect.md
@@ -0,0 +1,134 @@
+---
+id: security-openid-connect
+title: Authentication using OpenID Connect
+sidebar_label: "Authentication using OpenID Connect"
+---
+
+Apache Pulsar supports authenticating clients using [OpenID
Connect](https://openid.net/connect), which is an implementation of the OAuth
2.0 Protocol. Using an access token obtained from an OpenID Connect compliant
Identity Provider service acting as the token issuer, you can identify a Pulsar
client and associate it with a "principal" (or "role") that is permitted to do
some actions, such as publishing messages to a topic or performing some admin
operation.
+
+The source code for the OpenID Connect implementation is in the
[pulsar-broker-auth-oidc](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-oidc/)
submodule in the Apache Pulsar git repo.
+
+## OpenID Connect Authentication Flow
+
+After authenticating with the Identity Provider, the Pulsar client gets an
access token from the server and passes this access token to Pulsar Server
(Broker, Proxy, WebSocket Proxy, or Function Worker) for authentication. When
using the `AuthenticationProviderOpenID` class, the Pulsar Server performs the
following validations in order:
+
+1. Validate that the token's issuer claim (`iss`) is one of the allowed token
issuers (`openIDAllowedTokenIssuers`).
+2. Retrieve and cache the OpenID Connect discovery document from the issuer
following the [OpenID Connect Discovery
1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) specification.
+3. Verify the resulting JSON document's `issuer` field matches the token's
issuer claim.
+4. Retrieve and cache the public key set from the `jwks_uri` provided by the
discovery document obtained in step 2.
+5. Verify the signature of the token using the public key set obtained in step
4.
+6. Validate the token's claims, like `aud`, `exp`, `iat`, and `nbf`.
+7. When token validation is successful, the Pulsar Server extracts the `sub`
claim from the token (or the configured `openIDRoleClaim`) and uses it as the
principal for authorization.
+8. When the token expires, the Pulsar Server challenges the client to
re-authenticate with the Identity Provider and provide a new access token. If
the client fails to re-authenticate, the Pulsar Server closes the connection.
+
+## Enable OpenID Connect Authentication in the Brokers, Proxies, and WebSocket
Proxies
+
+To configure Pulsar Servers to authenticate clients using OpenID Connect, add
the following parameters to the `conf/broker.conf`, the `conf/proxy.conf`, and
the `conf/websocket.conf` files. If you use a standalone Pulsar, you need to
add these parameters to the `conf/standalone.conf` file:
+
+```properties
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.oidc.AuthenticationProviderOpenID
+
+# Required settings for AuthenticationProviderOpenID
+# A comma separated list of allowed, or trusted, token issuers. The token
issuer is the URL of the token issuer.
+PULSAR_PREFIX_openIDAllowedTokenIssuers=https://my-issuer-1.com,https://my-issuer-2.com
+# The list of allowed audiences for the token. The audience is the intended
recipient of the token. A token with
+# at least one of these audience claims will pass the audience validation
check.
+PULSAR_PREFIX_openIDAllowedAudiences=audience-1,audience-2
+
+# Optional settings (values shown are the defaults)
+# The path to the file containing the trusted certificate(s) of the token
issuer(s). If not set, uses the default
+# trust store of the JVM.
+PULSAR_PREFIX_openIDTokenIssuerTrustCertsFilePath=
+# The JWT's claim to use for the role/principal during authorization.
+PULSAR_PREFIX_openIDRoleClaim=sub
+# The leeway, in seconds, to use when validating the token's expiration time.
+PULSAR_PREFIX_openIDAcceptedTimeLeewaySeconds=0
+
+# Cache settings
+PULSAR_PREFIX_openIDCacheSize=5
+PULSAR_PREFIX_openIDCacheRefreshAfterWriteSeconds=64800
+PULSAR_PREFIX_openIDCacheExpirationSeconds=86400
+PULSAR_PREFIX_openIDHttpConnectionTimeoutMillis=10000
+PULSAR_PREFIX_openIDHttpReadTimeoutMillis=10000
+
+# Whether to require that issuers use HTTPS. It is part of the OIDC spec to
use HTTPS, so the default is true.
+# This setting is for testing purposes and is not recommended for any
production environment.
+PULSAR_PREFIX_openIDRequireIssuersUseHttps=true
+
+# A setting describing how to handle discovery of the OpenID Connect
configuration document when the issuer is not
+# in the list of allowed issuers. This setting is documented below.
+PULSAR_PREFIX_openIDFallbackDiscoveryMode=DISABLED
+```
+
+:::note
+
+When using OIDC for a client connecting through the proxy to the broker, it is
necessary to set the broker's `openIDAcceptedTimeLeewaySeconds` to double the
proxy's `authenticationRefreshCheckSeconds` configuration because the proxy
caches the client's token and only refreshes it when it is expired. As such, in
certain cases, when the proxy initiates a new connection to the broker, the
token may not yet be expired in the proxy, but may be expired when it reaches
the broker. You can mitig [...]
+
+:::
+
+## Enable OpenID Connect Authentication in the Function Worker
+
+To configure the Pulsar Function Worker to authenticate clients using OpenID
Connect, add the following parameters to the `conf/functions_worker.yml` file.
The documentation for these settings is
[above](#enable-openid-connect-authentication-in-the-brokers-proxies-and-websocket-proxies).
+
+```yaml
+# Configuration to enable authentication
+authenticationEnabled: true
+authenticationProviders:
"org.apache.pulsar.broker.authentication.oidc.AuthenticationProviderOpenID"
+properties:
+ openIDAllowedTokenIssuers: "https://my-issuer-1.com,https://my-issuer-2.com";
+ openIDAllowedAudiences: "audience-1,audience-2"
+ openIDTokenIssuerTrustCertsFilePath: ""
+ openIDRoleClaim: "sub"
+ openIDAcceptedTimeLeewaySeconds: 0
+ openIDCacheSize: 5
+ openIDCacheRefreshAfterWriteSeconds: 64800
+ openIDCacheExpirationSeconds: 86400
+ openIDHttpConnectionTimeoutMillis: 10000
+ openIDHttpReadTimeoutMillis: 10000
+ openIDRequireIssuersUseHttps: true
+ openIDFallbackDiscoveryMode: "DISABLED"
+```
+
+## Enable Custom OpenID Connect Integration with Kubernetes
+
+Kubernetes has a built-in OpenID Connect integration where [Service Account
Token Volume
Projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
can easily be mounted into pods as signed JWTs that can be used as OpenID
Connect access tokens. The only drawback is that the [Kubernetes token issuer
discovery](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-iss
[...]
+
+The modes configure how the Open ID Connect Authentication Provider should
handle a JWT that has an issuer claim that is not explicitly in the allowed
issuers set configured by `openIDAllowedTokenIssuers`. The current
implementations rely on using the Kubernetes API Server's Open ID Connect
features to discover an additional issuer or additional public keys to trust.
+
+The available values for `openIDFallbackDiscoveryMode` are: `DISABLED`,
`KUBERNETES_DISCOVER_TRUSTED_ISSUER`, and `KUBERNETES_DISCOVER_PUBLIC_KEYS`.
The quick summary is that EKS requires `KUBERNETES_DISCOVER_TRUSTED_ISSUER`
right now, but GKE and AKS require `KUBERNETES_DISCOVER_PUBLIC_KEYS`. The
implementation details follow.
+
+1. `DISABLED`: There will be no discovery of additional trusted issuers or
public keys. This setting requires that operators explicitly allow all issuers
that will be trusted. For the Kubernetes Service Account Token Projections to
work, the operator must explicitly trust the issuer on the token's `iss` claim.
This is the default setting because it is the only mode that explicitly follows
the OIDC spec for verification of discovered provider configuration.
+2. `KUBERNETES_DISCOVER_TRUSTED_ISSUER`: The Kubernetes API Server will be
used to discover an additional trusted issuer by getting the issuer at the API
Server's `/.well-known/openid-configuration` endpoint, verifying that issuer
matches the `iss` claim on the supplied token, then treating that issuer as a
trusted issuer by discovering the `jwks_uri` via that issuer's
`/.well-known/openid-configuration` endpoint. This mode can be helpful in EKS
environments where the API Server's public [...]
+3. `KUBERNETES_DISCOVER_PUBLIC_KEYS`: The Kubernetes API Server will be used
to discover an additional set of valid public keys by getting the issuer at the
API Server's `/.well-known/openid-configuration` endpoint, verifying that
issuer matches the `iss` claim on the supplied token, then calling the API
Server endpoint to get the public keys using a kubernetes client. This mode is
currently useful getting the public keys from the API Server because the API
Server requires custom TLS and [...]
+
+:::note
+
+When deploying with either `KUBERNETES_DISCOVER_TRUSTED_ISSUER` or
`KUBERNETES_DISCOVER_PUBLIC_KEYS`, you will likely encounter an error like the
following `forbidden: User \"system:serviceaccount:pulsar:superuser\" cannot
get path \"/.well-known/openid-configuration/\"`. That error is a result of
https://github.com/kubernetes/kubernetes/issues/117455, which happens because
the `AuthenticationProviderOpenID` plugin uses the Java Kubernetes client to
connect to the Kubernetes API Server. [...]
+
+```bash
+kubectl patch clusterrole system:service-account-issuer-discovery --patch
'{"rules":[{"nonResourceURLs":["/.well-known/openid-configuration/","/.well-known/openid-configuration","/openid/v1/jwks/","/openid/v1/jwks"],"verbs":["get"]}]}'
+```
+
+:::
+
+## Configuring Pulsar Components and Applications to use Projected Service
Account Tokens to Authenticate with other Pulsar Components
+
+To leverage [Service Account Token Volume
Projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
in your pulsar components, update your it is sufficient to follow the
Kubernetes documentation on mounting service account tokens and then
configuring the pulsar components to use the token with the following config:
+
+```properties
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+brokerClientAuthenticationParameters=file:///path/to/mounted/token
+```
+
+We use the `AuthenticationToken` client plugin because Kubernetes
automatically retrieves and refreshes the token for us. The
`AuthenticationToken` works because it always reads the token from the
filesystem, which ensures that it will always read the latest token.
+
+## Enabling AuthenticationProviderOpenID Connect and
AuthenticationProviderToken Simultaneously
+
+In order to simplify migration from Static JWTs to OIDC Authentication, it is
possible to configure both the `AuthenticationProviderOpenID` and
`AuthenticationProviderToken` simultaneously. This allows for a seamless
transition from static JWTs to OIDC tokens. The `AuthenticationProviderToken`
will be used to authenticate clients that do not provide an OIDC token, and the
`AuthenticationProviderOpenID` will be used to authenticate clients that do
provide an OIDC token.
+
+
+## Configure OIDC authentication in Pulsar Clients and CLI Tools
+
+See the [OAuth2](security-oauth2.md) documentation for configuring clients to
use OAuth2 authentication.
diff --git a/versioned_docs/version-3.0.x/security-overview.md
b/versioned_docs/version-3.0.x/security-overview.md
index 7b550ebf5f1..cf5304412af 100644
--- a/versioned_docs/version-3.0.x/security-overview.md
+++ b/versioned_docs/version-3.0.x/security-overview.md
@@ -58,6 +58,7 @@ When you use proxies between clients and brokers, there are
two authentication d
- [Kerberos authentication](security-kerberos.md)
- [JSON Web Token (JWT) authentication](security-jwt.md)
- [OAuth 2.0 authentication](security-oauth2.md)
+ - [OpenID Connect](security-openid-connect.md)
- [HTTP basic authentication](security-basic-auth.md)
- To customize an authentication plugin, read [extended
authentication](security-extending.md).
diff --git a/versioned_sidebars/version-3.0.x-sidebars.json
b/versioned_sidebars/version-3.0.x-sidebars.json
index 2549c25d23b..eab2a3acb04 100644
--- a/versioned_sidebars/version-3.0.x-sidebars.json
+++ b/versioned_sidebars/version-3.0.x-sidebars.json
@@ -296,6 +296,7 @@
"security-athenz",
"security-kerberos",
"security-oauth2",
+ "security-openid-connect",
"security-basic-auth"
]
},
