OAuth Two-Factor Support

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

(New in version 7+)

When logging in with 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.