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.

Northline sample Public client

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
Quickstart

Run the browser smoke test

  1. PrepareGenerate local credentials
  2. Start KeycloakUse the loopback issuer
  3. 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.

  1. 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
  2. Start the identity provider

    Set JAVA_HOME to 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
  3. 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.

Local client settings
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.

Review the launch gates