Configuration

Dev OIDC Toolkit can be configured in two ways, either through environment variables, or through a JSON configuration file. Additionally, users and clients can be created and managed at runtime through the web interface - see Runtime Management for details.

Environment variable configuration

Dev OIDC Toolkit can be configured using environment variables. The environment variables should be prefixed with DevOidcToolkit__.

Docker

Here is how to run the application in a Docker container with environment variables:

docker run -p 8080:80                                                                \
    -e DevOidcToolkit__Users__0__Email=test@localhost                                 \
    -e DevOidcToolkit__Users__0__FirstName=Test                                       \
    -e DevOidcToolkit__Users__0__LastName=User                                        \
    -e DevOidcToolkit__Clients__0__Id=client                                          \
    -e DevOidcToolkit__Clients__0__Secret=secret                                      \
    -e DevOidcToolkit__Clients__0__RedirectUris__INDEX=http://localhost:3000/callback \
    ghcr.io/businesssimulations/dev-oidc-toolkit

The __0__ refers to the index of the user or client, and can be any integer, this allows you to add more users or clients by increasing the index.

Reference

This is a list of all of the environment variables that can be used to configure Dev OIDC Toolkit.

Environment Variable	Description	Example	Default Value
DevOidcToolkit__Port	The port that the application will listen on.	80	80
DevOidcToolkit__Address	The address that the application will listen on.	localhost	localhost
DevOidcToolkit__Issuer	Override the issuer URL embedded in tokens and the OIDC discovery document. Useful for testing clients that validate the `iss` claim. When not set, the issuer is derived from the incoming request URL.	https://fake-issuer.example.com	None (derived from request URL)
DevOidcToolkit__Database__SqliteFile	The path to the SQLite database file. When set, data is persisted to this file and survives restarts. When not set, an in-memory database is used and all data is lost on restart.	/data/dev-oidc-toolkit.db	None (in-memory)
DevOidcToolkit__Logging__MinimumLevel	The minimum log level, possible values are Trace, Debug, Information, Warning, Error, Critical.	Information	Information
DevOidcToolkit__Logging__UseXForwardedForHeader	Whether to use the X-Forwarded-For header, useful if behind a proxy.	false	false
DevOidcToolkit__Https__File__CertificatePath	The path to the certificate file.	/app/cert.pem	None
DevOidcToolkit__Https__File__PrivateKeyPath	The path to the private key file.	/app/key.pem	None
DevOidcToolkit__Https__Inline__Certificate	The certificate as a string.	Raw PEM certificate	None
DevOidcToolkit__Https__Inline__PrivateKey	The private key as a string.	Raw PEM private key	None
DevOidcToolkit__Users__INDEX__Email	The email of the user.	user@example.com	None
DevOidcToolkit__Users__INDEX__FirstName	The first name of the user.	John	None
DevOidcToolkit__Users__INDEX__LastName	The last name of the user.	Doe	None
DevOidcToolkit__Users__INDEX__Roles__INDEX	The roles of the user	user	None
DevOidcToolkit__Clients__INDEX__Id	The ID of the client.	client	None
DevOidcToolkit__Clients__INDEX__Secret	The secret of the client.	client	None
DevOidcToolkit__Clients__INDEX__RedirectUris__INDEX	The redirect URIs of the client.	http://localhost:8080/callback	None
DevOidcToolkit__Clients__INDEX__PostLogoutRedirectUris__INDEX	The post logout redirect URIs of the client.	http://localhost:8080/callback	None

File configuration

Dev OIDC Toolkit can be configured using a JSON file. The file should be named config.json and should be placed in the same directory that the application is running in.

Docker

When running the application in a Docker container, the config.json file should be mounted to the container at /app/config.json.

Here is how to run the application in a Docker container with a configuration file mounted:

docker run -p 8080:80 -v ./config.json:/app/config.json ghcr.io/businesssimulations/dev-oidc-toolkit

Reference

This is a list of all of the JSON properties that can be used to configure Dev OIDC Toolkit.

All properties are included in a JSON object with the key DevOidcToolkit (see the example for more details).

Root

Property	Type	Description	Example	Default Value
Port	int	The port that the application will listen on.	80	80
Address	string	The address that the application will listen on.	localhost	localhost
Issuer	string	Override the issuer URL embedded in tokens and the OIDC discovery document. Useful for testing clients that validate the `iss` claim. When not set, the issuer is derived from the incoming request URL.	https://fake-issuer.example.com	None
Database	object	The database configuration, see Database for more information.	See Database for more information.	None (in-memory)
Https	object	The HTTPS configuration, see HTTPS for more information.	See HTTPS for more information.	None
Logging	object	The logging configuration, see Logging for more information.	See Logging for more information.	None
Users	array	The users that will be created in the database, see Users for more information.	See Users for more information.	[]
Clients	array	The clients that will be created in the database, see Clients for more information.	See Clients for more information.	[]

Https

Property	Type	Description	Default Value
File	object	The HTTPS configuration, see HTTPS file certificate for more information.	None
Inline	object	The HTTPS configuration, see HTTPS inline certificate for more information.	None

Https file certificate

Property	Type	Description	Example	Default Value
CertificatePath	string	The path to the certificate file.	/app/cert.pem	None
PrivateKeyPath	string	The path to the private key file.	/app/key.pem	None

Https inline certificate

Property	Type	Description	Example	Default Value
Certificate	string	The certificate as a string.	Raw PEM certificate	None
PrivateKey	string	The private key as a string.	Raw PEM private key	None

Logging

Property	Type	Description	Example	Default Value
MinimumLevel	string	The minimum log level, possible values are Trace, Debug, Information, Warning, Error, Critical.	Information	Information
UseXForwardedForHeader	bool	Whether to use the X-Forwarded-For header, useful if behind a proxy.	false	false

Database

The database configuration controls how data is stored. By default, an in-memory database is used and all data (including users and clients created at runtime) is lost when the application stops. Set SqliteFile to a file path to use a SQLite database instead, which persists data between restarts.

!!! note "Limitations" The SQLite database schema is created automatically on first run using EnsureCreated. There are no migrations supported — if the schema changes in a future version of dev-oidc-toolkit you may need to delete and recreate the database file.

Property	Type	Description	Example	Default Value
SqliteFile	string	Path to the SQLite database file. When set, all data is persisted to this file. When omitted, an in-memory database is used and data is lost on restart.	/data/dev-oidc-toolkit.db	None (in-memory)

Users

Property	Type	Description	Example	Default Value
Email	string	The email of the user.	sudo@localhost	None
FirstName	string	The first name of the user.	Test	None
LastName	string	The last name of the user.	User	None

Clients

Property	Type	Description	Example	Default Value
Id	string	The ID of the client.	test	None
Secret	string	The secret of the client.	ThisIsNotARealSecret	None
RedirectUris	array	The redirect URIs of the client.	["http://localhost:3000/callback"]	[]
PostLogoutRedirectUris	array	The valid post logout redirect URIs of the client.	["http://localhost:3000/callback"]	[]

Example JSON configuration

In-memory database (default, no persistence):

{
    "DevOidcToolkit": {
        "Port": 80,
        "Issuer": "https://fake-issuer.example.com",
        "Users": [
            {
                "Email": "sudo@localhost",
                "FirstName": "Test",
                "LastName": "User"
            }
        ],
        "Clients": [
            {
                "Id": "test",
                "Secret": "ThisIsNotARealSecret",
                "RedirectUris": [
                    "http://localhost:3000/callback"
                ]
            }
        ]
    }
}

SQLite database (data persists across restarts):

{
    "DevOidcToolkit": {
        "Port": 80,
        "Database": {
            "SqliteFile": "/data/dev-oidc-toolkit.db"
        },
        "Users": [
            {
                "Email": "sudo@localhost",
                "FirstName": "Test",
                "LastName": "User"
            }
        ],
        "Clients": [
            {
                "Id": "test",
                "Secret": "ThisIsNotARealSecret",
                "RedirectUris": [
                    "http://localhost:3000/callback"
                ]
            }
        ]
    }
}