15.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:
In case if authenitcating a serial number:
-
GET
/validate/triggerchallenge
¶ An administrator can call this endpoint if he has the right of
triggerchallenge
(scope: admin). He can pass auser
name and or aserial
number. privacyIDEA will trigger challenges for all native challenges response tokens, possessed by this user or only for the given serial number.The request needs to contain a valid PI-Authorization header.
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.
- serial – The serial number of the token.
Return: a json result with a “result” of the number of matching challenge response tokens
Example response for a successful triggering of challenge:
{"jsonrpc": "2.0", "signature": "1939...146964", "detail": {"transaction_ids": ["03921966357577766962"], "messages": ["Enter the OTP from the SMS:"], "threadid": 140422378276608}, "versionnumber": "unknown", "version": "privacyIDEA unknown", "result": {"status": true, "value": 1}, "time": 1482223663.517212, "id": 1}
Example response for response, if the user has no challenge token:
{"detail": {"messages": [], "threadid": 140031212377856, "transaction_ids": []}, "id": 1, "jsonrpc": "2.0", "result": {"status": true, "value": 0}, "signature": "205530282...54508", "time": 1484303812.346576, "version": "privacyIDEA 2.17", "versionnumber": "2.17"}
- Example response for a failed triggering of a challenge. In this case
- the
status
will befalse
.{"detail": null, "id": 1, "jsonrpc": "2.0", "result": {"error": {"code": 905, "message": "ERR905: The user can not be found in any resolver in this realm!"}, "status": false}, "signature": "14468...081555", "time": 1484303933.72481, "version": "privacyIDEA 2.17"}
-
POST
/validate/triggerchallenge
¶ An administrator can call this endpoint if he has the right of
triggerchallenge
(scope: admin). He can pass auser
name and or aserial
number. privacyIDEA will trigger challenges for all native challenges response tokens, possessed by this user or only for the given serial number.The request needs to contain a valid PI-Authorization header.
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.
- serial – The serial number of the token.
Return: a json result with a “result” of the number of matching challenge response tokens
Example response for a successful triggering of challenge:
{"jsonrpc": "2.0", "signature": "1939...146964", "detail": {"transaction_ids": ["03921966357577766962"], "messages": ["Enter the OTP from the SMS:"], "threadid": 140422378276608}, "versionnumber": "unknown", "version": "privacyIDEA unknown", "result": {"status": true, "value": 1}, "time": 1482223663.517212, "id": 1}
Example response for response, if the user has no challenge token:
{"detail": {"messages": [], "threadid": 140031212377856, "transaction_ids": []}, "id": 1, "jsonrpc": "2.0", "result": {"status": true, "value": 0}, "signature": "205530282...54508", "time": 1484303812.346576, "version": "privacyIDEA 2.17", "versionnumber": "2.17"}
- Example response for a failed triggering of a challenge. In this case
- the
status
will befalse
.{"detail": null, "id": 1, "jsonrpc": "2.0", "result": {"error": {"code": 905, "message": "ERR905: The user can not be found in any resolver in this realm!"}, "status": false}, "signature": "14468...081555", "time": 1484303933.72481, "version": "privacyIDEA 2.17"}
-
POST
/validate/offlinerefill
¶ This endpoint allows to fetch new offline OTP values for a token, that is already offline. According to the definition it will send the missing OTP values, so that the client will have as much otp values as defined.
Parameters: - serial – The serial number of the token, that should be refilled.
- refilltoken – The authorization token, that allows refilling.
- pass – the last password (maybe password+OTP) entered by the user
Return:
-
GET
/validate/radiuscheck
¶ 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
. In case of successful authentication it returnsresult->value: true
.In case of a challenge response authentication a parameter
exception=1
can be passed. This would result in a HTTP 500 Server Error response if an error occurred during sending of SMS or Email.In case
/validate/radiuscheck
is requested, the responses are modified as follows: A successful authentication returns an empty HTTP 204 response. An unsuccessful authentication returns an empty HTTP 400 response. Error responses are the same responses as for the/validate/check
endpoint.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.
- otponly – If set to 1, only the OTP value is verified. This is used in the management UI. Only used with the parameter serial.
- 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 Validation Request:
POST /validate/check HTTP/1.1 Host: example.com Accept: application/json user=user realm=realm1 pass=s3cret123456
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" }
Example response for this first part of a challenge response authentication:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "serial": "PIEM0000AB00", "type": "email", "transaction_id": "12345678901234567890", "multi_challenge: [ {"serial": "PIEM0000AB00", "transaction_id": "12345678901234567890", "message": "Please enter otp from your email"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS"} ] }, "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": false }, "version": "privacyIDEA unknown" }
In this example two challenges are triggered, one with an email and one with an SMS. The application and thus the user has to decide, which one to use. They can use either.
Note
All challenge response tokens have the same transaction_id in this case.
-
POST
/validate/radiuscheck
¶ 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
. In case of successful authentication it returnsresult->value: true
.In case of a challenge response authentication a parameter
exception=1
can be passed. This would result in a HTTP 500 Server Error response if an error occurred during sending of SMS or Email.In case
/validate/radiuscheck
is requested, the responses are modified as follows: A successful authentication returns an empty HTTP 204 response. An unsuccessful authentication returns an empty HTTP 400 response. Error responses are the same responses as for the/validate/check
endpoint.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.
- otponly – If set to 1, only the OTP value is verified. This is used in the management UI. Only used with the parameter serial.
- 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 Validation Request:
POST /validate/check HTTP/1.1 Host: example.com Accept: application/json user=user realm=realm1 pass=s3cret123456
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" }
Example response for this first part of a challenge response authentication:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "serial": "PIEM0000AB00", "type": "email", "transaction_id": "12345678901234567890", "multi_challenge: [ {"serial": "PIEM0000AB00", "transaction_id": "12345678901234567890", "message": "Please enter otp from your email"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS"} ] }, "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": false }, "version": "privacyIDEA unknown" }
In this example two challenges are triggered, one with an email and one with an SMS. The application and thus the user has to decide, which one to use. They can use either.
Note
All challenge response tokens have the same transaction_id in this case.
-
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": {"attributes": { "username": "koelbel", "realm": "themis", "mobile": null, "phone": null, "myOwn": "/data/file/home/koelbel", "resolver": "themis", "surname": "Kölbel", "givenname": "Cornelius", "email": null}, "auth": true} }, "version": "privacyIDEA unknown" }
The response in value->attributes can contain additional attributes (like “myOwn”) which you can define in the LDAP resolver in the attribute mapping.
-
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": {"attributes": { "username": "koelbel", "realm": "themis", "mobile": null, "phone": null, "myOwn": "/data/file/home/koelbel", "resolver": "themis", "surname": "Kölbel", "givenname": "Cornelius", "email": null}, "auth": true} }, "version": "privacyIDEA unknown" }
The response in value->attributes can contain additional attributes (like “myOwn”) which you can define in the LDAP resolver in the attribute mapping.
-
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
. In case of successful authentication it returnsresult->value: true
.In case of a challenge response authentication a parameter
exception=1
can be passed. This would result in a HTTP 500 Server Error response if an error occurred during sending of SMS or Email.In case
/validate/radiuscheck
is requested, the responses are modified as follows: A successful authentication returns an empty HTTP 204 response. An unsuccessful authentication returns an empty HTTP 400 response. Error responses are the same responses as for the/validate/check
endpoint.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.
- otponly – If set to 1, only the OTP value is verified. This is used in the management UI. Only used with the parameter serial.
- 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 Validation Request:
POST /validate/check HTTP/1.1 Host: example.com Accept: application/json user=user realm=realm1 pass=s3cret123456
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" }
Example response for this first part of a challenge response authentication:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "serial": "PIEM0000AB00", "type": "email", "transaction_id": "12345678901234567890", "multi_challenge: [ {"serial": "PIEM0000AB00", "transaction_id": "12345678901234567890", "message": "Please enter otp from your email"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS"} ] }, "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": false }, "version": "privacyIDEA unknown" }
In this example two challenges are triggered, one with an email and one with an SMS. The application and thus the user has to decide, which one to use. They can use either.
Note
All challenge response tokens have the same transaction_id in this case.
-
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
. In case of successful authentication it returnsresult->value: true
.In case of a challenge response authentication a parameter
exception=1
can be passed. This would result in a HTTP 500 Server Error response if an error occurred during sending of SMS or Email.In case
/validate/radiuscheck
is requested, the responses are modified as follows: A successful authentication returns an empty HTTP 204 response. An unsuccessful authentication returns an empty HTTP 400 response. Error responses are the same responses as for the/validate/check
endpoint.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.
- otponly – If set to 1, only the OTP value is verified. This is used in the management UI. Only used with the parameter serial.
- 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 Validation Request:
POST /validate/check HTTP/1.1 Host: example.com Accept: application/json user=user realm=realm1 pass=s3cret123456
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" }
Example response for this first part of a challenge response authentication:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "serial": "PIEM0000AB00", "type": "email", "transaction_id": "12345678901234567890", "multi_challenge: [ {"serial": "PIEM0000AB00", "transaction_id": "12345678901234567890", "message": "Please enter otp from your email"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS"} ] }, "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": false }, "version": "privacyIDEA unknown" }
In this example two challenges are triggered, one with an email and one with an SMS. The application and thus the user has to decide, which one to use. They can use either.
Note
All challenge response tokens have the same transaction_id in this case.