Run a Connect server
Control Center Connect runs provider sign-ins (GitHub, Google Calendar, Linear, Slack) for servers that have not registered apps of their own. This guide shows you how to run your own Connect, so the provider apps, their secrets and the list of servers allowed to use them all stay with you.
What Connect can and cannot see is in the Connect reference. Read it first if you are deciding whether to run one.
Prerequisites
Section titled “Prerequisites”- A public HTTPS address for Connect, such as
https://connect.example.com, behind a TLS-terminating proxy. Plainhttpis accepted on loopback only - Docker, or a
cc_serveryou can restart with extra environment variables - Permission to register apps with each provider you want to serve
- The servers that will use it, with their owners at hand: each one has an install id you add to Connect’s allowlist
Step 1: Choose the address
Section titled “Step 1: Choose the address”Pick the URL now and keep it. CONNECT_PUBLIC_URL is part of everything Connect
does: request signatures, sealed credentials, provider redirect URLs and each
server’s install id are all bound to it. Changing it later means registering the
redirects again and every person signing in again.
Step 2: Register the provider apps
Section titled “Step 2: Register the provider apps”Register only the providers you want to serve. A provider whose variables are
incomplete is left out of Connect’s configuration, and servers see it as
unavailable. <base> below is your CONNECT_PUBLIC_URL.
| Provider | Register | Keep |
|---|---|---|
| GitHub App | Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup with Redirect on update on. Leave Request user authorization (OAuth) during installation off: with it on, GitHub ignores the setup URL. Keep Expire user authorization tokens on |
App id, slug, client id, client secret, a private key |
An OAuth client of type Web application with redirect URI <base>/oauth/google/callback, and the Google Calendar API enabled |
Client id, client secret | |
| Linear | An OAuth application with callback URLs <base>/oauth/linear/callback and <base>/oauth/linear_app/callback |
Client id only |
| Slack | Redirect URLs <base>/oauth/slack_oidc/callback and <base>/oauth/slack/callback. Event Subscriptions at <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash commands at <base>/v1/hooks/slack/commands. Token rotation on |
App id, client id, client secret, signing secret |
Give the GitHub App these repository permissions: Metadata read, Contents read and write, Pull requests read and write, Issues read and write, Checks, Actions and Commit statuses read. Add organization Members read for team review requests. Webhooks can stay off: servers poll.
Connect needs the GitHub App’s private key (Generate a private key in the App’s settings). It signs the App’s requests that find the installation covering a repository (or, when the repository has none, the owner’s installation) and mint a one-repository installation token, each only after the asking person’s own sign-in proved access to that repository.
Every server on your Connect shares the App’s bot. It may read, comment, label
and react as the bot for any of them. Reviewing pull requests as the bot is
allowed only for the servers you list in CONNECT_GITHUB_REVIEW_BOT_INSTALLS
(their install ids, comma-separated); every other server publishes reviews on
the reviewer’s own token. Pushing is never done as the bot. To let a server of
your own review as the bot, add its install id there and restart. Keep the key file
as a secret, like the seal key. Linear needs no secret: Connect hands the code
back to the server, which finishes the exchange itself.
Step 3: Collect the install ids
Section titled “Step 3: Collect the install ids”Connect answers only the servers on its allowlist. On each server, point it at your Connect, then read its install id:
- Go to Settings → Server → Single sign-on, open the Control Center Connect card and choose Use a custom Connect server
- Enter your URL and save. The card shows the server’s Install id
From a terminal on the server host, the same thing is:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus prints the install id. It shows install_blocked until Step 5 is done,
which is expected.
An install id is derived per Connect address, so the same server has a different id for every Connect it talks to. It changes only when its owner rotates the key.
Step 4: Create a seal key
Section titled “Step 4: Create a seal key”Connect encrypts every credential it hands back with a seal key. Make one and keep it as a secret file:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysLosing the seal key signs everybody out: no seal can be opened without it.
Step 5: Start the container
Section titled “Step 5: Start the container”Every release publishes ghcr.io/samuelalev/cc-connect with build provenance.
Pin a version tag in production.
docker run -d --name cc-connect -p 8790:8790 \ -e CONNECT_PUBLIC_URL=https://connect.example.com \ -e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \ -e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \ -v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \ -e CONNECT_GITHUB_APP_ID=123456 \ -e CONNECT_GITHUB_APP_SLUG=acme-control-center \ -e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \ -e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \ -v "$PWD/github_secret:/run/secrets/github:ro" \ -e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \ -v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \ -v cc-connect-data:/data \ ghcr.io/samuelalev/cc-connect:latestPoint your reverse proxy at port 8790, and set CONNECT_TRUST_PROXY to the
number of proxies in front of Connect so its per-address limit sees each
client’s address. The image runs as an unprivileged user, keeps its state in the
/data volume and has a built-in health check (cc-connect --healthcheck,
which probes /healthz: the process answers). /readyz also checks that its
state and binding stores answer and that Redis, when used, still runs
maxmemory-policy noeviction; point an orchestrator’s readiness check there.
The sign-in consent page answers with a form post that Connect accepts only
from its own page: Sec-Fetch-Site, when sent, must be same-origin, and
Origin, when sent, must be the origin of CONNECT_PUBLIC_URL; a post with
neither is refused. So the proxy must pass both headers through unchanged, and
CONNECT_PUBLIC_URL must be the address people’s browsers actually use. If
continuing on that page always shows “This link has expired”, and the log shows
oauth.done_refused with reason origin or no_origin, one of those two is
off.
Connect refuses to start (exit code 78) when its configuration is open, unsafe
or half finished, and prints which variable is wrong. A missing allowlist, an
http address off loopback, a malformed seal key or both NAME and
NAME_FILE set all stop it.
Checkpoint: on each server, the Connect card reads Working, and Where each
sign-in runs names Connect for every provider you registered.
cc_server connect status prints Health: ok and the same lanes.
Mount Connect inside cc_server
Section titled “Mount Connect inside cc_server”A server can host Connect itself instead of a separate container. The mounted service is the same one the image runs.
- Put the
CONNECT_*variables in the server’s.envfile, as in Step 5. The server refuses to start when a Connect secret,CONNECT_SENTRY_DSNincluded, is exported in its environment - Add
CC_SERVER_CONNECT_HOST=on - Restart the server. Its log prints
embedded Connect at <url>
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_GITHUB_CLIENT_SECRET=<secret>CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pemConnect is then served at <server>/connect:
CONNECT_PUBLIC_URLdefaults to the server’s public URL origin plus/connect. Set it explicitly behind a proxy. Its path must be exactly/connect, and it must be HTTPS unless it is loopback- Only
CONNECT_*variables reach the mounted service, so it never borrows the server’s own provider apps CONNECT_ALLOWED_INSTALLSis still required, including for the hosting server itself- A misconfigured mount stops the server from booting rather than serving an open broker
- The demo server never mounts it
Register the provider redirects against https://<server>/connect, then point
servers (the hosting one included) at that URL as in Step 3.
Configuration reference
Section titled “Configuration reference”Every setting is an environment variable. Any secret can come from a mounted
file instead: set NAME_FILE in place of NAME. Connect re-reads the file at
most every 30 seconds and keeps the last good value. Secrets marked dual also
accept NAME_PREVIOUS (or NAME_PREVIOUS_FILE) during a rotation.
Address and access
Section titled “Address and access”| Variable | Default | Meaning |
|---|---|---|
CONNECT_PUBLIC_URL |
required | The canonical public URL. HTTPS, or http on loopback only. A path means a mount. No query or fragment |
CONNECT_ALLOWED_INSTALLS |
required | Comma-separated install ids. * is accepted only together with CONNECT_SIGNED_CONFIG_FILE |
CONNECT_DENY_INSTALLS |
Install ids refused even when allowed | |
CONNECT_GITHUB_ALLOWED_OWNERS |
Numeric GitHub owner ids. When set, repository tokens are minted only for repositories they own. It does not limit who signs in: a person allowed to use this Connect still receives their own App user token. To serve one organization only, keep the App private to it | |
CONNECT_GITHUB_REVIEW_BOT_INSTALLS |
Install ids that may have the App’s bot review pull requests. Empty by default; * is refused, and each id must also be allowed |
|
CONNECT_HOST, CONNECT_PORT |
0.0.0.0, 8790 |
Bind address and port |
CONNECT_TRUST_PROXY |
0 |
Trusted proxy hops in X-Forwarded-For (0 to 8). Used only for the per-address limits, the sign-in page’s network hint and the logged address. Behind a proxy, 0 counts every client as the proxy, and the log says so once |
Provider lanes
Section titled “Provider lanes”| Variable | Default | Meaning |
|---|---|---|
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID |
The GitHub App | |
CONNECT_GITHUB_CLIENT_SECRET |
Secret, dual | |
CONNECT_GITHUB_APP_PRIVATE_KEY |
Secret. The App’s private key (PEM) | |
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET |
The Google client. The secret is dual | |
CONNECT_LINEAR_CLIENT_ID |
The Linear application. No secret | |
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID |
The Slack app | |
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET |
Secrets, dual | |
CONNECT_KLIPY_APP_KEY |
Klipy GIF search key. Secret, dual | |
CONNECT_KLIPY_MODE |
proxy |
proxy keeps the key in Connect; key hands it to servers |
CONNECT_<LANE>_SECRET_GENERATION |
1 |
GitHub, Google and Slack: the generation recorded in new seals |
CONNECT_<LANE>_MIN_SEAL_GENERATION |
1 |
GitHub, Google and Slack: older seals must sign in again |
CONNECT_<LANE>_ACCEPTS_NEW |
true |
Every lane: false stops new sign-ins while existing ones keep refreshing |
Seals, state and storage
Section titled “Seals, state and storage”| Variable | Default | Meaning |
|---|---|---|
CONNECT_SEAL_BACKEND |
local |
local or gcp-kms |
CONNECT_SEAL_KEYS |
Secret, required for local. Comma-separated kid:key entries, newest first; older entries still decrypt |
|
CONNECT_KMS_KEY |
projects/…/locations/…/keyRings/…/cryptoKeys/…, required for gcp-kms |
|
CONNECT_STATE |
memory |
memory for one instance, redis for several. A full memory store refuses new sign-ins and requests rather than forget a live entry |
CONNECT_REDIS_URL |
Secret. redis:// or rediss://. Redis 6.2 or later with maxmemory-policy noeviction, both checked at startup |
|
CONNECT_REDIS_CA_FILE |
CA bundle for rediss:// |
|
CONNECT_BINDINGS |
file |
Where Slack team bindings live: file or firestore |
CONNECT_DATA_DIR |
data (/data in the image) |
Holds bindings.json. Locked by one Connect: a second one on the same directory does not start |
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE |
(default) database |
For CONNECT_BINDINGS=firestore. Connect does not start when Firestore does not answer |
Configuration, logs and limits
Section titled “Configuration, logs and limits”| Variable | Default | Meaning |
|---|---|---|
CONNECT_SIGNED_CONFIG_FILE |
An offline-signed configuration, served as is. Used by Control Center’s hosted Connect | |
CONNECT_CONFIG_PUBLIC_KEYS |
Keys the signed configuration must verify against | |
CONNECT_CONFIG_EPOCH |
1 |
The epoch of the configuration a self-hosted Connect generates |
CONNECT_LOG_HMAC_KEY |
random per process | Secret. Set it to keep the tags that stand in for install ids stable across restarts and instances |
CONNECT_SENTRY_DSN |
Secret. An https Sentry DSN that error lines are reported to: the error type, stack frames, route and request id, never a message, body or header | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
The Sentry environment |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
Reported by /v1/version |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
Requests per install |
CONNECT_RATE_IP_PER_MINUTE |
300 |
Requests per address (an IPv6 address counts per /64) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
Requests for the whole instance |
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE |
600 |
Slack event and command deliveries per address, counted apart from other requests |
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND |
100 |
Slack event and command deliveries for the whole instance |
CONNECT_RATE_SLACK_TEAM_PER_MINUTE |
600 |
Slack events per team |
CONNECT_RATE_KLIPY_PER_MINUTE |
120 |
GIF searches per install |
CONNECT_RATE_KLIPY_IP_PER_MINUTE |
240 |
GIF searches per address, across servers |
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES |
60 |
Sign-ins started per address |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR |
30 |
GitHub tokens issued per GitHub account on one server (sign-ins, refreshes, repository tokens) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
4 × the above (120) |
The same per GitHub account across all servers |
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR |
600 |
GitHub tokens issued per address |
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR |
500 |
New GitHub sign-ins for the whole app |
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR |
120 |
Bot tokens per server |
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR |
240 |
Bot tokens per asking GitHub account, across servers |
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR |
3000 |
Bot tokens for the whole app |
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR |
1500 |
Refreshes and repository tokens for the whole app. New sign-ins have their own limit above |
CONNECT_GITHUB_TOKEN_CAP_WARN |
10 |
Live repository tokens one GitHub account may hold before Connect logs a warning |
CONNECT_RATE_RETIRE_IP_PER_HOUR |
10 |
Install ids retired per address (per /48 for IPv6) |
A call past a limit is answered rate_limited. Servers retry later and never
sign anyone out for it.
Run more than one instance
Section titled “Run more than one instance”One instance with CONNECT_STATE=memory is enough for most organizations.
Several instances behind one address need CONNECT_STATE=redis and
CONNECT_BINDINGS=firestore, so a sign-in started on one instance can finish on
another and every instance sees the same Slack bindings and retired install
ids. A shared CONNECT_DATA_DIR does not work: the first Connect locks it. The
per-install, per-address and instance request limits are per instance; the
limits on sign-ins, GitHub tokens, bot tokens, GIF searches per address,
retirements and Slack teams are shared through the state store.
Rotate a provider secret
Section titled “Rotate a provider secret”Nobody is signed out:
- Create the new secret at the provider and keep the old one
- Move the old value to
NAME_PREVIOUS, put the new one inNAME, and raiseCONNECT_<LANE>_SECRET_GENERATION. Mounted files are picked up within 30 seconds - Wait for sign-ins to refresh, then delete the old secret at the provider and
remove
NAME_PREVIOUS
To rotate a seal key, put a new cc-connect-config seal-key entry first in
CONNECT_SEAL_KEYS and keep the old entry until its seals have refreshed.
Change an app
Section titled “Change an app”Servers remember the app and client ids your Connect announced the first time they used it. If you replace an app, every server’s Connect card shows Connect’s apps changed, and sign-ins through Connect pause until its owner presses Trust new apps. Tell server owners before you switch, so they know the prompt is yours.
Block a server
Section titled “Block a server”Add its install id to CONNECT_DENY_INSTALLS and restart. Its owner sees
“Connect has blocked this server’s install id. Contact whoever runs your Connect server.” and every Connect sign-in on it stops.
A server also retires its own old install id when its owner rotates the key. It proves the id is its own with one credential seal this Connect made for it, so only a server that signed someone in can retire an id. Connect keeps retired ids for good, so the old key and every seal made for it stop working, and releases the Slack workspaces bound to the old id. Tokens already handed out expire on their own: within 8 hours for a person’s, 1 hour for a bot’s. Connect holds at most 100,000 retired ids; past that, a rotation is refused and the log says so at error level.
Troubleshooting
Section titled “Troubleshooting”A server says Connect has blocked it
Section titled “A server says Connect has blocked it”Its install id is not in CONNECT_ALLOWED_INSTALLS, it is in
CONNECT_DENY_INSTALLS, or it was retired by a key rotation. The id changes
when its owner rotates the key; ask for the new one.
Every sign-in to one provider fails
Section titled “Every sign-in to one provider fails”One of its variables may be missing, so Connect left the lane out. Check the startup log and the tables above. GitHub needs all five of app id, slug, client id, client secret and private key; Google needs both client id and secret.
Sign-ins fail with a redirect mismatch
Section titled “Sign-ins fail with a redirect mismatch”The redirect registered with the provider does not match CONNECT_PUBLIC_URL
exactly. Compare scheme, host, port and the /connect path for a mounted
Connect.
Everybody had to sign in again
Section titled “Everybody had to sign in again”The seal key changed or was lost, a server rotated its key, or a server’s data was restored onto another machine. A sealed credential opens only for the install and Connect that created it.