5.2. Administrative Interfaces¶
Note
To every management controller you can add the parameter httperror followed by an HTTP error code. If LinOTP would return HTTP 200/OK with status: false in the JSON response indicating an internal error then LinOTP will instead return a e.g. HTTP 500 error code.
5.2.1. Admin Interface¶
Managing tokens can be performed via an HTTPs Interface just like the authentication via /validate/check and /validate/simplecheck. The main API is located at the controller /admin. There you can find functions like this:
- /admin/init: Enroll token
- /admin/enable: Enable token
- /admin/disable: Disable token
- /admin/show: List tokens
- /admin/delete: Delete tokens
Other controllers are
- /manage: provides the Web UI.
- /system: provides the functions to configure the LinOTP server.
- /license: provides the functions to set and get license information.
- /audit: provides the functions for the audit trail.
5.2.1.1. Orphanced tokens¶
Orphaned tokens are tokens, that are still assigned to the user, but where the user object was deleted from the user database.
Using the method /admin/show you can also view such orphaned tokens by calling the method:
/admin/show?user='/:no%20user%20info:/'
You can also find tokens that have no users or tokens that are assigned to no realm:
/admin/show?user=''
/admin/show?realm=''
5.2.2. Admin Controller¶
- class linotp.controllers.admin.AdminController(*args, **kw)[source]¶
The linotp.controllers are the implementation of the web-API to talk to the LinOTP server. The AdminController is used for administrative tasks like adding tokens to LinOTP, assigning tokens or revoking tokens. The functions of the AdminController are invoked like this
https://server/admin/<functionname>The functions are described below in more detail.
- assign()[source]¶
- method:
- admin/assign
- description:
- assigns a token to a user, i.e. a binding between the token and the user is created.
- arguments:
- serial - required - the serial number / identifier of the token
- user - required - login user name
- pin - optional - the pin of the user pass
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- check_serial()[source]¶
- method
- admin/check_serial
- description:
- This function checks, if a given serial will be unique. It returns True if the serial does not yet exist and new_serial as a new value for a serial, that does not exist, yet
- arguments:
- serial - required- the serial to be checked
- returns:
- a json result with a new suggestion for the serial
- exception:
- if an error occurs an exception is serialized and returned
- checkstatus()[source]¶
show the status either
- of one dedicated challenge
- of all challenges of a token
- of all challenges belonging to all tokens of a user
Parameters: - transactionid/state – the transaction id of the challenge
- serial – serial number of the token - will show all challenges
- user –
Returns: json result of token and challenges
- copyTokenPin()[source]¶
- method:
- admin/copyTokenPin
- description:
- copies the token pin from one token to another
- arguments:
- from - required - serial of token from
- to - required - serial of token to
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- copyTokenUser()[source]¶
- method:
- admin/copyTokenUser
- description:
- copies the token user from one token to another
- arguments:
- from - required - serial of token from
- to - required - serial of token to
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- disable()[source]¶
- method:
- admin/disable
- description:
- disables a token given by serial or all tokens of a user
- arguments:
- serial - optional
- user - optional
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- enable()[source]¶
- method:
- admin/enable
- description:
- enables a token or all tokens of a user
- arguments:
- serial - optional
- user - optional
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- getSerialByOtp()[source]¶
- method:
- admin/getSerialByOtp
- description:
- searches for the token, that generates the given OTP value. The search can be restricted by several critterions
- arguments:
- otp - required. Will search for the token, that produces this OTP value
- type - optional, will only search in tokens of type
- realm - optional, only search in this realm
- assigned - optional. 1: only search assigned tokens, 0: only search unassigned tokens
- returns:
- a json result with the serial
- exception:
- if an error occurs an exception is serialized and returned
- getsession()[source]¶
This generates a session key and sets it as a cookie set_cookie is defined in python-webob:
def set_cookie(self, key, value='', max_age=None, path='/', domain=None, secure=None, httponly=False, version=None, comment=None, expires=None, overwrite=False):
- init()[source]¶
- method:
- admin/init
- description:
- creates a new token.
- arguments:
- otpkey - required - the hmac Key of the token
- genkey - required - =1, if key should be generated. We either need otpkey or genkey
- keysize - optional - either 20 or 32. Default is 20
- serial - required - the serial number / identifier of the token
- description - optional
- pin - optional - the pin of the user pass
- user - optional - login user name
- realm - optional - realm of the user
- type - optional - the type of the token
- tokenrealm - optional - the realm a token should be put into
- otplen - optional - length of the OTP value
- hashlib - optional - used hashlib sha1 oder sha256
- ocra arguments:
for generating OCRA Tokens type=ocra you can specify the following parameters:
- ocrasuite - optional - if you do not want to use the default ocra suite OCRA-1:HOTP-SHA256-8:QA64
- sharedsecret - optional - if you are in Step0 of enrolling an OCRA/QR token the sharedsecret=1 specifies, that you want to generate a shared secret
- activationcode - optional - if you are in Step1 of enrolling an OCRA token you need to pass the activation code, that was generated in the QRTAN-App
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- loadtokens()[source]¶
- method:
- admin/loadtokens
- description:
- loads a whole token file to the server
- arguments:
- file - the file in a post request
- type - the file type.
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- losttoken()[source]¶
- method:
- admin/losttoken
- description:
- creates a new password token and copies the PIN and the user of the old token to the new token. The old token is disabled.
- arguments:
- serial - serial of the old token
- returns:
- a json result with the new serial an the password
- exception:
- if an error occurs an exception is serialized and returned
- remove()[source]¶
- method:
- admin/remove
- description:
- deletes either a certain token given by serial or all tokens of a user
- arguments:
- serial - optional
- user - optional
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- reset()[source]¶
- method:
- admin/reset
- description:
- reset the FailCounter of a Token
- arguments:
- user or serial - to identify the tokens
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- resync()[source]¶
- method:
- admin/resync - resync a token to a new counter
- description:
- this function resync the token, if the counter on server side is out of sync with the physica token.
- arguments:
- serial - serial or user required
- user - s.o.
- otp1 - the next otp to be found
- otp2 - the next otp after the otp1
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- set()[source]¶
- method:
- admin/set
- description:
- this function is used to set many different values of a token.
- arguments:
- serial - optional
- user - optional
- pin - optional - set the OTP PIN
- MaxFailCount - optional - set the maximum fail counter of a token
- SyncWindow - optional - set the synchronization window of the token
- OtpLen - optional - set the OTP Lenght of the token
- CounterWindow - optional - set the counter window (blank presses)
- hashlib - optioanl - set the hashing algo for HMAC tokens. This can be sha1, sha256, sha512
- timeWindow - optional - set the synchronize window for timebased tokens (in seconds)
- timeStep - optional - set the timestep for timebased tokens (usually 30 or 60 seconds)
- timeShift - optional - set the shift or timedrift of this token
- countAuthSuccessMax - optional - set the maximum allowed successful authentications
- countAuthSuccess - optional - set the counter of the successful authentications
- countAuth - optional - set the counter of authentications
- countAuthMax - optional - set the maximum allowed authentication tries
- validityPeriodStart - optional - set the start date of the validity period. The token can not be used before this date
- validityPeriodEnd - optional - set the end date of the validaity period. The token can not be used after this date
- phone - set the phone number for an SMS token
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- setPin()[source]¶
- method:
- admin/set
- description:
- This function sets the smartcard PINs of a eTokenNG OTP. The userpin is used to store the mOTP PIN of mOTP tokens! !!! For setting the OTP PIN, use the function /admin/set!
- arguments:
- serial - required
- userpin - optional: store the userpin
- sopin - optional: store the sopin
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- show()[source]¶
- method:
- admin/show
- description:
- displays the list of the available tokens
- arguments:
- serial - optional: only this serial will be displayed
- user - optional: only the tokens of this user will be displayed. If the user does not exist, linotp will search tokens of users, who contain this substring. TODO: This can be very time consuming an will be changed in the next release to use wildcards.
- filter - optional: takes a substring to search in table token columns
- viewrealm - optional: takes a realm, only the tokens in this realm will be displayed
- sortby - optional: sort the output by column
- sortdir - optional: asc/desc
- page - optional: reqeuest a certain page
- pagesize- optional: limit the number of returned tokens
- user_fields - optional: additional user fields from the userid resolver of the owner (user)
- outform - optional: if set to “csv”, than the token list will be given in CSV
- returns:
- a json result with: { “head”: [], “data”: [ [row1], [row2] .. ] }
- exception:
- if an error occurs an exception is serialized and returned
- testresolver()[source]¶
- method:
- admin/testresolver
- description:
- This method tests a useridresolvers configuration
- arguments:
- type - “LDAP”: depending on the type there are other parameters:
- “SQL”
- LDAP:
- BINDDN
- BINDPW
- LDAPURI
- TIMEOUT
- LDAPBASE
- LOGINNAMEATTRIBUTE
- LDAPSEARCHFILTER
- LDAPFILTER
- USERINFO
- LDAPSEARCHFILTER
- SIZELIMIT
- NOREFERRALS
- CACERTIFICATE
- SQL:
- Driver
- Server
- Port
- Database
- User
- Password
- Table
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- tokenrealm()[source]¶
- method:
- admin/tokenrealm - set the realms a token belongs to
- description:
- sets the realms of a token
- arguments:
- serial - required - serialnumber of the token
- realms - required - comma seperated list of realms
- unassign()[source]¶
- method:
- admin/unassign - remove the assigned user from the token
- description:
- unassigns a token from a user. i.e. the binding between the token and the user is removed
- arguments:
- serial - required - the serial number / identifier of the token
- user - optional
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- userlist()[source]¶
- method:
- admin/userlist - list all users
- description:
- lists the user in a realm
- arguments:
- <searchexpr> - will be retrieved from the UserIdResolverClass
- realm - a realm, which is a collection of resolver configurations
- resConf - a destinct resolver configuration
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
5.2.3. System Controller¶
- class linotp.controllers.system.SystemController(*args, **kw)[source]¶
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()[source]¶
- method:
- system/checkPolicy
- description:
- this function checks if a the given parameter will trigger a policy or not.
- arguments:
- user - the name of the user
- realm - the realm
- scope - the scope
- 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> }
- delConfig()[source]¶
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
- delPolicy()[source]¶
- method:
- system/delPolicy
- description:
- this function deletes the policy with the given name
- arguments:
- name - the policy with the given name
- returns:
- a json result about the delete success
- exception:
- if an error occurs an exception is serialized and returned
- delRealm()[source]¶
- method:
- system/delRealm
- description:
- this function deletes the given realm
- arguments:
- realm - the name of the realm to be deleted
- returns:
- a json result if deleting the realm was successful
- exception:
- if an error occurs an exception is serialized and returned
- delResolver()[source]¶
- method:
- system/delResolver
- description:
- this function deletes an existing resolver All config keys of this resolver get deleted
- arguments:
- resolver - the name of the resolver to delete.
- returns:
- success state
- exception:
- if an error occurs an exception is serialized and returned
- getConfig()[source]¶
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
- remark: 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
- getDefaultRealm()[source]¶
- method:
- system/getDefaultRealm
- description:
- this function returns the default realm
- arguments:
- ./.
- returns:
- a json description of the default realm
- exception:
- if an error occurs an exception is serialized and returned
- getPolicy()[source]¶
- method:
- system/getPolicy
- description:
- this function is used to retrieve the policies that you defined.
- arguments:
realm - (optional) will return all policies in the given realm
name - (optional) will only return the policy with the given name
scope - (optional) will only return the policies within the given scope
- export - (optional) The filename needs to be specified as the third part of the URL like /system/getPolicy/policy.cfg. It
will then be exported to this file.
display_inactive - (optional) if set, then also inactive policies will be displayed
- returns:
- a json result with the configuration of the specified policies
- exception:
- if an error occurs an exception is serialized and returned
- getPolicyDef()[source]¶
- method:
- system/getPolicyDef
- description:
- This is a helper function that returns the POSSIBLE policy definitions, that can be used to define your policies.
- arguments:
- 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
- exception:
- if an error occurs an exception is serialized and returned
- getRealms()[source]¶
- method:
- system/getRealms
- description:
- returns all realm definitinos as a json result.
arguments:
- returns:
- a json result with a list of Realms
- exception:
- if an error occurs an exception is serialized and returned
Either the admin has the policy scope=system, action=read or he is rights 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.
- getResolver()[source]¶
- method:
- system/getResolver
- description:
- this function retrieves the definition of the resolver
- arguments:
- resolver - the name of the resolver
- returns:
- a json result with the configuration of a specified resolver
- exception:
- if an error occurs an exception is serialized and returned
- getResolvers()[source]¶
- method:
- system/getResolvers
- descriptions:
- returns a json list of all useridresolvers
arguments:
- returns:
- a json result with a list of all available resolvers
- exception:
- if an error occurs an exception is serialized and returned
- getSupportInfo()[source]¶
return the support status, which is community support by default or the support subscription info, which could be the old license
- importPolicy()[source]¶
- method:
- system/importPolicy
- description:
- This function is used to import policies from a file.
- arguments:
- file - mandatory: The policy file in the POST request
- policies_flexi()[source]¶
This function is used to fill the policies tab Unlike the complex /system/getPolcies function, it only returns a simple array of the tokens.
- setConfig()[source]¶
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
- setDefault()[source]¶
- method:
- system/set
- description:
- define default settings for tokens. These default settings are used when new tokens are generated. The default settings will not affect already enrolled tokens.
- arguments:
- DefaultMaxFailCount - Default value for the maximum allowed authentication failures DefaultSyncWindow - Default value for the synchronization window DefaultCountWindow - Default value for the coutner window DefaultOtpLen - Default value for the OTP value length – usuall 6 or 8 DefaultResetFailCount - Default value, if the FailCounter should be reset on successful authentication [True|False]
- returns:
- a json result with a boolean
- “result”: true
- exception:
- if an error occurs an exception is serialized and returned
- setDefaultRealm()[source]¶
- method:
- system/setDefaultRealm
- description:
- this function sets the given realm to the default realm
- arguments:
- realm - the name of the realm, that should be the default realm
- returns:
- a json result with a list of Realms
- exception:
- if an error occurs an exception is serialized and returned
- setPolicy()[source]¶
- method:
- system/setPolicy
- description:
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
- arguments:
- 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 success or error
- exception:
- if an error occurs an exception is serialized and returned
- setRealm()[source]¶
- method:
- system/setRealm
- description:
- this function is used to define a realm with the given useridresolvers
- arguments:
- 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
- exception:
- if an error occurs an exception is serialized and returned
- setResolver()[source]¶
- method:
- system/setResolver
- description:
- creates or updates a useridresolver
- arguments:
name - the name of the resolver type - the type of the resolver [ldapsersolver, sqlresolver]
- LDAP:
- LDAPURI LDAPBASE BINDDN BINDPW TIMEOUT SIZELIMIT LOGINNAMEATTRIBUTE LDAPSEARCHFILTER LDAPFILTER USERINFO NOREFERRALS - True|False
- SQL:
- Database Driver Server Port User Password Table Map
- returns:
- a json result with the found value
- exception:
- if an error occurs an exception is serialized and returned
5.2.4. License Controller¶
5.2.5. Session protection¶
Starting with LinOTP 2.4.1 the API provides an additional session protection. This means all functions that change data need to pass an additional session parameter in the URL parameters like this:
If the session is not passed the server will respond with a 401 Not authenticated. To get such a session, the client needs to send a session request:
This will set a cookie in the clients cookie store, which also needs to be passed with every request. Thus the clients needs to pass the cookie and the session parameter. The server will compare these two values and only perform the required action if the session values are the same.
5.2.5.1. Disabling session protection¶
You may disable session protection. Please note that you should not do this when accessing LinOTP with a web browser. You should only disable session protection if you fully understand what you are doing.
In /etc/linotp2/linotp.ini add the following line to the DEFAULT section:
linotpNoSessionCheck = 10.1.2.3, 192.168.0.0/24
You can add any IP address or subnet in CIDR notation seperated by comma.