Skip to content
Menu

Contributing#

This page tells you what Drawbridge is, where changes go, how to build and check them, and the rules a change must keep.

What the project is#

Drawbridge is the Citadel auth gateway: one OpenID Connect client to Microsoft Entra ID (through Apache mod_auth_openidc) in front of apps, which signs a short assertion for SESAME's gateway driver. It is a container image (docker/gateway/Dockerfile) plus a PHP signer and CLI (bin/drawbridge). It is not installed with Composer by apps and is not on Packagist.

Its consumer is SESAME's gateway driver. The assertion (header, claims, signing algorithm, lifetime) is a contract between the two; change both together. Integration tests run against a SESAME checkout when SESAME_PATH is set.

Where it lives#

Development happens on git.wayne.edu, the canonical repository (enterprise-apps/drawbridge). Changes, issues and merge requests go there. Tags are made there, by the maintainer, with an approver. Drawbridge is not on GitHub: git.wayne.edu is its only home.

Build and test#

Task Windows (PowerShell) Linux and macOS
Install composer install composer install
All checks (what CI runs) composer ci composer ci
Validate a config file php bin/drawbridge config:validate --config=config/drawbridge.yaml same
Build the gateway image docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . same
End-to-end rig (mock IdP by default, gateway, echo app, tests) rig\run.ps1 [keycloak] sh rig/run.sh [keycloak]

composer ci runs composer validate --strict, PHPUnit (unit and integration suites), Pint, the agent-ready check, PHPStan, composer audit and the docs check (composer docs:check). The end-to-end suite (phpunit.e2e.xml.dist) runs inside the rig. The rig's keys and passwords are throwaway values made for the rig only. The optional keycloak argument swaps the mock for a pinned Keycloak started from rig/keycloak/realm.json and runs the Keycloak tests instead; that provider checks the client secret and PKCE and knows only the realm's two synthetic users.

The docs pages wear the front page's look through two files: docs/_header.html (the masthead and sheet index) and docs/theme/drawbridge.css (the front page's tokens mapped onto the docs kit, plus the dark mode it shares with the front page's section 11 in site/assets/drawbridge.css; change one, change both). Change the look there, never in site/assets/docs.css or site/assets/docs.js, which are Squire's kit and are checked by hash. Rebuild with composer docs.

CI#

  • GitLab: Preflight's php-test (PHP 8.3, 8.4, 8.5) and composer-audit components, a composer-ci job, gateway-image:build (Buildah, on merge requests and main), gateway-image:publish (on tags only), a manual rig job, and the advisories job (scheduled or by hand only).
  • GitHub: .github/workflows/ci.yml calls Preflight's reusable workflow with composer ci, plus the rig job.
  • Green means composer ci passes on all three PHP versions on both, and the rig passes on GitHub.

Rules a change must keep#

BEST_PRACTICES.md lists the 55 practices the gateway holds itself to, each with one tag (Enforced, Checked, Documented or Not yet), and every Enforced practice names the tests that prove it. A change must keep all of them, among them: strip first, fail closed, public is a decision not a default, match the normalized path never the raw one, exact or prefix nothing clever, sign narrowly and briefly, let the module do OpenID Connect, one session per app host, overwrite forwarded headers, keep secrets out of git and out of logs, do not trust the network, run small and boring, bounded dependencies, add headers never overwrite. See Best practices for the full rules and the tests behind each one.

Where open work is listed#

OPEN_QUESTIONS.md lists what is still to be verified against a real tenant and what is not built yet, in three sections: questions (the identity provider rows E-1 to E-8, the platform rows C-1 to C-7, and questions that came up while building), missing configuration, and not built yet. Each "default built" is what the code does today, and each default is the safer choice. ENTRA_TEST.md is the checklist for the first real Entra test.

Releasing#

  1. Move the lines under the top heading of CHANGELOG.md (Keep a Changelog) to ## X.Y.Z (YYYY-MM-DD).
  2. composer ci and the rig green locally, then both pipelines green for that commit.
  3. Run a secrets scan of the history and check that nothing internal (server names, people, tenant or client IDs) is in the tree.
  4. Tag X.Y.Z (no v) on git.wayne.edu. The tag runs gateway-image:publish, which pushes the image to the stack's image registry: the group's images project, repository drawbridge-gateway, at the registry the NOUGAT_REGISTRY project variable names, logging in with the NOUGAT_REGISTRY_USER and NOUGAT_REGISTRY_TOKEN deploy token (protected variables, so release tags must be protected).
  5. A release needs a maintainer's approval. Running it in front of real apps also needs the Citadel platform team.

Who maintains it#

Wayne State University Enterprise Applications maintains Drawbridge. The internal runbook (accounts, the app registration, secret storage, platform contacts) is held by Enterprise Applications: ask them.