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.
| Panel | ||||||
|---|---|---|---|---|---|---|
On this page:
|
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
| Code Block |
|---|
http POST https://cloud-api.eis.utoronto.ca/tf/enable method=AUTHENTICATOR -a <username> |
cURL
| Code Block |
|---|
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.
| Code Block |
|---|
{
"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
| Code Block |
|---|
http POST https://cloud-api.eis.utoronto.ca/tf/verify otp=<code> -a <username> |
cURL
| Code Block |
|---|
curl -X POST -H 'Content-Type: application/json' \
https://cloud-api.eis.utoronto.ca/tf/verify \
-d '{"otp": "<code>"}' -u <username> |
Response
| Code Block |
|---|
{
"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
| Code Block |
|---|
http POST https://cloud-api.eis.utoronto.ca/auth/request-token otp=<code> -a <username> |
cURL
| Code Block |
|---|
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.
| Code Block |
|---|
{
"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/disablewith your credentials.Code Block 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.