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 a user name and or a serial 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 be false.
{"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 a user name and or a serial 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 be false.
{"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/radiuscheck

check the authentication for a user or a serial number. Either a serial or a user is required to authenticate. The PIN and OTP value is sent in the parameter pass. In case of successful authentication it returns result->value: true.

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 a user is required to authenticate. The PIN and OTP value is sent in the parameter pass. In case of successful authentication it returns result->value: true.

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 a user is required to authenticate. The PIN and OTP value is sent in the parameter pass. In case of successful authentication it returns result->value: true.

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 a user is required to authenticate. The PIN and OTP value is sent in the parameter pass. In case of successful authentication it returns result->value: true.

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.