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/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" }