Table of contents
  1. 1. The Authentication Process
    1. 1.1. Notes

(Version 7+)

When authenticating a user, for which Two-Factor is enabled, use the following process.

The Authentication Process

  1. Client sends a Resource Owner Grant authorization request to the OAuth token endpoint
    • [domain]:[port]/OAuth2/Token
    • POST data (Form URL encoded)
      • "grant_type" equal to "password"
      • "username"
      • "password"
  2. If the response is 200 (OK) then the content of the reponse will be JSON containing the bearer token and expiry
    • "token_type"
    • "access_token"
    • "refresh_token" (not currenly implemented)
    • "expiry"
  3. If the reponse is an error code then the content of the reponse will be JSON containing an explaination of the error
    • "error"
    • "error_description"
  4. The headers of the reponse should be examined for X-Pleasant-OTP and X-Pleasant-OTP-Provider values
    • X-Pleasant-OTP should contain "required"
      • If this header is not present then the error was not related to Two-Factor Authentication
    • X-Pleasant-OTP-Provider will contain the identifier for the two-factor provider token expected
      • The user's default Two-Factor Provider is used, if a user does not have a default selected then the first enabled Provider is used
  5. Collect the Two-Factor token and resubmit
    • As above, except addtional headers must be set on the request
    • X-Pleasant-OTP must be the value of the two-factor token
    • X-Pleasant-OTP-Provider must be the value that was returned in the error response
  6. The server will respond with a standard success or error response (as above)
    • The server will NOT respond with a Two-Factor error response if the X-Pleasant-OTP-Provider header is included in the request


It is possible to bypass the 2-step authentication, however the following conditions must be met:

  1. The client must know ahead of time the value of the Two-Factor Provider identifier for the X-Pleasant-OTP-Provider header
  2. The User (and the User's Policy) must have the intended Two-Factor Provider correctly configured
  3. The Two-Factor Provider must not be one that sends a message to the user via a Back Channel (such as SMS or email)

If these 3 conditions are met, then the token can be collected at the same time as the user's name and password and all values may be submitted in a single request. It is recommended to only do this in custom software that has a specific Two-Factor Configuration requirement.

Tag page
You must login to post a comment.