Using the Duo API Integration

After invoking the /users/_login endpoint, you will receive a payload like this:

<com.mirth.connect.plugins.mfa.model.DuoLoginStatus>
    ...
    <primaryStatus>SUCCESS</primaryStatus>
    <apiHostname>api-f9248ffb.duosecurity.com</apiHostname>
    <signedRequest>TX|...:APP|...</signedRequest>
</com.mirth.connect.plugins.mfa.model.DuoLoginStatus>

Take note of the primaryStatus, which lets you know whether primary authentication (username and password) succeeded. You should only proceed if the primary status is SUCCESS or SUCCESS_GRACE_PERIOD. Note the apiHostname and signedRequest, as those will be passed into the Duo iframe.

The next step is to show the Duo iframe to the user, and retrieve the signed response string. Instructions are here: https://duo.com/docs/duoweb.

After you retrieve the signed response string, call the /users/_login endpoint again. On this second leg of authentication, only the username is required, not the password. Concatenate the username, primary status, and signed response with colons (":"). Then send the string as a custom header, X-Mirth-Login-Data.

If the login call was successful, the server returns a JSESSIONID cookie for you to use on subsequent requests. When you no longer need the session, call the /users/_logout endpoint to clear the session data on the server.