Codumentor logo Codumentor

OAuth Plugin

Owns the OAuth 2.0 / OIDC connect flow for a Codumentor deployment: users connect an account from Settings, tokens are stored encrypted at rest, and they are refreshed in the background.

Google Workspace and GitHub both need this plugin loaded. Users connect Google from Settings → Extensions → Google Workspace (product picker, then Connect). GitHub is connected from Settings → Extensions → OAuth Accounts. Connecting requires the oauth:manage permission, which the built-in power_user and admin roles have.

Configuration

Load this plugin and each provider plugin. Provider plugins must use a lower priority than OAuth (3 vs 4).

plugins:
  - module: codumentor.plugins.oauth
    class: OAuthPlugin
    priority: 4
    args:
      enabled: true
      previous_jwt_secrets: []          # for key-rotation grace period
      state_ttl_seconds: 600

  - module: codumentor.plugins.github_oauth
    class: GitHubOAuthPlugin
    priority: 3
    args:
      client_id: ${GITHUB_OAUTH_CLIENT_ID}
      client_secret: ${GITHUB_OAUTH_CLIENT_SECRET}

  - module: codumentor.plugins.google_workspace
    class: GoogleWorkspacePlugin
    priority: 3
    args:
      client_id: ${GOOGLE_OAUTH_CLIENT_ID}
      client_secret: ${GOOGLE_OAUTH_CLIENT_SECRET}

Parameters

ParameterTypeDefaultDescription
enabledbooltrueMaster on/off.
previous_jwt_secretslist[]Previous auth.jwt_secret values, so tokens encrypted under an older key can still be decrypted after rotation.
state_ttl_secondsint600How long an in-progress connect flow stays valid (10 minutes).
data_dirstringagent.storage_dirOverride only if tokens should not live under the agent storage directory.

Set auth.jwt_secret so tokens are encrypted at rest (keyed off that secret). Without it the plugin still loads, but tokens cannot be stored securely.

For the browser redirect after Google consent, set api.external_url (and optionally api.trust_forwarded) so the callback URL is reachable. When unset, the plugin falls back to http://127.0.0.1:<port>/oauth/callback/<provider> (<port> is api.port, default 2638), which both GitHub and Google accept for local installs.

Register that callback at the IdP:

Using it

  1. Open Settings → Extensions.
  2. For Google: open Google Workspace, pick products and access levels, click Connect. For GitHub: open OAuth Accounts, pick GitHub, click Connect.
  3. Complete the provider's consent screen in the browser (or enter the device code GitHub shows).
  4. Later you can add scopes (broaden the grant) or disconnect (local delete plus a best-effort revoke at the provider).

If a tool needs a product you have not granted, it tells you to reconnect from Settings rather than calling the provider.

Tokens are per (user, provider, account). Two people in the same instance never share a grant. Refresh happens automatically before expiry.

See also