Configuration#

This page lists the settings of the IAM server, and the ways to change them. It is meant for developers who need a server behavior that differs from the default one. How pytest-iam works explains how these settings are used when the server starts.

Server settings#

The iam_configuration() session fixture returns the settings of the server, as a dict. The keys are Flask and Canaille settings, described in Configuration. pytest-iam sets these values:

@pytest.fixture(scope="session")
def iam_configuration(iam_server_port: int) -> dict[str, Any]:
    """Session fixture that returns the settings of the IAM server.

    Redefine it to change the settings, as described in :doc:`configuration`.
    """
    os.environ["AUTHLIB_INSECURE_TRANSPORT"] = "1"

    jwk = JWKRegistry.generate_key("RSA", 2048)
    jwk.ensure_kid()

    return {
        "TESTING": True,
        "ENV_FILE": None,
        "SECRET_KEY": str(uuid.uuid4()),
        "WTF_CSRF_ENABLED": False,
        "PREFERRED_URL_SCHEME": "http",
        "SERVER_NAME": f"localhost:{iam_server_port}",
        "CANAILLE": {
            "DATABASE": "memory",
            "ENABLE_REGISTRATION": True,
            "JAVASCRIPT": False,
            "ACL": {
                "DEFAULT": {
                    "PERMISSIONS": ["use_oidc", "manage_oidc"],
                }
            },
            "LOGGING": {
                "version": 1,
                "disable_existing_loggers": False,
                "formatters": {
                    "default": {
                        "format": "[%(asctime)s] %(levelname)s in %(module)s: %(message)s",
                    }
                },
                "handlers": {
                    "canaille": {
                        "class": "logging.NullHandler",
                        "formatter": "default",
                    }
                },
                "loggers": {
                    "canaille": {"level": "DEBUG", "handlers": ["canaille"]},
                },
            },
        },
        "CANAILLE_OIDC": {
            "DYNAMIC_CLIENT_REGISTRATION_OPEN": True,
            "ACTIVE_JWKS": [jwk.as_dict(private=True)],
        },
        "CANAILLE_SCIM": {"ENABLE_SERVER": True},
    }

The other settings keep their Canaille default value. The fixture also sets the AUTHLIB_INSECURE_TRANSPORT environment variable for the whole test process.

To change a setting, redefine the fixture in a conftest.py file, and edit the dictionary:

conftest.py#
import pytest


@pytest.fixture(scope="session")
def iam_configuration(iam_configuration):
    iam_configuration["CANAILLE_OIDC"]["REQUIRE_NONCE"] = False
    return iam_configuration

Server port#

The iam_server_port session fixture returns the port of the server. By default, it is a free port, picked when the server starts. Redefine the fixture to use a fixed port.

Environment variables#

The settings can also be set with environment variables. A variable name is the setting name, prefixed by PYTEST_IAM_. Nested settings are separated by __. For instance, PYTEST_IAM_CANAILLE_OIDC__REQUIRE_NONCE sets iam_configuration["CANAILLE_OIDC"]["REQUIRE_NONCE"].

env PYTEST_IAM_CANAILLE_OIDC__REQUIRE_NONCE=false pytest

The same variables can be written in a .pytest-iam.env file, in the current directory. The PYTEST_IAM_ prefix is also required in this file.

.pytest-iam.env#
 PYTEST_IAM_CANAILLE_OIDC__REQUIRE_NONCE=false

Priority#

A setting can be defined in several sources. The value from the first source in this list is used:

  1. the dictionary returned by iam_configuration();

  2. the environment variables prefixed by PYTEST_IAM_;

  3. the .pytest-iam.env file.

The priority applies to each setting. An environment variable cannot change a value that iam_configuration() sets, such as iam_configuration["CANAILLE"]["ENABLE_REGISTRATION"]. To change such a value, redefine the fixture.