Sign inSign up

marcoimme/oidcmock

By marcoimme

•Updated 8 months ago

A Python implementation of a mock OpenID Connect (OIDC) server for testing and development.

Image
0

1.3K

marcoimme/oidcmock repository overview

⁠MockOIDC Docker Image

A lightweight OpenID Connect (OIDC) mock server for testing and development, packaged as a Docker image.

⁠Quick Start

docker run -p 8080:8080 marcoimme/oidcmock:latest

The server will be available at http://localhost:8080

⁠What is MockOIDC?

MockOIDC is a full-featured OIDC provider simulator that implements:

  • ✅ OpenID Connect Discovery
  • ✅ Authorization Code Flow with PKCE
  • ✅ JWT token generation (RS256)
  • ✅ UserInfo endpoint
  • ✅ JWKS endpoint
  • ✅ Token introspection and revocation

Perfect for testing, CI/CD pipelines, and local development without depending on real identity providers.

⁠Usage

⁠Basic Configuration
docker run -p 8080:8080 \
  -e ISSUER=http://localhost:8080 \
  -e PORT=8080 \
  marcoimme/oidcmock:latest
⁠Available Environment Variables
VariableDefaultDescription
PORT8080Server listening port
LOG_LEVELINFOLogging level (DEBUG, INFO, WARNING, ERROR)
ACCESS_TOKEN_LIFETIME3600Access token lifetime in seconds
ID_TOKEN_LIFETIME3600ID token lifetime in seconds
AUTHORIZATION_CODE_LIFETIME600Authorization code lifetime in seconds
⁠Custom Users

Mount a custom users.json file to define your test users:

docker run -p 8080:8080 \
  -v $(pwd)/users.json:/app/config/users.json \
  marcoimme/oidcmock:latest

Example users.json:

{
  "users": [
    {
      "sub": "[email protected]",
      "name": "John Doe",
      "email": "[email protected]",
      "preferred_username": "john.doe",
      "groups": ["admin", "developers"]
    }
  ]
}
⁠Docker Compose Example
version: '3.8'

services:
  mockoidc:
    image: marcoimme/oidcmock:latest
    ports:
      - "8080:8080"
    environment:
      ISSUER: http://localhost:8080
      LOG_LEVEL: DEBUG
    volumes:
      - ./config/users.json:/app/config/users.json
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/.well-known/openid-configuration"]
      interval: 30s
      timeout: 10s
      retries: 3

  your-app:
    image: your-app:latest
    depends_on:
      - mockoidc
    environment:
      OIDC_ISSUER: http://mockoidc:8080
      OIDC_CLIENT_ID: test-client

⁠OIDC Endpoints

Once running, the following endpoints are available:

  • GET /.well-known/openid-configuration - OpenID Connect Discovery
  • GET /authorize - Authorization endpoint
  • POST /token - Token endpoint
  • GET /userinfo - UserInfo endpoint
  • GET /jwks - JSON Web Key Set
  • POST /revoke - Token revocation
  • GET /logout - Logout endpoint
⁠Testing the Flow

1. Discovery:

curl http://localhost:8080/.well-known/openid-configuration | jq

2. Authorization:

curl "http://localhost:8080/authorize?response_type=code&client_id=test-client&redirect_uri=http://localhost:3000/callback&scope=openid+profile+email&state=xyz"

3. Token Exchange:

curl -X POST http://localhost:8080/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_CODE" \
  -d "client_id=test-client" \
  -d "redirect_uri=http://localhost:3000/callback"

4. Get User Info:

curl http://localhost:8080/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⁠Integration Examples

⁠Python (requests-oauthlib)
from requests_oauthlib import OAuth2Session

oauth = OAuth2Session(
    "test-client",
    redirect_uri="http://localhost:3000/callback",
    scope=["openid", "profile", "email"]
)

auth_url, state = oauth.authorization_url("http://localhost:8080/authorize")
# Visit auth_url, get code, then:
token = oauth.fetch_token(
    "http://localhost:8080/token",
    authorization_response=callback_url,
    client_id="test-client"
)
⁠Node.js (openid-client)
const { Issuer } = require('openid-client');

const issuer = await Issuer.discover('http://localhost:8080');
const client = new issuer.Client({
  client_id: 'test-client',
  redirect_uris: ['http://localhost:3000/callback'],
  response_types: ['code']
});

const authUrl = client.authorizationUrl({
  scope: 'openid profile email'
});

⁠Volumes

PathDescription
/app/config/users.jsonCustom users configuration
/app/keys/private_key.pemCustom RSA private key
/app/keys/public_key.pemCustom RSA public key

⁠Networking

⁠With Custom Network
docker network create app-network

docker run --network app-network \
  --name mockoidc \
  -p 8080:8080 \
  marcoimme/oidcmock:latest

docker run --network app-network \
  -e OIDC_ISSUER=http://mockoidc:8080 \
  your-app:latest

⁠Health Check

The image includes a health check endpoint:

curl http://localhost:8080/.well-known/openid-configuration

Docker health check is configured to verify the discovery endpoint every 30 seconds.

⁠Tags

  • latest - Latest stable release
  • v1.x.x - Specific version
  • main - Latest commit from main branch (unstable)

⁠Image Details

  • Base Image: python:3.13-slim
  • Exposed Ports: 8080
  • Working Directory: /app
  • Non-root User: appuser (UID 1000)

⁠Security Notes

⚠️ This image is intended for testing and development only.

  • No real authentication
  • In-memory storage (data lost on restart)
  • Auto-generated RSA keys (not persisted between restarts)
  • No rate limiting or production hardening

Do not use in production environments.

⁠Troubleshooting

⁠View Logs
docker logs mockoidc
⁠Enable Debug Logging
docker run -p 8080:8080 \
  -e LOG_LEVEL=DEBUG \
  marcoimme/oidcmock:latest
⁠Port Already in Use
docker run -p 9090:8080 \
  -e ISSUER=http://localhost:9090 \
  marcoimme/oidcmock:latest
⁠Token Validation Fails

⁠Source Code

Full source code available at: https://github.com/marcoimme/mockoidc⁠

⁠License

MIT License - see repository for details

⁠Support

For issues and questions:

Tag summary

Content type

Image

Digest

sha256:b6035c072…

Size

73.9 MB

Last updated

8 months ago

docker pull marcoimme/oidcmock