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:

privacyidea.lib.token.check_user_pass()

privacyidea.lib.token.check_token_list()

privacyidea.lib.tokenclass.TokenClass.authenticate()

privacyidea.lib.tokenclass.TokenClass.check_pin()

privacyidea.lib.tokenclass.TokenClass.check_otp()

In case if authenticating a serial number:

privacyidea.lib.token.check_serial_pass()

privacyidea.lib.token.check_token_list()

privacyidea.lib.tokenclass.TokenClass.authenticate()

privacyidea.lib.tokenclass.TokenClass.check_pin()

privacyidea.lib.tokenclass.TokenClass.check_otp()

POST /validate/offlinerefill¶

For HOTP token, this endpoint will return the amount of offline OTP values so that the client has the defined count, which is why the last pass is required. For WebAuthn/Passkey, this endpoint will return nothing specific. Every response contains the serial and a new refilltoken. Returns an error in case the token has been unmarked for offline use or if the refilltoken is incorrect.

Parameters:

serial – The serial number of the token, that should be refilled.
refilltoken – The authorization token, that allows refilling.
pass – The last password (or password+OTP) entered by the user. For WebAuthn/Passkey, the value should be empty (“”).

Return:

Hashed OTP values (HOTP) or nothing (WebAuthn/Passkey). Returns an error in case the token has been unmarked for offline use or if the refilltoken is incorrect (out of sync).

GET /validate/samlcheck¶

GET /validate/radiuscheck¶

GET /validate/check¶

Important

The /validate/samlcheck endpoint will be deprecated in v3.12

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

POST /validate/samlcheck¶

POST /validate/radiuscheck¶

POST /validate/check¶

Important

The /validate/samlcheck endpoint will be deprecated in v3.12

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

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

GET /validate/initialize¶: Start an authentication by requesting a challenge for a token type. Currently, supports only type passkey :jsonparam type: The type of the token, for which a challenge should be created.

POST /validate/initialize¶: Start an authentication by requesting a challenge for a token type. Currently, supports only type passkey :jsonparam type: The type of the token, for which a challenge should be created.