16.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 authenticating 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.
type – The tokentype of the tokens, that are taken into account during authentication. Requires authz policy application_tokentype. Is ignored when a distinct serial is given.
- Return
a json result with a “result” of the number of matching challenge response tokens
Example response for a successful triggering of challenge:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "client_mode": "interactive", "message": "please enter otp: , please enter otp: ", "messages": [ "please enter otp: ", "please enter otp: " ], "multi_challenge": [ { "client_mode": "interactive", "message": "please enter otp: ", "serial": "TOTP000026CB", "transaction_id": "11451135673179897001", "type": "totp" }, { "client_mode": "interactive", "message": "please enter otp: ", "serial": "OATH0062752C", "transaction_id": "11451135673179897001", "type": "hotp" } ], "serial": "OATH0062752C", "threadid": 140329819764480, "transaction_id": "11451135673179897001", "transaction_ids": [ "11451135673179897001", "11451135673179897001" ], "type": "hotp" }, "id": 2, "jsonrpc": "2.0", "result": { "status": true, "value": 2 }
Example response for response, if the user has no challenge token:
HTTP/1.1 200 OK Content-Type: application/json { "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
.HTTP/1.1 200 OK Content-Type: application/json { "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.
type – The tokentype of the tokens, that are taken into account during authentication. Requires authz policy application_tokentype. Is ignored when a distinct serial is given.
- Return
a json result with a “result” of the number of matching challenge response tokens
Example response for a successful triggering of challenge:
HTTP/1.1 200 OK Content-Type: application/json { "detail": { "client_mode": "interactive", "message": "please enter otp: , please enter otp: ", "messages": [ "please enter otp: ", "please enter otp: " ], "multi_challenge": [ { "client_mode": "interactive", "message": "please enter otp: ", "serial": "TOTP000026CB", "transaction_id": "11451135673179897001", "type": "totp" }, { "client_mode": "interactive", "message": "please enter otp: ", "serial": "OATH0062752C", "transaction_id": "11451135673179897001", "type": "hotp" } ], "serial": "OATH0062752C", "threadid": 140329819764480, "transaction_id": "11451135673179897001", "transaction_ids": [ "11451135673179897001", "11451135673179897001" ], "type": "hotp" }, "id": 2, "jsonrpc": "2.0", "result": { "status": true, "value": 2 }
Example response for response, if the user has no challenge token:
HTTP/1.1 200 OK Content-Type: application/json { "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
.HTTP/1.1 200 OK Content-Type: application/json { "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" }
- GET /validate/polltransaction/(transaction_id)¶
- GET /validate/polltransaction¶
Given a mandatory transaction ID, check if any non-expired challenge for this transaction ID has been answered. In this case, return true. If this is not the case, return false. This endpoint also returns false if no challenge with the given transaction ID exists.
This is mostly useful for out-of-band tokens that should poll this endpoint to determine when to send an authentication request to
/validate/check
.- JSON Parameters
transaction_id – a transaction ID
- 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/samlcheck¶
- GET /validate/radiuscheck¶
- 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 emptyHTTP 204
response. An unsuccessful authentication returns an emptyHTTP 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.
type – The tokentype of the tokens, that are taken into account during authentication. Requires the authz policy application_tokentype. It is ignored when a distinct serial is given.
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", "client_mode": "interactive"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS", "client_mode": "interactive"} ] }, "id": 2, "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.
The challenges also contain the information of the “client_mode”. This tells the plugin, whether it should display an input field to ask for the OTP value or e.g. to poll for an answered authentication. Read more at Authentication Modes and Client Modes.
Note
All challenge response tokens have the same
transaction_id
in this case.Example response for a successful authentication with
/samlcheck
: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¶
- POST /validate/radiuscheck¶
- 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 emptyHTTP 204
response. An unsuccessful authentication returns an emptyHTTP 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.
type – The tokentype of the tokens, that are taken into account during authentication. Requires the authz policy application_tokentype. It is ignored when a distinct serial is given.
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", "client_mode": "interactive"}, {"serial": "PISM12345678", "transaction_id": "12345678901234567890", "message": "Please enter otp from your SMS", "client_mode": "interactive"} ] }, "id": 2, "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.
The challenges also contain the information of the “client_mode”. This tells the plugin, whether it should display an input field to ask for the OTP value or e.g. to poll for an answered authentication. Read more at Authentication Modes and Client Modes.
Note
All challenge response tokens have the same
transaction_id
in this case.Example response for a successful authentication with
/samlcheck
: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.