Introduction

The ITS Private Cloud API recently introduced in v2021.11.0 Multi Factor Authentication with Time-based One-Time Password (TOTP) in order to provide an additional layer of security when generating an Access Token to manage your virtual infrastructure.

MFA with TOTP is opt-in based.

Time-based OTP generation and delivery methods supported by the ITS Private Cloud API include:

Authenticator: DUO, Microsoft Authenticator, Google Authenticator, Auhty, etc.
Email: OTP code is sent upon request via email to the main account.
SMS: OTP code is sent upon request via SMS to a given phone number during setup.

Enable MFA

To enable MFA with TOTP using Authenticator just make a POST request to /tf/enable providing the preferred method in the payload, in this case AUTHENTICATOR. If a payload or method is not provided, EMAIL is used by default.

HTTPIe

http POST https://cloud-api.eis.utoronto.ca/tf/enable method=AUTHENTICATOR -a <username>

cURL

curl -X POST -H 'Content-Type: application/json' \
https://cloud-api.eis.utoronto.ca/tf/enable \
-d '{"method": "AUTHENTICATOR"}' -u <username>

Response

A successful response includes the QR code image in svg format encoded named image, the authenticator key and uri used for setting up Authenticator Apps manually by copying and pasting the secret and a list of one-time recovery codes that can be used instead of providing a TOTP.

{
  "image": "<long-string>",
  "issuer": "vss-api.eis.utoronto.ca",
  "key": "<authenticator-key>",
  "method": "authenticator",
  "phone": null,
  "recovery_codes": [
    "<recovery-code_1>",
    "<recovery-code_2>",
    "<recovery-code_3>",
    "<recovery-code_4>",
    "<recovery-code_5>",
    "<recovery-code_6>",
    "<recovery-code_7>",
    "<recovery-code_8>",
  ],
  "uri": "otpauth://totp/vss-api.eis.utoronto.ca:<username>?secret=<secret>&issuer=vss-api.eis.utoronto.ca",
  "username": "<username>"
}

A similar response is expected for SMS and EMAIL.

At this point, you should’ve received a confirmation email of your MFA setup.

Verify MFA

Once MFA has been enabled, grab one of the Authenticator Codes and make a POST request to /ft/verify with the payload {"otp": "<code>"}.

If you have enabled SMS or EMAIL you can request tokens by making a POST request to /tf/request-token with your credentials: curl -X POST https://vss-api.eis.utoronto.ca/tf/request-token -u <username>

HTTPie

cURL

Response

Request Access Token

There’s a bit of a difference in https://eis-vss.atlassian.net/wiki/spaces/API/pages/7569650/Authentication#Request-Access-Token when MFA is enabled. Just include a TOTP in the request payload as follows:

HTTPie

cURL

Response

If the TOTP and credentials are valid, the following response body will be provided.

Disable MFA

If you would like to change the MFA method, first you need to disable it. The process to disable MFA is:

A request has to be submitted via /tf/disable with your credentials.
An email is sent to your accounts default address for confirmation.
The email includes a link valid for 15 minutes that must be accessed with your credentials.
A confirmation email will be sent.