Authentication & Authorization

IXMP4 has built-in authentication and authorization facilities, which can restrict access for different users according to a custom permission system.

Almost all operations on a platform require “view”, “submit”, “edit” or “manage” permissions if authorization is enabled. If permission requirements are not met, any operation may raise an Unauthorized exception. Additionally, when querying data, a given user may not be able to see the totality of the data in a platform.

Authenticating with IIASA Infrastructure

IIASA provides a number of “public”, “gated” and “private” ixmp4 instances. To access “gated” instances and allow instance managers to give you access to or permissions on their instances, you will need an account with the ECE Management Service.

Once active, your account can be used to log in via the login console command.

ixmp4 login <username>

You will be prompted to enter your password.

Warning

Your username and password will be saved locally in plain-text for future use!

To list the instances you have access to you can use:

ixmp4 platforms list

From a Python environment, you can then connect to any of these platforms using the following code (provided you enjoy the necessary permissions):

import ixmp4
platform = ixmp4.Platform("<platform-name>")

Note

See the CLI section “IIASA Infrastructure” for more information on available commands.

Authenticating with a Local Server

By default, the ixmp4 server start command will start an ixmp4 server without any authentication mechanisms or checks.

To enable authentication, supply the Ixmp4Server class with a ServerSettings class that has a secret_hs256 configuration variable.

from ixmp4.server import Ixmp4Server
from ixmp4.conf.settings import ServerSettings

server = Ixmp4Server(ServerSettings(secret_hs256="changeme"))

# ... use server.asgi_app to start a server

Or set the IXMP4_SERVER__SECRET_HS256 environment variable:

IXMP4_SERVER__SECRET_HS256=changeme ixmp4 server start

A client connecting to a server started in this manner has to be configured using the ixmp4.conf.settings.ClientSettings.secret_hs256 configuration variable to enable unrestricted use:

import ixmp4
from ixmp4.conf.settings import ClientSettings
from ixmp4.transport import HttpxTransport

transport = HttpxTransport.from_url(
    "http://localhost:9000/v1/test/",
    ClientSettings(secret_hs256="changeme"),
)
platform = ixmp4.Platform(transport)

This will give anyone with knowledge of the secret superuser access to the local server instance. Anyone connecting without a secret will receive an “unauthorized” response.

Note

The secret is used for cryptographic signatures and their verification. It is never sent in any client-server communication.

Ideally, it is only shared between individuals physically or via verifiably secure channels.