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 authenticating a serial number:

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.

  • 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 be false.

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/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.

  • 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 be false.

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

POST /validate/samlcheck
POST /validate/radiuscheck
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 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.

  • 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.

GET /validate/samlcheck
GET /validate/radiuscheck
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 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.

  • 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.