13.1.1.3. Validate endpoints

This module contains the REST API for doing authentication. The methods are tested in the file tests/test_api_validate.py

Authentication is either done by providing a username and a password or a serial number and a password.

Authentication workflow

Authentication workflow is like this:

In case of authenticating a user:

  • lib/token/check_user_pass (user, passw, options)
  • lib/token/check_token_list(list, passw, user, options)
  • lib/tokenclass/authenticate(pass, user, options)
  • lib/tokenclass/check_pin(pin, user, options)
  • lib/tokenclass/check_otp(otpval, options)

IN case if authenitcating a serial number:

  • lib/token/check_serial_pass(serial, passw, options)
  • lib/token/check_token_list(list, passw, user, options)
  • lib/tokenclass/authenticate(pass, user, options)
  • lib/tokenclass/check_pin(pin, user, options)
  • lib/tokenclass/check_otp(otpval, options)
GET /validate/samlcheck

Authenticate the user and return the SAML user information.

Parameters:
  • user – The loginname/username of the user, who tries to authenticate.
  • realm – The realm of the user, who tries to authenticate. If the realm is omitted, the user is looked up in the default realm.
  • pass – The password, that consists of the OTP PIN and the OTP value.
Return:

a json result with a boolean “result”: true

Example response for a successful authentication:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "detail": {
     "message": "matching 1 tokens",
     "serial": "PISP0000AB00",
     "type": "spass"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": {"auth": true,
               "username: <loginname>,
               "realm": ....,
               "surname": ....,
               "givenname": .....,
               "mobile": ....,
               "phone": ....,
               "email": ....
     }
   },
   "version": "privacyIDEA unknown"
 }
POST /validate/samlcheck

Authenticate the user and return the SAML user information.

Parameters:
  • user – The loginname/username of the user, who tries to authenticate.
  • realm – The realm of the user, who tries to authenticate. If the realm is omitted, the user is looked up in the default realm.
  • pass – The password, that consists of the OTP PIN and the OTP value.
Return:

a json result with a boolean “result”: true

Example response for a successful authentication:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "detail": {
     "message": "matching 1 tokens",
     "serial": "PISP0000AB00",
     "type": "spass"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": {"auth": true,
               "username: <loginname>,
               "realm": ....,
               "surname": ....,
               "givenname": .....,
               "mobile": ....,
               "phone": ....,
               "email": ....
     }
   },
   "version": "privacyIDEA unknown"
 }
GET /validate/check

check the authentication for a user or a serial number. Either a serial or a user is required to authenticate. The PIN and OTP value is sent in the parameter pass.

Parameters:
  • serial – The serial number of the token, that tries to authenticate.
  • user – The loginname/username of the user, who tries to authenticate.
  • realm – The realm of the user, who tries to authenticate. If the realm is omitted, the user is looked up in the default realm.
  • pass – The password, that consists of the OTP PIN and the OTP value.
  • transaction_id – The transaction ID for a response to a challenge request
  • state – The state ID for a response to a challenge request
Return:

a json result with a boolean “result”: true

Example response for a successful authentication:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "detail": {
     "message": "matching 1 tokens",
     "serial": "PISP0000AB00",
     "type": "spass"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": true
   },
   "version": "privacyIDEA unknown"
 }
POST /validate/check

check the authentication for a user or a serial number. Either a serial or a user is required to authenticate. The PIN and OTP value is sent in the parameter pass.

Parameters:
  • serial – The serial number of the token, that tries to authenticate.
  • user – The loginname/username of the user, who tries to authenticate.
  • realm – The realm of the user, who tries to authenticate. If the realm is omitted, the user is looked up in the default realm.
  • pass – The password, that consists of the OTP PIN and the OTP value.
  • transaction_id – The transaction ID for a response to a challenge request
  • state – The state ID for a response to a challenge request
Return:

a json result with a boolean “result”: true

Example response for a successful authentication:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "detail": {
     "message": "matching 1 tokens",
     "serial": "PISP0000AB00",
     "type": "spass"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": true
   },
   "version": "privacyIDEA unknown"
 }