linotp.controllers.userservice module

userservice controller -

This is the controller for the user self service interface, where an authenitcated users can manage their own tokens

There are three types of requests

  • the context requests: before, context

  • the auth requests: auth, userinfo

  • the admin requests

At least all admin request must provide the auth cookie and the username - the auth cookie is verified by decryption - the username is checked for valid policy acceptance

Remarks:

  • the userinfo request could use the cookie check as it is running after the authorization request, but no policy definition is required

  • the context request might as well run for an authenticated user, thus auth request but no policy check

exception linotp.controllers.userservice.UserNotFound

Bases: Exception

class linotp.controllers.userservice.UserserviceController(name, install_name='', **kwargs)

Bases: BaseController

the interface from the service into linotp to execute the actions for the user in the scope of the selfservice

after the login, the selfservice user gets an auth cookie, which states that he already has been authenticated. This cookie is provided on every request during which the auth_cookie and session is verified

activateocratoken()

POST /userservice/activateocratoken

activateocratoken - called from the selfservice web ui to activate the OCRA token

Parameters

  • type – ‘ocra2’

  • serial – serial number of the token

  • activationcode – the calculated activation code

Returns

dict about the token { ‘activate’: True, ‘ocratoken’ : {

’url’ : url, ‘img’ : ‘<img />’, ‘label’ : “%s@%s” % (g.authUser.login,

g.authUser.realm),

’serial’ : serial,

} }

Raises

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

assign()

POST /userservice/assign

This is the internal assign function that is called from within the self service portal

Parameters

  • serial – the token serial

  • description – an optional description

  • pin – the new token pin

Returns

a json result with a boolean status and request result

Raises

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

auth()

GET, POST /userservice/auth

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

user authentication for example to the remote selfservice

Parameters

  • login – login name of the user normaly in the user@realm format

  • realm – the realm of the user

  • password – the password for the user authentication which is base32 encoded to seperate the os_passw:pin+otp in case of mfa_login

Returns

{result : {value: bool} }

Raises

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

context()

GET, POST /userservice/context

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 the authentication to self service If you want to do ANYTHING with selfservice, you need to be authenticated. The _before_ is executed before any other function in this controller.

Returns

a json result with a boolean status and request result

Raises

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

delete()

POST /userservice/delete

This is the internal delete token function that is called from within the self service portal. The user is only allowed to delete token, that belong to him.

Parameters

serial – the serial number of the token

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 /userservice/disable

disables a token

as this is a controller method, the parameters are taken from BaseController.request_params

Parameters

  • serial – serial number of the token *required

  • user – username in format user@realm *required

Returns

a linotp json doc with result {u’status’: True, u’value’: 2}

enable()

POST /userservice/enable

enables a token or all tokens of a user

as this is a controller method, the parameters are taken from BaseController.request_params

Parameters

  • serial – serial number of the token *required

  • user – username in format user@realm *required

Returns

a linotp json doc with result {u’status’: True, u’value’: 2}

enroll()

POST /userservice/enroll

Enroll a token.

Note

Depending on the token type more parameters have to be provided as http parameters

Parameters

  • type – one of (hmac, totp, pw, …)

  • serial – a suggested serial number

  • prefix – a prefix for the serial number

  • description – an optional description for the token

  • otppin – the pin for the token

Returns

a json result with a boolean status and request result

Raises

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

finishocra2token()

POST /userservice/finishocra2token

finishocra2token - called from the selfservice web ui to finish

the OCRA2 token to run the final check_t for the token

Parameters

  • passw – the calculated verificaton otp

  • transactionid – the transactionid

Returns

dict about the token

Raises

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

getSerialByOtp()

GET, POST /userservice/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 This method only searches tokens in the realm of the user and tokens that are not assigned!

Parameters

  • otp – (required) Will search for the token, that produces this OTP value

  • type – (optional) will only search in tokens of type

Returns

a json result with a boolean status and serial in the result

Raises

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

getmultiotp()

GET, POST /userservice/getmultiotp

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.

Using this function the user may receive OTP values for his own tokens.

Parameters

count – number of otp values to return

Returns

a json result with a boolean status and request result

Raises

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

history()

GET, POST /userservice/history

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 returns the list of the tokenactions of this user It returns the audit information for the given search pattern

key, value pairs as search patterns.

or: Usually the key=values will be locally AND concatenated.

it a parameter or=true is passed, the filters will be OR concatenated.

The Flexigrid provides us the following parameters:

(‘page’, u‘1’), (‘rp’, u‘100’), (‘sortname’, u’number’), (‘sortorder’, u’asc’), (‘query’, u’‘), (‘qtype’, u’serial’)]

Parameters

  • page –

  • rp –

  • sortname –

  • sortorder –

  • query –

Returns

a json result with a boolean status and request result

Raises

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

jwt_exempt = True
login()

GET, POST /userservice/login

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

user authentication for example to the remote selfservice

Parameters

  • login – login name of the user normaly in the user@realm format

  • realm – the realm of the user

  • password – the password for the user authentication

  • otp – optional the otp

Returns

{result : {value: bool} }

Raises

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

logout()

hook for the auth, which deletes the cookies of the current session

Returns

a json result with a boolean status and request result

Raises

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

pre_context()

GET, POST /userservice/pre_context

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 the authentication to self service If you want to do ANYTHING with selfservice, you need to be authenticated. The _before_ is executed before any other function in this controller.

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 /userservice/reset

This internally resets the failcounter of the given token.

Parameters

serial – the serial number of the token

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 /userservice/resync

This is the internal resync function that is called from within the self service portal

Parameters

  • serial – the serial number of the token

  • otp1 – the first otp for the sequence

  • otp2 – the second otp for the sequence

Returns

a json result with a boolean status and request result

Raises

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

setdescription()

POST /userservice/setdescription

sets a description for a token, provided the setDescription policy is set.

as this is a controller method, the parameters are taken from BaseController.request_params

Parameters

  • serial – serial number of the token *required

  • description – string containing a new description for the token

Returns

a linotp json doc with result {‘status’: True, ‘value’: True}

Raises

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

setmpin()

POST /userservice/setmpin

When the user hits the set pin button, this function is called.

Parameters

  • serial – the serial number of the token

  • pin – the pin for the 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 /userservice/setpin

When the user hits the set pin button, this function is called.

Parameters

  • serial – the serial number of the token

  • userpin – the pin for the token

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 /userservice/unassign

This is the internal unassign function that is called from within the self service portal. The user is only allowed to unassign token, that belong to him.

Parameters

serial – the serial number of the token

Returns

a json result with a boolean status and request result

Raises

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

userinfo()

GET, POST /userservice/userinfo

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.

hook for the auth, which requests additional user info

Returns

a json result with a boolean status and request result

Raises

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

usertokenlist()

GET, POST /userservice/usertokenlist

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 returns a tokenlist as html output

Parameters

active – (optional) True or False - should only active or inactive tokens be returned default is to show both

Returns

a tokenlist as html output

Raises

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

verify()

GET, POST /userservice/verify

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

verify a token, identified by a serial number

after a successful authentication and a valid session, the idenitfied user can verify his enrolled tokens. To verify the token, the token serial number is used.

for direct authenticating tokens like hmac and totp, the parameter otp is required:

a valid verification request example would be:

replied by the usual /validate/check json response

{
“jsonrpc”: “2.XX”,
“result”: {

“status”: true, “value”: true

}, “version”: “LinOTP 2.XX”, “id”: 1

}

Parameters

  • serial –

  • transactionid –

  • otp –

  • session –

Returns

a json result with a boolean status and request result

Raises

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

webprovision()

POST /userservice/webprovision

This function is called, when the create OATHtoken button is hit. This is used for web provisioning. See:

in param:
type: valid values are “oathtoken” and “googleauthenticator” and

“googleauthenticator_time”

description: string containing a description for the token

It returns the data and the URL containing the HMAC key

Parameters

  • type – one of [oathtoken, googleauthenticator, googleauthenticator_time, ocra2]

  • description – a dicrption which might be set for the token

  • serial – (optional) a serial number could be sugggested

Returns

a json result with a boolean status and request result

Raises

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

linotp.controllers.userservice.add_and_delete_cookies(response)

Given a Response object, add or delete cookies as per the g.cookies_to_delete and g.cookies variables.

linotp.controllers.userservice.get_auth_user(request)

retrieve the authenticated user either from selfservice or userservice api / remote selfservice

Parameters

request – the request object

Returns

tuple of (authentication type and authenticated user and authentication state)

in the development environment where we run in debug mode there is probaly no https defined. So we switch secure cookies off. this is done in the settings.py

linotp.controllers.userservice.sendResult(response_proxy, obj, id=1, opt=None, status=True)

extend the standard sendResult to handle cookies

linotp.controllers.userservice.unauthorized(response_proxy, exception, status=401)

extend the standard sendResult to handle cookies