linotp.controllers.admin module

admin controller - interfaces to administrate LinOTP

class linotp.controllers.admin.AdminController(name, install_name='', **kwargs)

Bases: BaseController, JWTMixin

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()

POST /admin/assign

assigns a token to a user, i.e. a binding between the token and the user is created.

Parameters

  • 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 status and request result

Raises

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

check_serial()

GET, POST /admin/check_serial

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 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

Parameters

serial – the serial to be checked

Returns

a json result with a boolean status and a new suggestion for the serial

Raises

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

checkstatus()

GET, POST /admin/checkstatus

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.

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

Raises

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

copyTokenPin()

POST /admin/copyTokenPin

copies the token pin from one token to another

Parameters

  • from – (required) serial of token from

  • to – (required) serial of token to

Returns

a json result with a boolean status and request result

Raises

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

copyTokenUser()

POST /admin/copyTokenUser

copies the token user from one token to another

Parameters

  • from – (required) serial of token from

  • to – (required) serial of token to

Returns

a json result with a boolean status and request result

Raises

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

disable()

POST /admin/disable

disables a token given by serial or all tokens of a user

Parameters

  • serial – the token serial

  • user – the user for whom all tokens will be disabled

Returns

a json result with a boolean status and request result

Raises

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

enable()

POST /admin/enable

enables a token or all tokens of a user

Parameters

  • serial – (optional), the token serial number

  • user – (optional), will enable all tokens of a user

Returns

a json result with a boolean status and request result

Raises

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

getSerialByOtp()

GET, POST /admin/getSerialByOtp

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.

searches for the token, that generates the given OTP value. The search can be restricted by several critterions

Parameters

  • 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 a boolean status and request result

Raises

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

getTokenOwner()

GET, POST /admin/getTokenOwner

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.

provide the userinfo of the token, which is specified as serial

Parameters

serial – the serial number of the token

Returns

a json result with a boolean status and request result

init()

POST /admin/init

creates a new token.

common arguments:

Parameters

  • otpkey – (required) the hmac Key of the token

  • genkey – (required) =1, if key should be generated. We e:ither need otpkey or genkey

  • keysize – (optional) either 20 or 32. Default is 20

  • serial – (re:quired) 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 – (opt:ional) 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

ocra2 arguments: for generating OCRA2 Tokens type=ocra2 you can specify the following parameters:

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 OCRA2 token the sharedsecret=1 specifies, that you want to generate a shared secret

  • activationcode – (optional) if you are in Step1 of enrolling an OCRA2 token you need to pass the activation code, that was generated in the QRTAN-App

qrtoken arguments: for generating QRTokens type=qr you can specify the

following parameters

Parameters

hashlib – (optional) the hash algorithm used in the mac calculation (sha512, sha256, sha1). default is sha256

Returns

a json result with a boolean status and request result

Raises

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

loadtokens()

POST /admin/loadtokens

loads a whole token file to the server

Parameters

  • file – the file in a post request

  • type – the file type.

  • realm – the target real of the tokens

Returns

a json result with a boolean status and request result

Raises

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

losttoken()

POST /admin/losttoken

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.

Parameters

  • serial – serial of the old token

  • type – (optional) , password, email or sms

  • email – (optional) , email address, to overrule the owner email

  • mobile – (optional) , mobile number, to overrule the owner mobile

Returns

a json result with a boolean status and request result

Raises

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

remove()

POST /admin/remove

deletes either a certain token given by serial or all tokens of a user

Parameters

  • serial –

    • the serial number of the token

  • user – (optional) , will delete all tokens of a user

Returns

a json result with a boolean status and request result

Raises

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

reset()

POST /admin/reset

reset the FailCounter of a Token

Parameters

serial (user or) – to identify the tokens

Returns

a json result with a boolean status and request result

Raises

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

resync()

POST /admin/resync

this function resync the token, if the counter on server side is out of sync with the physical token.

Parameters

  • 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 status and request result

Raises

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

set()

POST /admin/set

this function is used to set many different values of a token.

Parameters

  • 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 – (optional) - 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 status and request result

Raises

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

setPin()

POST /admin/setPin

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!

Parameters

  • serial – (required) the token serial

  • userpin – (optional) store the userpin

  • sopin – (optional) store the sopin

Returns

a json result with a boolean status and request result

Raises

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

setValidity()

POST /admin/setValidity

dedicated backend for setting the token validity for multiple selected tokens.

Parameters

  • tokens[] – the token serials (required)

  • countAuthSuccessMax – the maximum number of allowed successful authentications

  • countAuthMax – the maximum number of allowed successful authentications

  • validityPeriodStart – utc - unix seconds as int

  • validityPeriodEnd – utc - unix seconds as int

Note

the parameter names are the same as with the admin/set while admin/set does not support multiple tokens

Note

if the value is ‘unlimited’ the validity limit will be removed

Returns

json document with the value field containing the serials of the modified tokens

Raises

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

show()

GET, POST /admin/show

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.

displays the list of the available tokens

Parameters

  • 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

  • realm – (optional) alias to the viewrealm

  • 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

  • tokeninfo_format – (optional) if set to “json”, this will be supplied in embedded JSON otherwise, string format is returned with dates in format DD/MM/YYYY TODO

Returns

a json result with a boolean status and request result

Raises

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

testresolver()

POST /admin/testresolver

This method tests a useridresolvers configuration

Parameters

name – the name of the resolver

Returns

a json result with a boolean status and request result

Raises

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

tokenrealm()

POST /admin/tokenrealm

set the realms a token belongs to

Parameters

  • serial – (required) serial number of the token

  • realms – (required) comma seperated list of realms

Returns

a json result with a boolean status and request result

Raises

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

totp_lookup()

GET, POST /admin/totp_lookup

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 information for a past otp value of a TOTP token. Includes, when and how long the given OTP was valid.

Parameters

  • serial – (required) serial number of the token

  • otp – (required) a past OTP value to check

  • window – (optional) the duration to search back from current time. Defaults to “24h”.

Returns

a json result with a boolean status and request result

Raises

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

unassign()

POST /admin/unassign

unassigns a token from a user. i.e. the binding between the token and the user is removed

Parameters

  • serial – (required) - the serial number / identifier of the token

  • user – (- )optional)

Returns

a json result with a boolean status and request result

Raises

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

unpair()

POST /admin/unpair resets a token to its unpaired state

param serial

the serial number of the token

return

a json result with a boolean status and request result

raises Exception

if an error occurs an exception is serialized and returned

userlist()

GET, POST /admin/userlist

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.

lists the user in a realm

Parameters

  • <searchexpr> – will be retrieved from the UserIdResolverClass

  • realm – a realm, which is a collection of resolver configurations

  • resConf – a destinct resolver configuration

  • page – the number of page, which should be retrieved (optional)

  • rp – the number of users per page (optional)

Returns

a json result with a boolean status and request result

Raises

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