Doc: Provide a developer doc for using CLI tools such as "grpcurl" to test

[esnible]

Provide a few examples of using CLI tools such as grpcurl to test the ext-proc.

It might be better to implement #338 first, so this documentation can be small.

It might be valuable to be able to run the various AuthBridge components locally so that developers can use their favorite debugging tools. It might be good to provide a sample AuthBridge config file for spiffe://prod.acme.com/billing/api so that new developers can try out modifications to the AuthBridge code without building and pushing a new sidecar image and starting an agent to induce the Kagenti Operator to attach the new code to a running Agent.

This is what I tried to run locally:

export KEYCLOAK_URL=http://keycloak.localtest.me:8080
export KEYCLOAK_REALM=kagenti
export TOKEN_URL=$(curl --silent ${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/.well-known/openid-configuration | jq --raw-output ".token_endpoint")
export DEFAULT_OUTBOUND_POLICY=passthrough
export CLIENT_ID=spiffe://localtest.me/sa/kagenti-example-client

go run ./cmd/authbridge/main.go -config authproxy/authbridge-combined.yaml

I couldn't find any other config files, and this one was insufficient -- it wanted a socket_path or jwt_svid_path, and as a new dev I couldn't figure out how to supply them.

[esnible]

To get a config file easily for local testing:

oc -n team1 exec -it git-issue-agent-69cb95986c-6dj8h -c envoy-proxy -- cat /etc/authbridge/config.yaml > /tmp/authbridge-config.yaml

go run ./cmd/authbridge/main.go --config /tmp/authbridge-config.yaml

The config file looks like this:

mode: envoy-sidecar
inbound:
  issuer: "http://keycloak.localtest.me:8080/realms/kagenti"
outbound:
  keycloak_url: "http://keycloak-service.keycloak.svc:8080"
  keycloak_realm: "kagenti"
  default_policy: "passthrough"
identity:
  # Map Helm clientAuthType to authbridge identity.type:
  #   "client-secret"  → "client-secret" (traditional)
  #   "federated-jwt"  → "spiffe" (SPIFFE JWT-SVID authentication)
  type: "client-secret"
  client_id_file: "/shared/client-id.txt"
  client_secret_file: "/shared/client-secret.txt"
bypass:
  inbound_paths:
    - "/.well-known/*"
    - "/healthz"
    - "/readyz"
    - "/livez"

[esnible]

Notes:

Now that the gRPC reflection API is merged, we can do grpcurl --plaintext localhost:9090 list.

We can also do

EXT_REQ='{"requestHeaders":{"headers":{"headers":[{"key":":authority", "rawValue":"bXktd2VhdGhlci1zZXJ2aWNlLXdpdGgtYXV0aGJyaWRnZS50ZWFtMS5zdmMuY2x1c3Rlci5sb2NhbDo4MDgw"}, {"key":":path", "rawValue":"Ly53ZWxsLWtub3duL2FnZW50LWNhcmQuanNvbg=="}, {"key":":method", "rawValue":"R0VU"}, {"key":":scheme", "rawValue":"aHR0cA=="}, {"key":"user-agent", "rawValue":"R28taHR0cC1jbGllbnQvMS4x"}, {"key":"accept", "rawValue":"YXBwbGljYXRpb24vanNvbg=="}, {"key":"accept-encoding", "rawValue":"Z3ppcA=="}, {"key":"x-forwarded-proto", "rawValue":"aHR0cA=="}, {"key":"x-request-id", "rawValue":"ODEzYzliMmQtZDdkYS00NWZkLWIxMGItM2VlZWE4ODU2MTEw"}, {"key":"x-authbridge-direction", "rawValue":"aW5ib3VuZA=="}]}, "endOfStream":true}, "metadataContext":{}, "protocolConfig":{}}'

grpcurl -d ${EXT_REQ} -plaintext localhost:9090 envoy.service.ext_proc.v3.ExternalProcessor.Process

The purpose of this issue is to create a short doc for new devs and LLMs to see how to do this.

@huang195 I was very surprised that although the protobuf supports using value, AuthBridge's impl only supports using rawValue in base64. Would it be worthwhile to fix the code to accept either?