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 auser
is required to authenticate. The PIN and OTP value is sent in the parameterpass
.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 auser
is required to authenticate. The PIN and OTP value is sent in the parameterpass
.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" }