OIDC Local Testing with Forge CLI

This guide covers how to locally develop and test OIDC-enabled Aspects using the Forge CLI and the OIDC SSO Toolkit.

Prerequisites

• Docker — Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Forge CLI — installed via Homebrew or npm/pnpm (see Installation)

Overview

The Forge CLI integrates the OIDC SSO Toolkit — a Docker-based mock OIDC Identity Provider. When you preview the oidc-snippet template without providing --client-id / --fi-domain, the CLI automatically:

1. Starts the OIDC Toolkit Docker container.
2. Waits for the mock IdP to become healthy.
3. Fetches auto-generated client credentials from the toolkit.
4. Generates a working snippet targeting localhost:9000.
5. Registers the snippet in the OLB playground (or serves via local mock).

Quick Start

Bash

# Zero-config: starts toolkit, fetches credentials, generates working snippet
forge aspect preview --template oidc-snippet

The generated snippet performs a real OIDC authorization code flow against the local toolkit and displays a success toast upon completion.

Managing the Toolkit

You can also manage the toolkit independently:

Bash

# Start the toolkit
forge oidc up

# Check status, health, and credentials
forge oidc status

# Print credentials (useful for manual testing)
forge oidc credentials
forge oidc credentials --reveal  # show client secret

# Stop the toolkit
forge oidc down

How the Generated Snippet Works

In toolkit mode (default, no --client-id), the generated JavaScript:

1. Builds an authorization URL targeting http://localhost:9000/api/auth/authorize.
2. Sends a fetch() GET request with the auto-generated client_id.
3. The toolkit returns a JSON response containing an authorization code.
4. The snippet logs the code to the console.
5. If a --message was provided, a success toast appears.

In production mode (--client-id + --fi-domain), the snippet targets the real Keycloak endpoint at https://{fi-domain}/auth/realms/{fi-domain}/protocol/openid-connect/auth.

Transitioning to Production

Once your integration works locally:

1. Contact your Candescent PM for real FI credentials (client_id, client_secret, endpoint URLs)
2. Switch to production scaffold:

Bash

forge aspect preview --template oidc-snippet --client-id <pm-provided-id> --fi-domain <fi-domain>

3. Submit for review:

Bash

forge aspect submit "my-oidc-aspect" --template oidc-snippet --client-id <id> --fi-domain <domain> --env stage

Using the Toolkit with Custom Code

The toolkit is not limited to the built-in oidc-snippet template. You can point any custom Aspect or widget code to the toolkit endpoints:

Endpoint	URL	Method
Authorization	http://localhost:9000/api/auth/authorize	GET
Token	http://localhost:9000/api/auth/token	POST
Client credentials	http://localhost:9000/api/client	GET
Health check	http://localhost:9000/api/health	GET

Bash

# Start the toolkit independently
forge oidc up

# Get credentials for your custom code
forge oidc credentials --json

Port Configuration

By default, the toolkit uses ports 8000 (configuration UI) and 9000 (mock IdP API). If these ports are occupied, the CLI auto-resolves to the next available port. You can also specify ports manually:

Bash

forge oidc up --backend-port 9001 --frontend-port 8001

Troubleshooting

Issue	Cause	Solution
"Port 9000 is in use"	Another service on that port	Stop the conflicting service or use --backend-port 9001
Toolkit not becoming healthy	Container startup slow	Wait longer, or check docker logs cdx-oidc-toolkit
ARM64 / Apple Silicon warning	Image is amd64-only	Normal — the CLI runs it via emulation automatically
Credentials expired	15-minute TTL	Credentials auto-regenerate; re-fetch with forge oidc credentials
Docker not running	Docker Desktop not started	Start Docker Desktop and retry

References

• OIDC Integration Overview
• OIDC Technical Reference
• OIDC SSO Toolkit (GitHub)
• Aspects Overview