14.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 authentication:
{"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}
-
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 authentication:
{"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}
-
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
.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" }
-
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
.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" }