Integrations¶
This page is for the owner of an external system that must cross the gdsgate boundary. Each recipe names the two systems, supported version evidence, command host, secret boundary, positive proof, nearest denial, recovery, cleanup, and next link. The deployment owner supplies endpoints and credentials; this page does not invent a public URL or hosted console.
The current gdsgate release is the value printed by the supplied binary. Record that value beside each external client version. The split lab names authority-1, proxy-1, connector-1, lab-postgres, lab-read, lab-denied, and alice@example.test.
OIDC identity provider (Keycloak)¶
Systems: an OIDC provider, Authority, Proxy, and the client. Authority fetches the provider discovery document and JWKS, verifies issuer, audience, expiry, and an approved asymmetric signing algorithm, then maps sanitized groups to Cedar. HMAC signing is refused by the source validator.
This walkthrough is checked against the committed split fixture's Keycloak 26.0 image on the 2026-08-20 review date. A deployment owner records the exact provider build and blocks an upgrade until discovery, login, group mapping, and signing-key rotation pass again.
Configure gdsgate¶
Actor: the Authority owner on the Authority host. The provider owner supplies the exact HTTPS issuer, client ID, discovery policy, and key refresh policy. Keep the issuer and any client secret out of a public config:
Expected result: Authority starts and can refresh discovery and JWKS. Positive proof is a successful device or browser login followed by a known principal in audit. The nearest negative is an issuer mismatch, unknown key ID, unsupported algorithm, wrong audience, or expired token. Recovery is to correct the provider metadata or trust record and repeat login; do not disable signature checks. Cleanup removes retired client metadata and lets cached identities expire.
Configure the Keycloak client¶
Actor: the identity-provider owner. Register a public client for Authorization Code with PKCE and Device Authorization when the deployment supports those flows. Redirect the PKCE loopback only to the local loopback address, and keep the audience equal to the configured client ID unless the deployment explicitly pins another audience. Do not enable a password grant as the default human or CI path.
Expected result: gdsgate login completes the device flow and login --browser completes PKCE. The nearest negative is a redirect, audience, or issuer mismatch. Fix the provider registration and retry. Cleanup removes unused redirects and revoked clients.
For signing-key rotation, publish the new asymmetric key in JWKS before using it, keep the old verification key through the accepted-token overlap, and wait for Authority's documented JWKS refresh. Prove a new login under the new key and the intended expiry behavior of an old token before retiring the old key. An unknown key ID must fail closed; do not recover by enabling HMAC or skipping signature verification.
Emit a groups claim¶
The provider must emit a groups claim whose values are sanitized names, not paths containing an unreviewed control prefix. Authority maps the claim to Cedar Group entities. Positive proof is an audit principal with the expected group and a policy view decision. The nearest negative is a missing, duplicated, or reserved group; the login may authenticate but policy must not elevate it. Recovery is a provider claim-mapping change and a fresh token. Cleanup removes stale group mappings.
Map groups to access with Cedar¶
Actor: the policy author on the admin host. Use typed permits for view, connect, and request-aware actions:
permit (principal in Group::"lab-readers",
action == Action::"view",
resource == Database::"lab-read");
permit (principal in Group::"lab-readers",
action == Action::"connect",
resource == Database::"lab-read");
Expected result: the intended group can see and connect to lab-read. The nearest negative is lab-denied or a principal outside the group. Verify both decisions and the catalog row. Cleanup is policy removal through the versioned workflow. Next: Policy.
Headless tokens (CI, scripts)¶
A workload or CI job may receive an identity token through its platform's protected mechanism. Put it in an environment variable only for the process that needs it:
The issuer owner must define TTL, audience, claim names, and rotation. The nearest negative is an expired token or an issuer claim that is not accepted; the gateway denies before a backend dial. Recovery is a fresh token or workload identity. Cleanup unsets the variable, removes temporary files, and does not print the token. Next: workload identity.
Native clients per protocol¶
Systems: the gdsgate client and one native protocol client. The client host runs the gdsgate relay and the native tool. The Connector owner configures the backend and its allow-list. For every recipe, keep the generated fragment or loopback relay owner-only.
ssh (OpenSSH)¶
Generate one fragment and include it before matching host entries:
SSH_FRAGMENT="${SSH_FRAGMENT:-./gdsgate-ssh-fragment.conf}"
SSH_CONFIG="${SSH_CONFIG:-$SSH_FRAGMENT}"
gdsgate --config "$CLIENT_CONFIG" ssh-config '*.gds' > "$SSH_FRAGMENT"
ssh -F "$SSH_CONFIG" user@RESOURCE_NAME
The defaults pass the generated fragment directly to the native client. If an
owner-controlled SSH configuration includes that fragment instead, set
SSH_CONFIG to the including file before running the command.
Expected result: a native SSH session with a connect decision and session close. The nearest negative is a host-key mismatch, forward denial, or Cedar connect denial. Keep those boundaries separate. Recovery is a verified host key, a narrower forward, or a policy review. Cleanup closes SSH and removes stale generated fragments. See User guide.
psql / mysql¶
Actor: a database client owner. The Connector owner configures the database backend and optional per-statement policy. On the client host:
gdsgate --config "$CLIENT_CONFIG" db proxy lab-read --listen 127.0.0.1:5433 &
DB_PID=$!
trap 'kill "$DB_PID" 2>/dev/null || true' EXIT
psql -h 127.0.0.1 -p 5433 -c 'select count(*) from lab_table;'
Expected result in the split lab is count 3. Positive evidence is the query result, connect row, and optional dbQuery row. The nearest negative is lab-denied, which must fail before the backend connection, or a write rejected by dbQuery. Recovery is a typed grant or corrected resource ID. Cleanup stops the relay and removes any temporary client config. The Connector backend kind cockroach uses PostgreSQL wire behavior but is catalogued as postgres.
kubectl¶
Systems: gdsgate Kubernetes proxy and the deployment's pinned kubectl version. The current documented upgrade path is kubectl 1.30 or newer; record the exact client version and review it with the Connector owner. The client host creates the exec credential and local proxy:
KUBECONFIG="${KUBECONFIG:-./gdsgate-kubeconfig.yaml}"
gdsgate --config "$CLIENT_CONFIG" kube login KUBE_RESOURCE > "$KUBECONFIG"
gdsgate --config "$CLIENT_CONFIG" kube proxy KUBE_RESOURCE --listen 127.0.0.1:6443 &
KUBE_PID=$!
trap 'kill "$KUBE_PID" 2>/dev/null || true' EXIT
kubectl --kubeconfig "$KUBECONFIG" get --raw=/version
Expected result: each call obtains a short-lived exec credential and reaches the intended API. kubeRequest is evaluated per request and can narrow verb, resource kind, namespace, name, subresource, and marker. Positive evidence is the API response plus the request and session audit rows. The nearest negative is a disallowed request, which returns 403 before the backend request. Port-forward is refused unless allow_port_forward is explicitly enabled; an enabled port-forward is an opaque audited byte channel, not a typed replay. Exec and attach have their own upgrade and recording limits. Recovery is one narrow request or a step-up. Cleanup stops the proxy, removes temporary kubeconfig files, and lets credentials expire.
redis-cli and other TCP clients¶
A TCP integration is an opaque byte relay. It does not claim to parse or authorize an arbitrary application protocol:
gdsgate --config "$CLIENT_CONFIG" tcp proxy RESOURCE_NAME --listen 127.0.0.1:6390 &
TCP_PID=$!
trap 'kill "$TCP_PID" 2>/dev/null || true' EXIT
redis-cli -p 6390 ping
Expected result is the native response and connect/byte audit evidence. The nearest negative is a connect denial before any downstream dial. Recovery is a typed policy grant or corrected ID. Cleanup stops the relay.
MCP clients¶
The Connector owner supplies a static allowed_tools list. Set enforce_tool_policy when Cedar must decide each tool, resource, and prompt:
[[connector.backends]]
resource = "tools-dev"
kind = "mcp"
allowed_tools = ["search"]
enforce_tool_policy = true
The client host starts the local proxy and, for a stdio-only client, bridge:
gdsgate --config "$CLIENT_CONFIG" mcp proxy tools-dev --listen 127.0.0.1:8765 &
MCP_PID=$!
trap 'kill "$MCP_PID" 2>/dev/null || true' EXIT
gdsgate mcp bridge 127.0.0.1:8765
Expected result: tools/list is filtered by viewTools and an allowed search call returns a JSON-RPC result. Positive evidence is the result and the matching MCP audit row. The nearest negative is an unlisted or policy-denied tool, resource, or prompt; it must fail before the backend call. Recovery is a narrower allow-list, Cedar rule, or step-up. Cleanup stops the proxy and removes client endpoint files.
CI pipelines¶
Systems: a CI runner, gdsgate client, and native tool. The CI owner supplies a short-lived issuer token and transport trust. The job host runs all commands; Authority and the Connector remain in their deployment zones:
export GDSGATE_ID_TOKEN="$CI_ID_TOKEN"
gdsgate --config "$CLIENT_CONFIG" db proxy lab-read --listen 127.0.0.1:5433 &
DB_PID=$!
trap 'kill "$DB_PID" 2>/dev/null || true' EXIT
psql -h 127.0.0.1 -p 5433 -c 'select count(*) from lab_table;'
Expected result is the lab count 3, the job principal in audit, and a closed relay. The nearest negative is an expired token or policy denial. Recovery is a fresh short-lived token or a reviewed workload identity. Cleanup kills the relay, unsets the token, and removes temporary trust/config files. Keep CI groups separate from human groups and request only the native operation needed. Next: workload identity.
Workload identity (CI and services)¶
Systems: a workload issuer, Authority enrollment, and the service or CI host. The host generates the keypair locally; the private key never leaves it. Provision-token workloads use the external revocation key configured for audit:
The issuer contract must provide a numeric project_id claim and a hexadecimal sha claim when those fields are used to build an identity. Do not interpolate raw project or ref names containing slash or dot segments into a workload ID. The issuer owner pins the claims schema, issuer version, owner, and review date.
Bootstrap on the workload host with the platform token or a one-time provision token, according to the deployment's approved path:
Expected result: a short-lived workload certificate and local keypair. Positive evidence is gdsgate doctor, a typed resource operation, and the workload principal in audit. The nearest negative is a missing revocation key, invalid claim component, replayed provision token, or revoked workload; all fail closed. Recovery is a fresh issuer token or an administrator-issued token after review. Cleanup unsets the token, expires/revokes the workload, and removes the local key after retention.
Token-less renewal is allowed only for provision-token workloads with a still valid certificate and proof of possession:
The nearest negative is an expired or revoked certificate. Rebootstrap instead of attempting to renew an expired identity. Next: Policy workload rules.
Delegated agents (autonomous access)¶
Use the AI agent guide for the complete threat model. The integration boundary is the owner, gdsgate delegation, the agent wrapper, and the external model/MCP systems. Verify the profile's external version, configuration shape, owner, source, and review date before launch:
gdsgate --config "$CLIENT_CONFIG" delegate \
--can mcp:search@tools-dev \
--can llm:call@models-dev \
--ttl 900 --sandbox strict --model gateway \
--agent-profile PROFILE_NAME \
--exec ./agent-wrapper -- --single-search-and-single-model-call
Expected result: one allowed search, one allowed test-small model call, and revocation on wrapper exit. Positive evidence is delegation.create, sandbox.claim, the two operation rows, and a close event. The nearest negative is an unlisted tool/model or direct model mode under a cage. Recovery is a narrower delegation or policy review. Cleanup is automatic for exec; a bind-key bundle needs explicit revoke and owner-only deletion.
Observability and SIEM¶
These are separate integrations with separate owners:
| Stream | Source and boundary | Positive proof | Nearest failure |
|---|---|---|---|
| stderr logs | process decisions and degradation | operation ID and reason | missing log destination |
| metrics | counters and gauges | metrics endpoint or scrape | role not listening |
| health/readiness | role-specific listener state | health and ready response | Connector ready before tunnel |
| OTLP traces | optional spans, configured exporter | trace ID joins request | exporter unavailable |
| audit JSONL | append-only local/export stream | hash-chain verification | missing anchor or tamper |
| SIEM shipper | external transport and retention | delivered event with ID | transport/replay failure |
The command host for local checks is the role host. Use the deployment's configured metrics/health listener and keep it inside the intended zone. A ready Connector does not prove an active Authority tunnel. Verify the durable chain off-band from a separate workstation whose configuration opens the audit store directly and names the anchor key:
Expected result is a chain and anchor summary. The nearest negative is a missing anchor, stale export, or health success with no tunnel. Recovery follows the owner's store/export procedure; do not turn off audit or substitute a metric. Cleanup removes temporary export files after delivery confirmation.
Backend kinds¶
The Connector backend inventory is exactly ten kinds:
| Backend kind | Catalog/resource behavior | Gate boundary |
|---|---|---|
| ssh | SshHost | connect, forwarding, optional onward certificate |
| tcp | TcpService | connect and opaque bytes |
| postgres | Database | connect and optional dbQuery |
| mysql | Database | connect and optional dbQuery |
| cockroach | advertised as postgres | PostgreSQL wire/session-role path |
| mcp | McpServer and subresources | connect, viewTools, tool/resource/prompt actions |
| kubernetes | KubernetesCluster | connect and per-request kubeRequest |
| llm | LlmService and LlmModel | per-call llmCall, no connect session |
| web | WebApp | connect and per-request httpRequest |
| web-egress | WebEgress | policy-controlled forward/CONNECT lane |
The catalog has nine resource kinds because cockroach is a backend engine label, not a separate catalog kind. web and web-egress are distinct. TCP is opaque. MCP static allow-lists remain available when Cedar per-tool enforcement is off.
Compatibility record.
Pin the external release and assign an owner before enabling each recipe:
| Boundary | Version or specification to record | Owner | Review date |
|---|---|---|---|
| Keycloak lab provider | 26.0 image; OIDC Discovery 1.0, PKCE, device flow, and JWKS rotation | identity owner | 2026-08-20 |
| OpenSSH client | exact ssh -V; generated config, host-key, SFTP, and forwarding checks |
access owner | 2026-08-20 |
| PostgreSQL fixture and client | PostgreSQL 16 fixture plus exact psql --version and TLS mode |
data owner | 2026-08-20 |
| MySQL client | exact mysql --version, authentication plugin, and TLS mode |
data owner | 2026-08-20 |
| Kubernetes client | exact kubectl version, current path tested at 1.30+ | cluster owner | 2026-08-20 |
| Redis fixture and client | Redis 7 fixture plus exact redis-cli --version |
service owner | 2026-08-20 |
| MCP client | protocol revision and transport | tool owner | 2026-08-20 |
| CI issuer | claim schema including project_id and sha | CI owner | 2026-08-20 |
| Telemetry exporter | OTLP protocol and endpoint policy | observability owner | 2026-08-20 |
If a version, owner, or review date is unknown, mark the integration blocked and ask the owner. Do not replace a missing source fact with a public URL, token, or unsupported acquisition path.