local-lab

🔐 OIDC Secure API Local Testing

This lab demonstrates how to use Envoy Proxy as an OIDC (OpenID Connect) enforcement point. It simulates a modern microservices environment where a sidecar validates JWT tokens from a Mock IDP before allowing traffic to reach a backend service.

🏗️ The setup

The lab consists of four Docker containers:

• mock-idp: A Navikt Mock-OAuth2-Server simulating a real OIDC provider (like GitHub, Okta, or Auth0).
• envoy: The gatekeeper. It uses the jwt_authn filter to validate tokens and Lua filters to assess claims.
• nginx: A simple Nginx service representing your internal API.
• tester: An Alpine-based container used to run curl and jq commands within the internal network.

🛠️ Prerequisites

Ensure you have the following installed:

• Docker & Docker Compose
• [Optional] nektos/act for GitHub Actions simulation

🚀 Quick Start

Testing with cURL

Enter the directory:

cd local-lab

Run the automated demo:
This script starts the stack, installs dependencies in the tester, and executes three security scenarios.

chmod +x run-local-demo.sh
./run-local-demo.sh

Manual Teardown:

docker compose down

Simulating GitHub Actions

To test the OIDC handshake exactly as it would run in GitHub Actions, use nektos/act. This spins up a runner container that joins the existing lab network.
After installing act, you can run:

cd local-lab 
docker compose up -d 
act --network local-lab_oidc-net -W ../templates/local-test.yaml 
docker compose down 

This will:

1. Navigate to lab directory
2. Start containers and network for the lab
3. Run GitHub Actions on your computer via act
4. Tear down the stack once completeed

Tip

Note: If act can't find the network, verify the name with docker network ls.
docker compose prefixes the network with the directory name, so running from a differently named directory changes it.

This runs the workflow locally inside a container that joins the lab network, allowing it to communicate with Envoy and the mock IDP.

🧪 Scenarios Tested

The demo script and actions execute the following test cases to verify the security policy:

Scenario	Description	Expected Result
1. Authorized	Request with a JWT containing the correct repository claim.	200 OK
2. Unauthorized Repo	Request with a valid JWT but from a "malicious" repository.	403 Forbidden
3. Wrong Audience	Request with a JWT intended for a different API.	403 Forbidden

📂 Key Files

• docker-compose.yaml: Orchestrates the 4-container environment.
• envoy-local.yaml: Defines the JWT validation provider and claim validation logic.
• run-local-demo.sh: Script that starts the lab containers, retrieves a token from the mock IDP, and executes the OIDC authentication flow locally.