README.md

Stub OIDC server

Stub OpenID Connect server for testing.

Primarily used to stub GOV.UK One Login for end-to-end tests and load testing of services that use it.

Prerequisites

1. Install Python 3.12

Running locally

1. Create a virtual environment:

   python3.12 -m venv --prompt . --upgrade-deps .venv

2. Activate the virtual environment:

   source .venv/bin/activate

3. Install the dependencies:

   pip install -e .[dev]

4. Run the server:

   make run

5. Open http://localhost:5001

Running locally using Docker

To run the server as a container:

1. Build the Docker image:

   docker build -t oidc_server .

2. Run the Docker image:

   docker run --rm -p 5001:5001 -e FLASK_SERVER_NAME=localhost:5001 oidc_server

3. Open http://localhost:5001

The server can also be run on a different port by specifying the PORT environment variable:

docker run --rm -p 8000:8000 -e FLASK_SERVER_NAME=localhost:8000 -e PORT=8000 oidc_server

The image is also available on GitHub Container registry as ghcr.io/acteng/stub-oidc-server.

Configuring

The server can be configured on start up using environment variables or at runtime using a Web API.

Environment variables

Use the following environment variables to create a user and register a client on start up:

Name	Value
FLASK_OIDC_USER_ID	OIDC user id
FLASK_OIDC_USER_EMAIL	OIDC user email
FLASK_OIDC_CLIENT_ID	OIDC client id
FLASK_OIDC_CLIENT_REDIRECT_URI	OIDC client redirect URI
FLASK_OIDC_CLIENT_PUBLIC_KEY	OIDC client public key
FLASK_OIDC_CLIENT_SCOPE	OIDC client scope

Web API

To create a user:

curl http://localhost:5001/users \
    -H 'Content-Type: application/json' \
    -d "{
            \"id\": \"test-user\",
            \"email\": \"[email protected]\"
        }"

To delete all users:

curl -X DELETE http://localhost:5001/users

To register an OIDC client:

curl http://localhost:5001/clients \
    -H 'Content-Type: application/json' \
    -d "{
            \"client_id\": \"test-client\",
            \"redirect_uri\": \"http://localhost:5000/auth\",
            \"public_key\": \"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\",
            \"scope\": \"openid email\"
        }"

To unregister all OIDC clients:

curl -X DELETE http://localhost:5001/clients

Licence

MIT License