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 of the policy that allowed this action> }

value{ “allowed””false”,

”info” : <e.g. an error message> }

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 definitions as a json result. :params realm: (optional) a realm name :return:

a json result with a list of Realms

Raises

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

getReportedStatuses()

GET, POST /system/getReportedStatuses

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.

description:

get all reported token_status per realm

Parameters

realms – (optional) specifies the realms for which token status will be returned. Use “*” to get all realms the requesting user has access to including “/:no realm:/”.

Returns

Dict[str, List[str]] of all reported token_status per requested realm.

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 policy holds for this realm

  • user – (optional) This policy 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

json 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 installs it after license verification

Parameters

format – the response format, either xml/html or json

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