Developers
Integrate with OpenID Connect.
Run the Northline sample against local Keycloak, then use the same issuer, client ID, and callback URL in your OpenID Connect library.
Local client configuration
- Client IDnorthline-sample
- Authorization flowOIDC code with PKCE S256
- Callback URLhttp://localhost:3001/callback
OIDC_ISSUER=http://localhost:8180/realms/authcan-local
Run the browser smoke test
- PrepareGenerate local credentials
- Start KeycloakUse the loopback issuer
- VerifyRun npm run test:browser
Local quickstart
From the Covenant project directory, use Node.js 22.23.1 or later, Keycloak 26.8.2, a patched Java 21 LTS build, and Chrome.
-
Prepare the environment
Install the locked dependencies and generate the local credentials. The preparation command saves them in ignored files.
npm ci --ignore-scripts npm run local:prepare -
Start the identity provider
Set
JAVA_HOMEto your JDK and supply the path to your Keycloak directory. Keep the process running on loopback port 8180.npm run local:idp -- /path/to/keycloak-26.8.2 -
Verify sign-in
From a second terminal, leave ports 3000 and 3001 free and run the browser test. It starts an isolated console, exercises sign-in and passkey enrolment with synthetic accounts, and removes those accounts afterward.
npm run test:browser
Connect an OIDC client
Discover endpoints by appending /.well-known/openid-configuration to the issuer.
Request the openid scope and use authorization code with PKCE S256, state, and nonce.
Configure your client library to validate the ID token and use the registered callback URL exactly.
OIDC_ISSUER=http://localhost:8180/realms/authcan-local
OIDC_CLIENT_ID=northline-sample
OIDC_REDIRECT_URI=http://localhost:3001/callback
Public sample client · No client secret required
Developer resources
Production registration
The sample client is pre-registered for local testing. Production app registration, isolated projects, and regional issuers are pending. Test your integration with synthetic accounts for now.