linotp.controllers.system module

system controller - to configure the system

exception linotp.controllers.system.RemoveForbiddenError

Bases: Exception

class linotp.controllers.system.SystemController(name, install_name='', **kwargs)

Bases: BaseController

The linotp.controllers are the implementation of the web-API to talk to the LinOTP server. The SystemController is used to configure the LinOTP server. The functions of the SystemController are invoked like this

https://server/system/<functionname>

The functions are described below in more detail.

checkPolicy()

GET, POST /system/checkPolicy

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

checks if a the given parameter will trigger a policy or not.

Parameters:

  • user – the name of the user

  • realm – the realm

  • scope – the scope

  • action – the action

  • client – the client IP

Returns:

a json result like this:
value{ “allowed””true”,

”policy” : <Name der Policy, die das erlaubt hat> }

value{ “allowed””false”,

”info” : <sowas wie die Fehlermeldung> }

Raises:

Exception – if an error occurs an exception is serialized and returned

delConfig()

POST /system/delConfig

delete a configuration key if an error occurs an exception is serializedsetConfig and returned

Parameters:

key – configuration key name

Returns:

a json result with the deleted value

Raises:

Exception – if an error occurs an exception is serialized and returned

delPolicy()

POST /system/delPolicy

deletes the specified policy

Parameters:

name – the policy with the given name

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

delProvider()

POST /system/delProvider

delete the specified SMS- and Email-providers

Parameters:

  • name – the name of the SMS or EMail Provider

  • type – the provider type

Returns:

boolean, true if number of deleted config entries is > 0 else False with message in detail

Raises:

Exception – if an error occurs an exception is serialized and returned

delRealm()

POST /system/delRealm

deletes the specified realm

:param realm - the name of the realm to be deleted

Returns:

a json result if deleting the realm was successful

Raises:

Exception – if an error occurs an exception is serialized and returned

delResolver()

POST /system/delResolver

this function deletes an existing resolver All config keys of this resolver get deleted

Parameters:

resolver – the name of the resolver to delete.

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

getConfig()

GET, POST /system/getConfig

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

retrieve value of a defined configuration key, or if no key is given, the complete configuration is returned if an error occurs an exception is serialized and returned

Note

the assumption is, that the access to system/getConfig is only allowed to privileged users

Parameters:

key – generic configuration entry name (optional)

Returns:

a json result with key value or all key + value pairs

Raises:

Exception – if an error occurs an exception is serialized and returned

getDefaultRealm()

GET, POST /system/getDefaultRealm

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

return the default realm

Returns:

a json description of the default realm

Raises:

Exception – if an error occurs an exception is serialized and returned

getPolicy(id=None)

GET, POST /system/getPolicy

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

retrieve a specified policies

Parameters:

  • id – (optional) Unused (but left for compatibility).

  • realm – (optional) will return all policies in the given realm

  • name – (optional) will only return the policy with the given name

  • action – (optional) will only return the policy with the given action

  • user – (optional) will only return the policy for this user

  • scope – (optional) will only return the policies within the given scope

  • display_inactive – (optional) if set, then also inactive policies will be displayed

Returns:

a json result with the configuration of the specified policies

Raises:

Exception – if an error occurs an exception is serialized and returned

getPolicyDef()

GET, POST /system/getPolicyDef

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

This is a helper function that returns the POSSIBLE policy definitions, that can be used to define your policies.

Parameters:

scope – (optional) if given, the function will only return policy definitions for the given scope.

Returns:

the policy definitions of

  • allowed scopes

  • allowed actions in scopes

  • type of actions

Raises:

Exception – if an error occurs an exception is serialized and returned

getProvider()

GET, POST /system/getProvider

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

get a dict of SMS- and Email-providers

Parameters:

  • name – (optional) the name of the provider in LinOTP

  • type – the type of the provider: SMS or EMail

Returns:

dictionary of provider with its entries as dictionary {‘ProviderA’ : { ‘Timeout’: ‘100’, …}

Raises:

Exception – if an error occurs an exception is serialized and returned

getProviderDef()

GET, POST /system/getProviderDef

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

get the definition of the specified provider - used for automatic rendering

Parameters:

  • type – (required) the provider type

  • class – (optional) the specific class definition or the parent class definition if not specified

Returns:

dictionary with the class as key and the parameters with their types as dictionaries

Raises:

Exception – if an error occurs an exception is serialized and returned

getRealms()

GET, POST /system/getRealms

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

returns all realm definitinos as a json result.

Note

Either the admin is allowed by the policy scope=system, action=read or he is allowed in scope=admin for some realms. If he does not have the system-read-right, then he will only see the realms, he is admin of.

Params realm:

(optional) a realm name

Returns:

a json result with a list of Realms

Raises:

Exception – if an error occurs an exception is serialized and returned

getResolver()

GET, POST /system/getResolver

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

this function retrieves the definition of the resolver

Parameters:

resolver – the name of the resolver

Returns:

a json result with the configuration of a specified resolver

Raises:

Exception – if an error occurs an exception is serialized and returned

getResolvers()

GET, POST /system/getResolvers

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

returns a json list of all useridresolvers

Returns:

a json result with a list of all available resolvers

Raises:

Exception – if an error occurs an exception is serialized and returned

getSupportInfo()

GET, POST /system/getSupportInfo

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

return the support status, which is community support by default or the support subscription info, which could be the old license

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

importPolicy()

POST /system/importPolicy

import policies from a file.

Parameters:

file – (mandatory) The policy file in the POST request

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

isSupportValid()

GET, POST /system/isSupportValid

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

verifies the support license status

if ok

status and value in response are both true

else

value is false and the detail is returned as detail in the response

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

policies_flexi()

GET, POST /system/policies_flexi

Deprecated since version 3.2: Requests using HTTP POST method (because it is only reading data). This endpoint will only be available via HTTP GET method in the future.

This function is used to fill the policies tab

Unlike the complex /system/getPolcies function, it only returns a simple array of the tokens.

Parameters:

  • name –

  • realm –

  • scope –

  • sortname –

  • sortorder –

  • page –

  • psize –

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

setConfig()

POST /system/setConfig

set a configuration key or a set of configuration entries

parameter could either be in the form key=..&value=.. or as a set of generic keyname=value pairs.

Note

In case of key-value pairs the type information could be provided by an additional parameter with same keyname with the postfix “.type”. Value could then be ‘password’ to trigger the storing of the value in an encrypted form

Parameters:

  • key – configuration entry name

  • value – configuration value

  • type – type of the value: int or string/text or password password will trigger to store the encrypted value

  • description – additional information for this config entry

or

Parameters:

pairs (key-value) – pair of &keyname=value pairs

Returns:

a json result with a boolean “result”: true

Raises:

Exception – if an error occurs an exception is serialized and returned

setDefault()

POST /system/setDefault

define default settings for tokens

These default settings are used when new tokens are generated. The default settings will not affect already enrolled tokens.

Parameters:

  • DefaultMaxFailCount –

    • Default value for the maximum allowed authentication failures

  • DefaultSyncWindow –

    • Default value for the synchronization window

  • DefaultCountWindow –

    • Default value for the counter window

  • DefaultOtpLen –

    • Default value for the OTP value length - usually 6 or 8

  • DefaultResetFailCount –

    • Default value, if the FailCounter should be reset on successful authentication [True|False]

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

setDefaultProvider()

POST /system/setDefaultProvider

set the specified provider (SMS- and Email) as default

Parameters:

  • name – the name of the SMS or EMail Provider

  • type – the provider type

Returns:

boolean, true if number of deleted config entries is > 0 else False with message in detail

Raises:

Exception – if an error occurs an exception is serialized and returned

setDefaultRealm()

POST /system/setDefaultRealm

set the given realm to the default realm

Parameters:

realm – the name of the realm, that should be the default realm

Returns:

a json result with a list of Realms

Raises:

Exception – if an error occurs an exception is serialized and returned

setPolicy()

POST /system/setPolicy

Stores a policy that define ACL or behaviour of several different

actions in LinOTP. The policy is stored as configuration values like this:

Policy.<NAME>.action
Policy.<NAME>.scope
Policy.<NAME>.realm
Parameters:

  • name – name of the policy

  • action – which action may be executed

  • scope – selfservice

  • realm – This polcy holds for this realm

  • user – (optional) This polcy binds to this user

  • time – (optional) on which time does this policy hold

  • client – (optional) for which requesting client this should be:

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

setProvider()

POST /system/setProvider

creates or updates SMS- and Email-provider

Parameters:

  • name – the name of the provider in LinOTP

  • type – the type of the provider [email, sms]

  • class – the name of the provider

  • config – the configuration for this provider

  • timeout – the timeout

Returns:

jsom document with value True or False with message in detail

Raises:

Exception – if an error occurs an exception is serialized and returned

setRealm()

POST /system/setRealm

define a realm with the given useridresolvers

Parameters:

  • realm – name of the realm

  • resolvers – comma separated list of resolvers, that should be in this realm

Returns:

a json result with a list of Realms

Raises:

Exception – if an error occurs an exception is serialized and returned

setResolver()

POST /system/setResolver

creates or updates a useridresolver

Parameters:

  • name – the name of the resolver

  • type – the type of the resolver [ldapsersolver, sqlresolver]

for LDAP resolver: :param LDAPURI: :param LDAPBASE: :param BINDDN: :param BINDPW: :param TIMEOUT: :param SIZELIMIT: :param LOGINNAMEATTRIBUTE: :param LDAPSEARCHFILTER: :param LDAPFILTER: :param USERINFO: :param NOREFERRALS: - True|False

for SQL resolver: :param Database: :param Driver: :param Server: :param Port: :param User: :param Password: :param Table: :param Map:

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

setSupport()

POST /system/setSupport

hook to load a support subscription file

receives the data with a form post file upload and installes it after license verification

Parameters:

format – the response format, either xml/htmll or jsom

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

setupSecurityModule()

POST /system/setupSecurityModule

start the pool of security modules

Parameters:

hsm_id – the id for the hsm (mostly the slot id)

Returns:

a json result with a boolean status and request result

Raises:

Exception – if an error occurs an exception is serialized and returned

testProvider()

POST /system/testProvider

if the provider has a test interface, the provider test is run

Parameters:

name – required - the name of the provider in LinOTP

Returns:

dictionary of provider with its entries as dictionary {‘ProviderA’ : { ‘Timeout’: ‘100’, …}

Raises:

Exception – if an error occurs an exception is serialized and returned