Skip to content

Version 1.1.8 ยท Last updated

Casdoor OAuth Resource Server

Casdoor configuration

Use the exact issuer https://auth.argusfa.com. Create distinct resources/audiences for the REST API and MCP. Configure access tokens with Casdoor's minimum one-hour lifetime. Signing must use an asymmetric algorithm allowed by Argus (RS256 by default), and Casdoor must publish OIDC Discovery and JWKS over HTTPS.

Create the public CLI application as admin/argus-cli with:

  • Authorization Code flow and PKCE S256;
  • no client secret;
  • the exact loopback redirect http://127.0.0.1:8765/callback (or the single configured replacement);
  • refresh-token issuance and rotation;
  • the API resource indicator/audience for the default login, and the distinct https://mcp.argusfa.com/mcp resource for auth login --interface mcp;
  • openid offline_access facts:read evidence:read audit:read licenses:read features:read argus:tools:public login scopes. These exact scopes are verified by release preflight;
  • https://www.argusfa.com/zh-CN/legal/terms/ as the Terms of Use URL;
  • the Agreement item visible and required for signup only, but hidden on the sign-in form;
  • an empty custom signup HTML field so the standard signup form, Agreement, and GitHub provider button remain available; and
  • a versioned footer disclosure that expressly covers continuing with GitHub and links the Terms, Privacy Notice, and Account Deletion Guide.

Casdoor fetches the Terms URL before rendering its agreement dialog. The website therefore returns Access-Control-Allow-Origin: https://auth.argusfa.com on the six legal routes only; do not use a wildcard origin or extend this CORS policy to the rest of the static site.

The current legal document version is 2026-09-03. The public documents are:

  • English: /en/legal/terms/, /en/legal/privacy/, and /en/legal/account-deletion/;
  • Simplified Chinese: /zh-CN/legal/terms/, /zh-CN/legal/privacy/, and /zh-CN/legal/account-deletion/.

Casdoor's standard username/password signup can enforce its Agreement checkbox. Its stock external-provider button redirects directly to GitHub and does not bind the checkbox state into an acceptance record. The versioned signup notice in the persistent legal footer therefore provides the required disclosure next to that route, but they are not a server-side, versioned clickwrap receipt. If a customer contract or jurisdiction requires proof of affirmative acceptance for GitHub registration, add an application-owned consent step and immutable acceptance record before enabling that market; do not describe the Casdoor footer alone as proof of consent.

Create a separate Casdoor management application for release inspection and put its Client ID and secret in the separate root-owned preflight secret directory as casdoor_management_client_id and casdoor_management_client_secret. Never put these credentials in the runtime secrets directory, .env.production, the CLI, or an image. The directory is mounted only into a one-off container; long-running API, MCP, worker, and beat services cannot read it. Production preflight uses HTTP Basic authentication against Casdoor's management API, refuses redirects so the credential cannot be forwarded to another origin, and requires the live admin/argus-cli application to expose exactly the release callback, only the authorization-code and refresh-token grants, and a one-hour access-token lifetime. It then submits the release Client ID, scopes, response type, and callback to the public login-contract endpoint. The release is rejected if either the stored application configuration or the authorization request differs. The same preflight also rejects missing or stale legal links, a non-required signup Agreement, an Agreement shown on ordinary sign-in, a custom HTML replacement of the standard signup form, or a missing versioned GitHub footer disclosure.

Disable DCR and pre-register the intended CLI, Claude, and ChatGPT clients. Their resource indicator must resolve to the API or MCP audience as applicable. The local Argus CLI/Python companion uses the same pre-registered public client and exact loopback callback for both resources; it performs a separate PKCE login for MCP and keeps audience-bound credential entries separate. A missing application named argus-mcp does not authorize inventing a Client ID. Hosted clients require their own pre-registration and approved redirects. Casdoor DCR-created applications default to seven-day tokens, so they are not accepted by Argus. Argus does not provide DCR and does not require Discovery to publish a registration_endpoint.

Argus configuration

The oauth settings group contains:

Setting Required meaning
enabled Enables REST API Bearer authentication and OAuth MCP
issuer Exact Casdoor issuer; HTTPS outside local/test
api_audience / mcp_audience Separate accepted resources
shared_institution_id Only institution granted to OAuth users
allowed_algorithms Asymmetric JWT algorithms; default RS256
max_token_lifetime_seconds At most 3600, matching Casdoor's minimum one-hour setting
clock_skew_seconds Default 60
jwks_cache_max_seconds At most 3600; response cache directives can shorten it
cli_client_id, cli_callback_url, login_scopes Public CLI PKCE client

Argus validates signature, kid, iss, aud, exp, nbf, and iat locally. An unknown kid triggers one immediate JWKS refresh and then fails closed. Argus does not call UserInfo and never stores access or refresh tokens. The CLI stores refresh credentials only in the operating-system credential store.

Authorization boundary

Argus maps every valid OAuth identity to institution:argus-oauth with governance_mode=machine_enforced. Permission scopes come from the signed scope/scp claim. Tool access comes from signed argus_tools/ tool_whitelist claims, or from the explicit argus:tools:public scope used by the pre-registered CLI. A valid token without either tool grant is denied all tools. OAuth requests are authorized by the same Argus permission, license, and output-policy chain as machine credentials; email domain, amr, MFA claim, and upstream login provider do not grant authorization.

The public scope maps to PUBLIC_OAUTH_TOOL_WHITELIST, not a wildcard. Consult the registry's permission_requirements.default_oauth_access before invocation. The reviewed public scope grants all 52 governed business tools, including metric_catalog and the five bounded stream_* tools. No additional administrator grant is required for these tools. Signed tool-specific claims can deliberately restrict an identity to a smaller set. Connector synchronization, metrics, and platform administration remain outside this public grant. Discovery through /v1/tool-registry remains unauthenticated. A registered tool is not a promise that the current credential can execute it or that a production provider has data available. Handle permission_denied, empty, partial, and unavailable results explicitly.

Danger

If Casdoor permits public registration or arbitrary external identities to complete authorization with the configured public-tool scope, those identities receive the reviewed default OAuth tool set within the shared institution. User admission, disablement, MFA, and identity provider restrictions must be enforced entirely in Casdoor.

Disabling a Casdoor user does not revoke an already issued token at Argus. With the required configuration, residual access lasts no more than one hour.

Enable only controlled password, email-code, SMS-code, and approved external providers in the same organization/application. Disable guest login, public registration, and unapproved providers: Casdoor controls who may obtain full Argus OAuth access. Administrator capabilities require separate explicit grants.