Skip to main content

Configure External Casdoor

CSGHub includes a bundled Casdoor instance by default, which initializes its own organization, applications, JWT signing certificate and administrator. This document describes how to configure a Kubernetes (Helm) deployment to use a Casdoor instance that is operated separately (global.casdoor.enabled: false).

With an external Casdoor instance, the chart no longer creates any Casdoor object. The objects below must be created in the Casdoor instance beforehand, and the resulting credentials copied into the chart values.

The chart assumes a Casdoor schema compatible with the bundled image (casbin/casdoor:3.62.1). Older releases may not provide all settings referenced in this document (for example the Signin session toggle) and cannot be configured correctly with CSGHub.

1. Prerequisites​

  • A reachable Casdoor instance. HTTPS is recommended for production; plain HTTP is acceptable for local or internal testing. The endpoint must be reachable from both the browser and the CSGHub server pods, and the Casdoor origin setting must equal the URL configured in global.casdoor.external.endpoint, including the scheme.
  • Administrative access to the Casdoor instance.
  • The CSGHub endpoint (global.gateway.external.domain, with TLS as configured). It is used to construct redirect URIs.
  • A Kubernetes Secret holding the JWT signing certificate (created in step 4).

2. Confirm the endpoint​

curl -sS https://sso.example.com/.well-known/openid-configuration | jq -r .issuer

The issuer must equal https://sso.example.com, without a trailing slash. If it does not match, correct the Casdoor origin / frontend URL before continuing.

Casdoor derives the issuer and all advertised endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint) from origin. In-cluster components use these endpoints, and the Temporal console validates the ID token issuer against global.casdoor.external.endpoint. An origin set to localhost or another address unreachable from the cluster therefore results in a failed token exchange.

3. Create the organization​

In Casdoor: Organizations → Add.

  • Name: OpenCSG (or a custom name; set global.casdoor.organization accordingly)
  • Password type: bcrypt, salt OpenCSG
  • Account items: retain Tag and Is admin (details below)

Default application: leave empty at this stage. The dropdown lists only existing applications, and CSGHub is created in step 5. The remaining attributes (logo, theme, languages, password policy, ...) may be configured as required; they do not affect the CSGHub integration.

Organization settings

Account items​

The Account items table of an organization determines which user fields are displayed in the signup and profile forms. CSGHub reads the user Tag field and the administrator flag, so both rows must remain in the table.

Open Organizations → OpenCSG → Edit and scroll down to Account items.

Account items table

The table is pre-filled with the default items. Locate the following two rows:

NameVisibleView ruleModify rule
TagonPublicAdmin
Is adminonAdminAdmin

These are the Casdoor defaults and match the bundled deployment, so a new organization already conforms. When editing the table:

  • The Name column is a dropdown of known Casdoor items, not a free-text field. If a row is missing, click Add in the Account items card header and select Tag / Is admin from the dropdown. The stored name is the English key even when the UI is set to another language.
  • The View rule and Modify rule columns are rendered only while the row is visible. Is admin is an administrative item, so its modify rule is limited to Admin / Immutable.

Removing either row does not affect sign-in, but the corresponding field no longer appears on the CSGHub profile page.

4. Create the JWT signing certificate​

In Casdoor: Certs → Add.

  • Organization: OpenCSG
  • Name: csghub-cert
  • Scope: JWT
  • Type: x509
  • Algorithm: RS256, bit size 4096

JWT signing certificate

Casdoor generates the key pair. Export the public certificate (not the HTTPS certificate of the Casdoor endpoint) and create the Secret:

# tls.crt must contain the PEM certificate of the csghub-cert signing key
kubectl create secret generic csghub-casdoor-cert \
--namespace csghub \
--from-file=tls.crt=./csghub-cert.crt

The chart mounts this Secret into the server, user and executor pods and points STARHUB_SERVER_CASDOOR_CERTIFICATE at tls.crt.

5. Create the CSGHub application​

In Casdoor: Applications → Add. The settings are distributed across several tabs.

Basic

  • Name: CSGHub (or set global.casdoor.application)
  • Organization: OpenCSG
  • Cert: csghub-cert
  • Redirect URI: <csghub-endpoint>/api/v1/callback/casdoor

CSGHub application: Basic tab

OIDC/OAuth

  • Token format: JWT
  • Grant types: Authorization Code

CSGHub application: OIDC/OAuth tab

Authentication

  • Signin session: on
  • Enable signup: on

CSGHub application: Authentication tab

UI Customization

  • Organization choice mode: Select

CSGHub application: UI Customization tab

If csghub-cert is not available in the Cert dropdown during creation, save the application with the other fields first (Organization is required), reopen it, and select the certificate.

Copy the generated Client ID and Client secret from the Basic tab; they become global.casdoor.external.applications.portal.clientId and clientSecret.

Finally, set Organizations → OpenCSG → Edit → Default application to CSGHub. Step 3 leaves it empty because the application does not exist at that point.

Default application

6. Create the Admin application​

This application is used by the Temporal and Superset consoles when they are enabled. The tab layout is the same as in the preceding section.

In Casdoor: Applications → Add.

Basic

  • Name: Admin
  • Organization: OpenCSG
  • Cert: csghub-cert
  • Redirect URIs:
    • <csghub-endpoint>/-/temporal/auth/sso/callback
    • <csghub-endpoint>/-/superset/oauth-authorized/casdoor

Admin application: Basic tab

OIDC/OAuth

  • Token format: JWT
  • Grant types: Authorization Code

Admin application: OIDC/OAuth tab

Authentication

  • Signin session: on
  • Enable signup: off

Admin application: Authentication tab

Copy its client ID and secret into global.casdoor.external.applications.admin.clientId / clientSecret. The chart fails at render time if the Temporal console or Superset is enabled and these values are missing.

7. Create the CSGShip application (optional)​

Required only when CSGShip is configured against the external instance.

Basic

  • Name: CSGShip
  • Organization: OpenCSG
  • Cert: csghub-cert
  • Redirect URI: <csgship-webAPI-endpoint>/api/v1/account/casdoor/login/callback

CSGShip application: Basic tab

OIDC/OAuth

  • Token format: JWT
  • Grant types: Authorization Code

CSGShip application: OIDC/OAuth tab

Copy the credentials into global.casdoor.external.applications.csgship.clientId / clientSecret.

CSGShip in the CSGHub umbrella: the umbrella includes CSGShip as a published subchart, and the pinned version does not support an external Casdoor. The chart therefore rejects global.casdoor.enabled=false together with csgship.enabled=true. Keep csgship disabled, or deploy the CSGShip chart separately once it provides global.casdoor support.

8. Create the providers​

Applications reference providers by name. Create the required providers under Providers:

  • Email_Provider (category Email): required for signup email flows.
  • Captcha_Provider (category Captcha): referenced by the default sign-in page.
  • GitLab_Provider (category OAuth, type Custom): required only when GitLab login is used.

Providers

An application that references a missing provider displays an error on the sign-in page.

9. Create the first administrator​

The Users page creates a new user in the organization currently selected in the organization selector of the top navigation bar, not in an organization chosen during creation. With the default All selected, Users → Add attempts to create the user in built-in, which Casdoor rejects:

adding a new user to the 'built-in' organization is currently disabled ... all users in the 'built-in' organization are global administrators in Casdoor

Do not circumvent this restriction by enabling Has privilege consent on built-in: that setting grants the user global Casdoor administrator privileges, which CSGHub does not require. Perform the following steps instead:

  1. In the top navigation bar, locate the organization selector on the right, between the language/theme buttons and the account menu. It is a wide dropdown that displays All by default; switch it to OpenCSG. The selector is visible to administrators only and is hidden in narrow (mobile) layouts; widen the browser window if it is not displayed.

    Organization selector

  2. Users → Add. Casdoor creates user_<random> in OpenCSG and opens its edit page.

    Users in the organization

  3. Set Name to root, set Tag to is_admin, select Is admin, and save.

    root user fields

    Is admin checkbox

The username must be root: CSGHub promotes root to its administrator on first sign-in. An administrator with a different username is not promoted automatically.

10. Configure the chart​

The enable switch, organization/application names, and external settings are all defined in global.casdoor, because the Casdoor instance is shared with the other charts in the deployment:

global:
casdoor:
enabled: false # false = use the external instance
organization: "OpenCSG" # organization CSGHub authenticates against
application: "CSGHub" # application CSGHub authenticates against
external:
endpoint: "https://sso.example.com"
existingSecret: "csghub-casdoor-cert"
applications:
portal: # the application the CSGHub portal logs into
clientId: "<portal client id>"
clientSecret: "<portal client secret>"
admin: # required when Temporal console or Superset is enabled
clientId: "<admin client id>"
clientSecret: "<admin client secret>"
csgship: # only for a standalone CSGShip deployment
clientId: "<csgship client id>"
clientSecret: "<csgship client secret>"

The keys under applications represent roles, not Casdoor application names; applications on an external instance may use any name. portal is the application used for CSGHub portal sign-in (its name is set in global.casdoor.application), admin is used by the Temporal and Superset consoles, and csgship is used by CSGShip.

global.casdoor.external.endpoint overrides the derived Casdoor URL in every location where it is consumed: the server configmap, portal login URL, CORS origins, Temporal and Superset OIDC settings, and the redirect route.

When global.casdoor.enabled=false, the chart creates no Casdoor objects. A missing existingSecret or application credential fails rendering, so it is detected at install time; a missing endpoint does not fail rendering, but falls back to the bundled Casdoor address and login fails at runtime, so it must also be set:

Missing valueWhen it must be set
global.casdoor.external.endpointalways
global.casdoor.external.existingSecretCSGHub chart (its server, user and executor pods mount the JWT certificate); not needed by a standalone CSGShip
global.casdoor.external.applications.portal.clientId / clientSecretalways
global.casdoor.external.applications.admin.clientId / clientSecretTemporal console or Superset enabled
global.casdoor.external.applications.csgship.clientId / clientSecretstandalone CSGShip deployment

11. Optional: sync the CSGHub administrator role to Casdoor​

The bundled deployment synchronizes Casdoor user.is_admin with CSGHub's role_mask through a PostgreSQL foreign data wrapper. With an external Casdoor instance this is not configured automatically; it must be configured manually to enable the behavior.

The external Casdoor database must:

  1. Be reachable from the bundled PostgreSQL instance.
  2. Have a role csghub_server_fdw with CONNECT, USAGE on schema public, and SELECT, UPDATE on public."user".

Run fdw-grant.sql on the external Casdoor database to create the role and grants. The csghub_server_fdw role has no password; cross-instance access requires one, and the user mapping below must use the same value:

ALTER ROLE csghub_server_fdw PASSWORD '<password>';

Then create the foreign server and trigger in the CSGHub server database, replacing the host, port, database name and password with the Casdoor values:

CREATE EXTENSION IF NOT EXISTS postgres_fdw;

CREATE SERVER csghub_casdoor_fdw FOREIGN DATA WRAPPER postgres_fdw
OPTIONS (host '<casdoor-db-host>', port '5432', dbname '<casdoor-db>');

CREATE USER MAPPING FOR <csghub-server-db-user>
SERVER csghub_casdoor_fdw
OPTIONS (user 'csghub_server_fdw', password '<password>');

CREATE FOREIGN TABLE public.casdoor_users (id varchar(100), is_admin boolean)
SERVER csghub_casdoor_fdw OPTIONS (schema_name 'public', table_name 'user');

The trigger function, trigger and backfill are identical to 1789619535_sync_role_mask_admin.sql. The foreign server, user mapping and foreign table in that file duplicate the statements above; skip those sections and apply only the trigger function, trigger and backfill.

If this step is skipped, CSGHub continues to operate, but administrator changes in CSGHub are not propagated to Casdoor, and those users cannot open the Temporal or Superset consoles.

12. Install and verify​

helm upgrade --install csghub csghub/csghub \
--namespace csghub \
-f values.yaml

Verify the following in order:

  1. Endpoint: kubectl -n csghub get configmap <release>-core -o yaml | grep CASDOOR displays the configured endpoint, organization, application and client ID.
  2. Certificate: the server pod mounts tls.crt, whose content is the csghub-cert public certificate.
  3. Login: open the CSGHub UI and sign in; confirm that the browser returns to /api/v1/callback/casdoor without an error.
  4. Token validation: server logs show no 401 / certificate errors after sign-in.
  5. Optional modules: open the Temporal console (if enabled) and confirm that SSO sign-in succeeds and does not require re-authentication on every visit.

verify.sh runs the read-only checks above against a running release.

Troubleshooting​

SymptomLikely cause
Redirected to Casdoor, then back to the login pagetls.crt is the HTTPS certificate instead of the csghub-cert JWT certificate, or the client ID/secret do not match the application.
invalid redirect_uri from CasdoorThe redirect URI does not exactly match the scheme/host/port of the CSGHub endpoint.
invalid_clientThe client ID or secret was copied from a different application.
Temporal SSO fails while exchanging the token, and the URL points at a host that was not configuredThe Casdoor origin differs from global.casdoor.external.endpoint, or origin was changed after the Temporal console started. Align origin, then restart the Temporal deployment.
Sign-in succeeds, but every Temporal console visit asks for credentialsThe Signin session toggle (Authentication tab) is off on the CSGHub/Admin application.
Administrator changes in CSGHub do not reach CasdoorFDW sync not configured (step 11).
x509: certificate signed by unknown authority in server logsThe Casdoor endpoint uses a private CA that the server container does not trust. Use a publicly trusted certificate, or mount the CA and set SSL_CERT_FILE through the server service volumes/environments overrides.
Sign-in page shows a provider errorThe application references a provider that does not exist (step 8).
Install fails with global.casdoor.enabled=false cannot be combined with csgship.enabled=trueThe CSGShip subchart of the umbrella does not yet support an external Casdoor (step 7). Keep csgship disabled.