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 serverunning at a public URL, such ashttps://cawdit.example.com, set aspublic_url.- A session key: create one with
openssl rand -hex 32and give it to Cawdit asdashboard.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.
- In the Zitadel console, open Projects and create a project named
Cawdit. - Under Roles, add the role
cawditfor people who may use the dashboard, andcawdit-adminfor admins. - In the project’s General settings, turn on Assert Roles on Authentication, so Zitadel sends the roles at sign-in.
- Optionally, turn on Check authorization on Authentication, so Zitadel itself refuses people without a role in the project.
- Under Authorizations, give each person the role they need.
Create the application
- In the project, open Applications and create a new application named
Cawdit. - Choose the type Web.
- Choose the authentication method Code.
- Add the redirect URI
<public_url>/api/v1/auth/callback, such ashttps://cawdit.example.com/api/v1/auth/callback, and leave the post-logout URI empty. - 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:
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:
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:
Restart cawdit serve.
The deployment configuration lists every key of [dashboard.oidc].
Check the sign-in
- Open the dashboard and choose Sign in with Example SSO.
- Sign in at Zitadel, which sends you back to the page you started from.
- 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.