PingDirectory API Reference

Authentication

The PingDirectory REST API supports a top-level authenticate endpoint used to authenticate users.

PingDirectory version 10 or higher is required to use the authenticate endpoint.

In most cases, requests sent to the authenticate endpoint will not require and should not include an Authorization header. The only exception to this would be if the request is attempting to use a control that is only available to authorized users. If the request does include an Authorization header, then it must be validated and used to identify the associated user.

Supported credential types

In an authenticate request, the credentials element must be a JSON object with a set of credentials for the desired type of authentication. All types of authentication must include an authenticationType field in the credentials object that specifies what type of authentication to use. The following authenticationType values are supported:

  • password

    The password authentication type identifies a user with either a username or a DN and only uses a static password as the credentials. The following additional fields are allowed in the credentials object:

    • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • staticPassword — A mandatory string field whose value is the static password for the target user.

  • passwordPlusTOTP

    The passwordPlusTOTP authentication type identifies a user with either a username or a DN and uses both a static password and a time-based one-time password (TOTP) as the credentials. For TOTP shared secret management, refer to Generate TOTP shared secret and Revoke TOTP shared secret. The following additional fields are allowed in the credentials object:

    • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • staticPassword — A mandatory string field whose value is the static password for the target user.

    • totp — A mandatory string field whose value is the time-based one-time password for the target user.

  • passwordPlusDeliveredOTP

    The passwordPlusDeliveredOTP authentication type identifies a user with either a username or a DN and uses both a static password and a one-time password that has been delivered to the user through a method like email or SMS. The one-time password will be valid for a limited period of time, and it will only be valid for a single authentication attempt. This authentication type uses the deliver one-time password extended operation.

    Once the deliver one-time password extended request has been used and the one-time password has been generated and delivered to the user, the authenticate endpoint can be used to authenticate with that one-time password. The following additional fields are allowed in the credentials object:

    • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • otp — A mandatory string field whose value is the one-time password that was delivered to the target user.

  • passwordPlusYubiKeyOTP

    The passwordPlusYubiKeyOTP authentication type identifies a user with either a username or a DN and uses both a static password and one-time password generated by a YubiKey device as the credentials. For information on YubiKey device management, refer to Register YubiKey OTP device and Deregister YubiKey OTP device. The following additional fields are allowed in the credentials object:

    • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

    • staticPassword — A mandatory string field whose value is the static password for the target user.

    • otp — A mandatory string field whose value is the one-time password generated by the YubiKey device.