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
http POST https://cloud-api.eis.utoronto.ca/tf/verify otp=<code> -a <username>
cURL
curl -X POST -H 'Content-Type: application/json' \ https://cloud-api.eis.utoronto.ca/tf/verify \ -d '{"otp": "<code>"}' -u <username>
Response
{ "code": 200, "message": "TOTP verified.", "type": "info" }
Request Access Token
There’s a bit of a difference inhttps://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
http POST https://cloud-api.eis.utoronto.ca/auth/request-token otp=<code> -a <username>
cURL
curl -X POST -H 'Content-Type: application/json' \ https://cloud-api.eis.utoronto.ca/auth/request-token \ -d '{"otp": "<code>"}' -u <username>
Response
If the TOTP and credentials are valid, the following response body will be provided.
{ "duration": 86400, "exp": <expiry>, "exp_date": "<expiry_date>, "token": "<super_long_string>", "type": "ACCESS" }
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.curl -X POST https://cloud-api.eis.utoronto.ca/tf/disable -u <username>
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.
It is recommended to disable MFA only to switch methods.