📚 Sync docs from alaudadevops/connectors-operator on a87919a042d0dbaa33c7e409178f7935f6dd9777

Source: docs: add docs to explain how to use auth exactor to customize built-in reverse proxy (#315)
Author: chengjingtao
Ref: refs/heads/main
Commit: a87919a042d0dbaa33c7e409178f7935f6dd9777

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: AlaudaDevops/connectors-operator@a87919a
🤖 Synced on 2025-11-18 11:06:56 UTC

Author: chengjingtao

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-11-12 10:24:25 UTC
+- **Last synced**: 2025-11-18 11:06:56 UTC
 - **Source repository**: alaudadevops/connectors-operator
-- **Source commit**: [00fbb705a0a71e01a0506cbec45c5dfaddc78061](https://github.com/alaudadevops/connectors-operator/commit/00fbb705a0a71e01a0506cbec45c5dfaddc78061)
+- **Source commit**: [a87919a042d0dbaa33c7e409178f7935f6dd9777](https://github.com/alaudadevops/connectors-operator/commit/a87919a042d0dbaa33c7e409178f7935f6dd9777)
 - **Triggered by**: chengjingtao
-- **Workflow run**: [#50](https://github.com/alaudadevops/connectors-operator/actions/runs/19294174445)
+- **Workflow run**: [#51](https://github.com/alaudadevops/connectors-operator/actions/runs/19463897226)
 
 ## Files synced:
 - docs/

docs/en/connectors/architecture/index.mdx

@@ -31,14 +31,13 @@ For example, a `Harbor ConnectorClass` can be defined to support integration wit
 
 ## Connectors Proxy
 
-`ConnectorsProxy` is a core component that provides secure, secretless access to integrated tools within Kubernetes clusters. It acts as a proxy server, handling authentication injection and request routing to target tool.
+`Connectors Proxy` is a core capability of the Connectors system that provides secure, secretless access to integrated tools. It typically operates as an HTTP service that can function as either a forward proxy or a reverse proxy for client applications.
 
-`ConnectorsProxy` enables clients to access tool resources without direct credential handling. This approach delivers significant security benefits:
+When clients access tool resources through `Connectors Proxy`, the proxy automatically injects the necessary authentication credentials into requests, enabling seamless access without requiring clients to handle credentials directly. This approach delivers a significant security benefit:
 
-- **Secretless Access**: Eliminates the need to distribute tool credentials directly to clients by using short-lived tokens issued by ServiceAccount. This prevents credential exposure in clients like logs or environment variables.
-- **Centralized Credential Management**: All tool credentials are managed centrally by connectors, and no need to distribute credentials to each client.
+- **Secretless Access**: Eliminates the need to distribute tool credentials directly to clients by using short-lived tokens issued by Kubernetes. This prevents credential exposure in client environments such as logs or environment variables.
 
-The platform supports both built-in and custom proxy implementations to accommodate diverse tool authentication requirements.
+To accommodate diverse tool authentication requirements, the platform supports both built-in and custom proxy implementations. Each `ConnectorClass` can provide its own proxy service, offering flexibility to meet specific tool authentication needs.
 
 ### Built-in Connectors Proxy
 

docs/en/connectors/concepts/connectorclass.mdx

@@ -357,7 +357,7 @@ The above YAML demonstrates basic authentication validation:
 - `path`: Uses the `repository` value from the Connector's `auth.params`, constructing the path as `/<repository>/info/refs?service=git-upload-pack`
 - `Authorization`: When the Connector is configured with a Secret, the `username` and `password` fields are Base64-encoded and included in the Basic authentication header.
 
-### Rego-based Authentication Logic Configuration
+### Rego-based Authentication Logic Configuration \{#rego-based-authentication-logic-configuration}
 
 When tool connectors require more complex authentication logic, you can use Rego-based authentication logic configuration.
 
@@ -713,11 +713,79 @@ spec:
       kind: Service
       name: proxy
       namespace: default
-    uri: https://proxy.example.com
+    # uri: https://proxy.example.com
 ```
 
 The Connector will use the proxy address to proxy the request to the ConnectorClass. [More information](./connectors_proxy.mdx)
 
+### Using Rego to extract token from request \{#using-rego-to-extract-token-from-request}
+
+When using the built-in reverse proxy, you can configure Rego rules using `spec.proxy.authExtractor` to extract tokens from client requests, enabling the built-in reverse proxy to validate client authentication using the extracted token.
+
+For example:
+
+```yaml
+spec:
+  proxy:
+    authExtractor:
+      rego: |
+        package proxy
+        auth = {
+          "token": input.headers["Private-Token"][0]
+        }
+```
+
+Rego rules must follow these requirements:
+
+- Rules must be defined in the `proxy` package
+- Use the `auth` variable to return the token, where the token is a string type, for example: `auth = { "token": "abcd1234" }`
+- If the token cannot be extracted, return an empty string, for example: `auth = { "token": "" }`
+
+The following variables are available in Rego:
+
+| key     | type                | description                                                        | Example                     |
+| ------- | ------------------- | ------------------------------------------------------------------ | --------------------------- |
+| headers | map[string][]string | Headers of the request sent to the built-in reverse proxy          | input.headers["X-Token"][0] |
+| body    | object              | Body of the request sent to the built-in reverse proxy             | input.body.token            |
+| query   | map[string][]string | Query parameters of the request sent to the built-in reverse proxy | input.query["token"][0]     |
+| method  | string              | HTTP method of the request sent to the built-in reverse proxy      | input.method                |
+| path    | string              | Path of the request sent to the built-in reverse proxy             | input.path                  |
+
+**Notes**:
+
+- Header keys in `headers` use Canonical MIME Header Key format (capitalized first letter)
+- When implementing Rego rules, ensure robust logic. For example, return an empty string when `input.headers` is null or empty.
+
+**Example**
+
+``` yaml
+spec:
+  proxy:
+    authExtractor:
+      rego: |
+        package proxy
+
+        default auth = {
+          "token": ""
+        }
+
+        auth = {
+          "token": input.headers["Private-Token"][0]
+        } if {
+          input.headers != null
+          input.headers["Private-Token"] != null
+          count(input.headers["Private-Token"]) > 0
+        }
+```
+
+This example demonstrates robust token extraction by:
+- Defining a default rule that returns an empty token string
+- Checking that headers exist and are not null before accessing them
+- Verifying that the specific header key exists and has at least one value
+
+For more advanced Rego rules, see the [Rego Policy Language](https://www.openpolicyagent.org/docs/latest/policy-language) documentation.
+For more information about using the built-in reverse proxy, see [Connectors Proxy](./connectors_proxy.mdx).
+
 ### Resolver Type
 
 The proxy address of the ConnectorClass will be resolved according to the specified `resolver` type. 

docs/en/connectors/concepts/connectors_proxy.mdx

@@ -7,14 +7,13 @@ sourceSHA: a3690e0a66ff0d323093db716163521315b340274eb2dbec21ada430d120870d
 
 # ConnectorsProxy
 
-`ConnectorsProxy` is a core component that provides secure, secretless access to integrated tools within Kubernetes clusters. It acts as a proxy server, handling authentication injection and request routing to target tool.
+`Connectors Proxy` is a core capability of the Connectors system that provides secure, secretless access to integrated tools. It typically operates as an HTTP service that can function as either a forward proxy or a reverse proxy for client applications.
 
-`ConnectorsProxy` enables clients to access tool resources without direct credential handling. This approach delivers significant security benefits:
+When clients access tool resources through `Connectors Proxy`, the proxy automatically injects the necessary authentication credentials into requests, enabling seamless access without requiring clients to handle credentials directly. This approach delivers a significant security benefit:
 
-- **Secretless Access**: Eliminates the need to distribute tool credentials directly to clients by using short-lived tokens issued by ServiceAccount. This prevents credential exposure in clients like logs or environment variables.
-- **Centralized Credential Management**: All tool credentials are managed centrally by connectors, and no need to distribute credentials to each client.
+- **Secretless Access**: Eliminates the need to distribute tool credentials directly to clients by using short-lived tokens issued by Kubernetes. This prevents credential exposure in client environments such as logs or environment variables.
 
-The platform supports both built-in and custom proxy implementations to accommodate diverse tool authentication requirements.
+To accommodate diverse tool authentication requirements, the platform supports both built-in and custom proxy implementations. Each `ConnectorClass` can provide its own proxy service, offering flexibility to meet specific tool authentication needs.
 
 ## Built-in Connectors Proxy
 
@@ -34,7 +33,7 @@ Connectors Proxy does not support the `CONNECT` method for `HTTP tunneling`. Cli
 
 :::
 
-### Reverse Proxy
+### Reverse Proxy \{#reverse-proxy}
 
 Clients access tools by connecting directly to the Connector Proxy Address instead of the original tool URL. The proxy:
 
@@ -190,6 +189,33 @@ Example:
 curl -H "Authorization: Bearer sa-token-xxxxxxx" "http://c-github.default.svc.cluster.local/"
 ```
 
+#### Custom Rego-based Authentication \{#custom-rego-based-authentication}
+
+When using the built-in HTTP reverse proxy with tools that use non-standard authentication methods, clients may be unable to provide tokens using standard Basic Auth or Bearer Token methods. Instead, they must use the tool's original credential format.
+
+To support these custom authentication formats, you can use Rego rules to customize token extraction from client requests. This allows the built-in HTTP reverse proxy to extract and validate tokens regardless of how they are provided by the client.
+
+For example:
+
+```yaml
+spec:
+  proxy:
+    authExtractor:
+      rego: |
+        package proxy
+        auth = {
+          "token": input.headers["Private-Token"][0]
+        }
+```
+
+This configuration extracts the token from the `Private-Token` header in client requests, which the proxy then uses to validate client authentication.
+
+This approach provides significant flexibility for non-standard HTTP authentication mechanisms. Client CLIs can provide Kubernetes tokens using the tool's original credential format, and the proxy extracts the token through Rego rules to complete authentication validation.
+
+For more detailed configuration on using Rego rules to extract tokens, see [ConnectorClass](./connectorclass.mdx#using-rego-to-extract-token-from-request).
+
+For more about injecting authentication credentials into backend request, see [Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy](#injecting-authentication-when-using-built-in-reverse-proxy).
+
 ##### Connector Identification
 
 The connector can be identified through different proxy address formats:
@@ -215,6 +241,50 @@ curl -u ":sa-token-xxxxxxx" \
 
 The proxy will validate the authentication token and automatically inject the `default/github` connector's authentication credentials when forwarding requests to GitHub services.
 
+### Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy \{#injecting-authentication-when-using-built-in-reverse-proxy}
+
+After the built-in reverse proxy validates the client request, it injects authentication credentials into the backend request based on the credential type configured in the Connector. The following injection methods are supported:
+
+- **Basic Auth**
+- **Bearer Token**
+- **Custom Rego**
+
+#### Basic Auth
+
+When a Connector is configured with the secret type `kubernetes.io/basic-auth`, the proxy injects the credentials into the backend request headers using Basic Authentication.
+
+#### Bearer Token
+
+When a Connector is configured with the secret type `connectors.cpaas.io/bearer-token`, the proxy injects the credentials into the backend request headers using Bearer Token authentication.
+
+#### Custom Rego
+
+In addition to the standard Basic Auth and Bearer Token methods, you can use Rego rules to define custom authentication injection logic. For example:
+
+```yaml
+spec:
+  auth:
+    types:
+    - name: rego-auth
+      secretType: Opaque
+      generator:
+        rego: |
+          package proxy
+          auth = {
+            "position": "header",
+            "auth": {
+              "Private-Token": input.token
+            }
+          }
+```
+This configuration injects the token value from the connector's secret data into the `Private-Token` header of backend requests.
+
+For more detailed configuration, see [ConnectorClass](./connectorclass.mdx#rego-based-authentication-logic-configuration).
+
+When using custom Rego authentication, you typically need to configure `spec.proxy.authExtractor` to extract tokens from client requests, enabling the built-in HTTP reverse proxy to validate client authentication.
+Simultaneously, use `spec.auth.types[].generator.rego` to inject authentication credentials into backend requests.
+This combination enables support for custom authentication mechanisms when using the built-in HTTP reverse proxy.
+
 ## References
 
 - [Kubernetes Authentication documentation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens)

docs/en/overview/release_notes.mdx

@@ -37,6 +37,9 @@ The following table shows the compatibility and support matrix between the Alaud
   - [NPM Connector Quick Start](../connectors-npm/quick_start.mdx)
 - Support accessing tool's original API through the Connector API when the ConnectorClass provides Proxy Service capabilities. The system now supports two ways to access tool resources: using the tool's original API via Proxy Service, or using custom APIs provided for the ConnectorClass. For more details, see
   * [Connector API](../connectors/concepts/connector_api.mdx)
+- Support using Rego rules to extract tokens from client requests when using the built-in HTTP reverse proxy. Combined with the existing ability to inject authentication credentials into backend requests through Rego rules, you can now extend the built-in reverse proxy's capabilities to support tools with non-standard HTTP authentication mechanisms.
+  - For token extraction configuration, see [Custom Rego-based Authentication](../connectors/concepts/connectors_proxy.mdx#custom-rego-based-authentication).
+  - For authentication injection configuration, see [Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy](../connectors/concepts/connectors_proxy.mdx#injecting-authentication-when-using-built-in-reverse-proxy).
 
 ### Breaking Changes