Using the Duo Universal API Integration

First Call

The first call posts to the /users/_login endpoint in order to get authorization.

To authenticate the Duo Administrator, it is necessary to provide a X-Mirth-Server-Url header containing the Mirth server URL.

• After invoking the /users/_login endpoint, you will receive a payload that looks, for example, like this:

  <com.mirth.connect.plugins.mfa.model.DuoLoginStatus>
      ....
      <primaryStatus>SUCCESS</primaryStatus>
      <apiHostname>api-ff51bcf3.duosecurity.com</apiHostname>
      <authURL>https://api-ff51bcf3.duosecurity.com/oauth/v1/authorize?scope=openid&amp;response_type=code&amp;redirect_uri=https://localhost:8443/api/4.5.0/extensions/mfa/duocallback&amp;client_id=DIZ4Q0FEZGOK8ZVOWN2O&amp;request=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJkdW9fdW5hbWUiOiJ0ZXN0MSIsInNjb3BlIjoib3BlbmlkIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL2xvY2FsaG9zdDo4NDQzL2FwaS80LjUuMC9leHRlbnNpb25zL21mYS9kdW9jYWxsYmFjayIsInN0YXRlIjoiMzJmNWUzN2IyMDVhZTE0MjMyNzE0MmVjNmYxYzQ0N2M3MjI4IiwiZXhwIjoxNzAzNzIyODAxLCJ1c2VfZHVvX2NvZGVfYXR0cmlidXRlIjp0cnVlLCJjbGllbnRfaWQiOiJESVo0UTBGRVpHT0s4WlZPV04yTyJ9.UThnUKGAz7CN-BbABb2uj_W0JWLIypJg2ATULjotwifxoKZJBYeh2HLAzXmsqpNOMPSHjDzT1DwhKQauS51bKQ</authURL>
      <redirectUri>https://localhost:8443/api/4.5.0/extensions/mfa/duocallback</redirectUri>
  </com.mirth.connect.plugins.mfa.model.DuoLoginStatus>

• From the payload, copy the URL within the authURL tags into a browser to start interacting with the Duo Administrator. For example:

   https://api-ff51bcf3.duosecurity.com/oauth/v1/authorize?scope=openid&response_type=code&redirect_uri=https://localhost:8443/api/4.5.0/extensions/mfa/duocallback&client_id=DIZ4Q0FEZGOK8ZVOWN2O&request=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJkdW9fdW5hbWUiOiJ0ZXN0MSIsInNjb3BlIjoib3BlbmlkIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL2xvY2FsaG9zdDo4NDQzL2FwaS80LjUuMC9leHRlbnNpb25zL21mYS9kdW9jYWxsYmFjayIsInN0YXRlIjoiMzJmNWUzN2IyMDVhZTE0MjMyNzE0MmVjNmYxYzQ0N2M3MjI4IiwiZXhwIjoxNzAzNzIyODAxLCJ1c2VfZHVvX2NvZGVfYXR0cmlidXRlIjp0cnVlLCJjbGllbnRfaWQiOiJESVo0UTBGRVpHT0s4WlZPV04yTyJ9.UThnUKGAz7CN-BbABb2uj_W0JWLIypJg2ATULjotwifxoKZJBYeh2HLAzXmsqpNOMPSHjDzT1DwhKQauS51bKQ

• A successful interaction will redirect to a URL in the address bar that looks like the following example:

  https://localhost:8443/api/4.5.0/extensions/mfa/duocallback?state=dff8bd53717fdbf36d5a6e4e6da6331d6e61&duo_code=FSVpTN3h5QNMji2uXzKe69Q5qWf0iv7L

Second Call

The second call sends the authorization back to Duo.

• Take note of the primaryStatus from the authentication payload, which lets you know whether the primary authentication (username and password) succeeded.
• You should only proceed if the primaryStatus is SUCCESS or SUCCESS_GRACE_PERIOD.
• Note the redirectUri, duo_code, and state from the redirect URL.
• Call the /users/_login endpoint again. On this second round of authentication, only the username is required, not the password.
  • Concatenate the username, primaryStatus, duo_code and state and base64 encoded redirect URI separated by colons (":"). For example:

    test1:SUCCESS:FSVpTN3h5QNMji2uXzKe69Q5qWf0iv7L:dff8bd53717fdbf36d5a6e4e6da6331d6e61:aHR0cHM6Ly9sb2NhbGhvc3Q6ODQ0My9hcGkvNC41LjAvZXh0ZW5zaW9ucy9tZmEvZHVvY2FsbGJhY2s=

  • 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.