documentation for totp (#841)
This commit is contained in:
Shuchang Zheng
@@ -21,9 +21,12 @@ Body:
|
||||
|
||||
## Time-based One-time Password (TOTP)
|
||||
|
||||
Skyvern supports one-time password (see https://www.twilio.com/docs/glossary/totp for more information) by fetching it from your endpoint. You can pass `totp_verification_url` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). Inside this endpoint hosted by you, you have to conform to the following schema:
|
||||
Skyvern supports one-time password (see https://www.twilio.com/docs/glossary/totp for more information), also knwon as 2FA/MFA, in two ways: 1) Skyvern gets the code from your endpoint 2) You push the the code to Skyvern.
|
||||
|
||||
### Set Up Your TOTP Endpoint
|
||||
### Get Code From Your Endpoint
|
||||
You can pass `totp_verification_url` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). Inside this endpoint hosted by you, you have to conform to the following schema:
|
||||
|
||||
#### Set Up Your TOTP Endpoint
|
||||
For websites that requires a verification code to complete a task, you have to set up a TOTP endpoint for Skyvern to fetch the verification code.
|
||||
|
||||
Here's the TOTP endpoint contract you should use:
|
||||
@@ -39,7 +42,7 @@ Response:
|
||||
| task_id | String | yes | tsk_123 | The task ID that needs the verification to be done |
|
||||
| verification_code | String | no | 123456 | The verification code |
|
||||
|
||||
### Validate The Sender of The Request
|
||||
#### Validate The Sender of The Request
|
||||
Same as the webhook API, your server needs to make sure it’s Skyvern that’s making the request.
|
||||
|
||||
- a python example for how to generate and validate the signature:
|
||||
@@ -54,3 +57,103 @@ def validate_skyvern_request_headers(request: Request) -> bool:
|
||||
```
|
||||
|
||||
SKYVERN_API_KEY: this is the [api key](/running-tasks/introduction) specific to your organization
|
||||
|
||||
### Push Code To Skyvern
|
||||
You can pass `totp_identifier` when [creating a task](/running-tasks/api-spec#request-initiate-a-task). When the TOTP code arrives at your inbox or as a text message, all you need to do is to send the email/message (Gmail + Zapier integration can be a good solution to set up email forwarding) to Skyvern's TOTP receiver endpoint (see below)
|
||||
|
||||
#### Skyvern's TOTP Endpoint
|
||||
This endpoint takes your TOTP/2FA/MFA code, stores it in Skyvern’s database and uses it while running tasks/workflows.
|
||||
|
||||
Request type: `POST`
|
||||
|
||||
Endpoint url: `https://api.skyvern.com/api/v1/totp`
|
||||
|
||||
Authentication: same as other Skyvern APIs, you need to pass your api key with the `x-api-key` header.
|
||||
|
||||
Request data:
|
||||
| field | required | type | example | description |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| totp_identifier | yes | string | An email address or phone number which received the code | this is a required field as this is the best way for skyvern to know what the identifier |
|
||||
| content | yes | string | | the email content of a 2FA email; the text message for the verification code |
|
||||
| task_id | no | string | tsk_22222222 | if passed, this will be used to help skyvern locate the totp code more accurately |
|
||||
| workflow_id | no | string | wpid_12345 | used to help better locate the totp code accurately for your workflow |
|
||||
| source | no | string | email, phone, app, etc | |
|
||||
| expired_at | no | string | | if provided, skyvern uses this time to decide if the code is valid or not |
|
||||
|
||||
#### Forwarding Your Email To Skyvern (Gmail + Zapier)
|
||||
This setup requires a Zapier pro plan account.
|
||||
|
||||
**Step 1. Create a Zapier Zap**
|
||||
|
||||
Go to https://zapier.com/app/home and create new Zaps
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap.png"/>
|
||||
</p>
|
||||
|
||||
In the newly created Zap draft, Click the “Trigger” button
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_trigger.png"/>
|
||||
</p>
|
||||
|
||||
Click `Email by Zapier`
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_trigger.png"/>
|
||||
</p>
|
||||
|
||||
In the Email “Setup”, pick `New Inbound Email` in the `Trigger event` selection. Click `Continue` to complete the “Setup”
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_email_setup.png"/>
|
||||
</p>
|
||||
|
||||
In Email “Configure”, create an email address which will be used to forward emails for TOTP codes. Click “Continue”.
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_input_email.png"/>
|
||||
</p>
|
||||
|
||||
Let’s add the Action to complete the Zapier setup before coming back to test it. Click the “Action” button and add `Webhooks by Zapier`
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_action.png"/>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_webhook.png"/>
|
||||
</p>
|
||||
|
||||
In the Setup, choose “POST” under the `Action event` selection. Then click “Continue”.
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_action_event_post.png"/>
|
||||
</p>
|
||||
|
||||
In the “Configure”, set up these in order to make a POST request to Skyvern’s TOTP API:
|
||||
|
||||
- URL: [`http://54.163.41.95:8000/api/v1/totp`](http://54.163.41.95:8000/api/v1/totp)
|
||||
- Payload Type: json
|
||||
- Data:
|
||||
- totp_identifier: choose `Raw To Email` after clicking the “+” sign
|
||||
- content: choose `Body Plain` after clicking the “+” sign
|
||||
- source: email
|
||||
- Headers:
|
||||
- x-api-key: {your Skyvern API key}
|
||||
|
||||
<p align="center">
|
||||
<img src="images/totp/create_zap_webhook_complete.png"/>
|
||||
</p>
|
||||
Click Continue
|
||||
|
||||
**Step 2. Add forwarding email and create a filter in Gmail**
|
||||
Go to Gmail Settings → Forwarding and POP/IMAP (https://mail.google.com/mail/u/0/#settings/fwdandpop) → click “Add a forwarding address” → enter the zapier email address you just created. There might be some verifications, including a verification email from Zapier, you have to complete here.
|
||||
|
||||
After setting up the forwarding email address, go to “Filters and Blocked Addresses” (https://mail.google.com/mail/u/0/#settings/filters). Click “Create a new filter” and set up your email filtering rule for your TOTP (2FA/MFA) emails. Click “Create filter”. Check “Forward it to” and pick the new email address and update filter.
|
||||
|
||||
<p align="center">
|
||||
<img src="images/totp/create_email_forwarding.png"/>
|
||||
</p>
|
||||
|
||||
**Step 3. Test it end to end!**
|
||||
You can forward any previous TOTP (2FA/MFA) email to the Zapier email address you created in Step 1.
|
||||
|
||||
In Zapier: under the “Test” of the Webhooks action, send a request to test it out. If your test is sccessful, you should see a `A request was sent to Webhooks by Zapier` message
|
||||
|
||||
<p align="center">
|
||||
<img src="images/totp/test_end_to_end.png"/>
|
||||
</p>
|
||||
|
||||
Reference in New Issue
Block a user