Skip to content
Cawdit

Set up SSO sign-in

cawdit serve can let people sign in to its dashboard through an OpenID Connect provider, such as a company’s single sign-on. This page sets it up with Zitadel, and the steps carry over to other providers such as Keycloak, Authentik or Dex. Forge sign-in keeps working next to it, and the sign-in page shows a button for each.

Everybody who signs in through the provider sees every repository Cawdit reviews, with its runs, findings and cost. Cawdit cannot ask the forge what they may read, because they have no forge account there. So allow only the people who may see every review.

Before you start

You need:

  • cawdit serve running at a public URL, such as https://cawdit.example.com, set as public_url.
  • A session key: create one with openssl rand -hex 32 and give it to Cawdit as dashboard.session_key.
  • A Zitadel instance, such as https://auth.example.com, and an account that can create projects in an organization.

Create the project and its roles

Roles let you choose who may sign in inside Zitadel, rather than by email domain in Cawdit. Skip the roles if an email domain is enough.

  1. In the Zitadel console, open Projects and create a project named Cawdit.
  2. Under Roles, add the role cawdit for people who may use the dashboard, and cawdit-admin for admins.
  3. In the project’s General settings, turn on Assert Roles on Authentication, so Zitadel sends the roles at sign-in.
  4. Optionally, turn on Check authorization on Authentication, so Zitadel itself refuses people without a role in the project.
  5. Under Authorizations, give each person the role they need.

Create the application

  1. In the project, open Applications and create a new application named Cawdit.
  2. Choose the type Web.
  3. Choose the authentication method Code.
  4. Add the redirect URI <public_url>/api/v1/auth/callback, such as https://cawdit.example.com/api/v1/auth/callback, and leave the post-logout URI empty.
  5. Create the application, and copy the client ID and the client secret, which Zitadel shows only once.

With Code, Cawdit sends the client secret with HTTP Basic authentication and adds PKCE. PKCE works too and makes a public client without a secret. Post does not work, because Cawdit does not send the secret in the body. The redirect URI is the same callback the forge sign-in uses.

Check the application’s settings after you create it:

  • Grant types: Authorization Code.
  • Response types: Code.
  • Auth token type: Bearer or JWT, either works.
  • User roles inside ID Token and User Info inside ID Token may stay off, because Cawdit reads the user info endpoint for claims the ID token lacks.
  • Enable Development mode only if the redirect URI uses plain HTTP, such as on a laptop.

Cawdit asks for the scopes openid, profile and email, which Zitadel grants to every application.

Configure Cawdit

Put the client secret where Cawdit can read it, such as a file or an environment variable, and add [dashboard.oidc] to the deployment configuration:

public_url = "https://cawdit.example.com"

[dashboard]
session_key = "file:/run/secrets/session-key"

[dashboard.oidc]
issuer = "https://auth.example.com"
client_id = "312345678901234567@cawdit"
client_secret = "file:/run/secrets/oidc-client-secret"
name = "Example SSO"
allowed_groups = ["cawdit"]
groups_claim = "urn:zitadel:iam:org:project:roles"
admin_groups = ["cawdit-admin"]

The issuer must match the issuer in https://auth.example.com/.well-known/openid-configuration exactly, so leave out a trailing slash that Zitadel does not show.

Without roles, allow an email domain instead, and name the admins by email:

[dashboard.oidc]
issuer = "https://auth.example.com"
client_id = "312345678901234567@cawdit"
client_secret = "file:/run/secrets/oidc-client-secret"
name = "Example SSO"
allowed_domains = ["example.com"]
admins = ["alice@example.com"]

When you set both allowed_domains and allowed_groups, a person must pass both. Cawdit counts an email only when Zitadel marks it as verified.

The same settings work as environment variables, such as for a container:

CAWDIT_DASHBOARD_SESSION_KEY=file:/run/secrets/session-key
CAWDIT_DASHBOARD_OIDC_ISSUER=https://auth.example.com
CAWDIT_DASHBOARD_OIDC_CLIENT_ID=312345678901234567@cawdit
CAWDIT_DASHBOARD_OIDC_CLIENT_SECRET=env:OIDC_CLIENT_SECRET
CAWDIT_DASHBOARD_OIDC_NAME=Example SSO
CAWDIT_DASHBOARD_OIDC_ALLOWED_GROUPS=cawdit
CAWDIT_DASHBOARD_OIDC_GROUPS_CLAIM=urn:zitadel:iam:org:project:roles
CAWDIT_DASHBOARD_OIDC_ADMIN_GROUPS=cawdit-admin

Restart cawdit serve. The deployment configuration lists every key of [dashboard.oidc].

Check the sign-in

  1. Open the dashboard and choose Sign in with Example SSO.
  2. Sign in at Zitadel, which sends you back to the page you started from.
  3. Open the account menu: it shows your login and the provider’s name, and says when you are an admin.

When the sign-in fails, the dashboard says why, and cawdit serve logs the reason:

  • Your account may not use this dashboard means no allow rule matched. Check that the person has the role and a verified email, and that Assert Roles on Authentication is on.
  • The sign-in failed means Cawdit could not reach Zitadel or could not check its answer, and the log names the cause, such as a wrong client secret.

Cawdit fetches Zitadel’s discovery document on the first sign-in. It fetches the signing keys again whenever a token names a key it does not know yet, so a key rotation needs no restart.