Skip to content

SDK Structure Requirements (WIP)

Jump to bottom
Nils Behlen edited this page May 8, 2020 · 1 revision

The SDK is meant to simplify the development of plugins that communicate with PrivacyIDEA. Therefore, all things related to working with the PrivacyIDEA API are put into separate projects (for different languages) which should be self-contained and easy to use.

Configuration

The configuration for PrivacyIDEA is a subset of the configuration that is read from the plugin. The following things are mandatory for the SDK to work:

  • Server URL (hostname and path, optionally port)

The following points can be provided for more functionality

  • Realm default realm / some sort of realm mapping
  • SSL Verification possibility to disable it in testing environments
  • Service Account can be used to trigger challenges directly
  • Token enrollment whether the user should be able to enroll a token and if so which type
  • Polling Intervals for PushToken
  • Logging Bridge to choose destination of log/error messages

Functions

The following functions should be available: Names are not final but should be agreed upon later for uniformity

validateCheck(username, otp, transaction_id) -> Response

The main function that covers most of the use cases. All parameters can be null. Sends the parameters with the respective keys user, pass and transaction_id to endpoint validate/check E.g. POST https://hostname.com/path/to/pi/validate/check?user=username&pass=otp&transaction_id=transaction_id If the transaction_id is null, it can be omitted.

Returns the server response in some way, plain text might be the easiest. In object oriented languages, an object could be more convenient to use.

Error handling could be done by throwing.

pollTransaction(transaction_id) -> boolean / Reponse

Poll for the transaction_id once using the endpoint /validate/polltransaction If this returns true, the authentication has to be finalized (see link below) manually.

asyncPollTransaction(transaction_id, username, callback?) -> Future?

Poll for the transaction_id in a separate thread with a loop.

If the polling returns success, the authentication has to be finalized: https://privacyidea.readthedocs.io/en/latest/tokens/authentication_modes.html?highlight=out%20of%20band#outofband-mode To do that, the username is needed aswell. Invokes the callback / set the future with the result of finalization.

stopPoll() -> _

Stop the polling to avoid leaks.

triggerChallenges(username) -> List(Challenge) / Response

Can only be used if a service account is set. First an authorization token has to be acquired from /auth: POST https://hostname.com/path/to/pi/auth?username=ServiceUsername&password=ServicePassword

Afterwards challenges can be triggered at the endpoint validate/triggerchallenge POST https://hostname.com/path/to/pi/validate/triggerchallenge?user=username

Other

  • All user-entered data that is sent to the server must be URL encoded
Clone this wiki locally