diff --git a/README.md b/README.md index c6f9d54c9651..54d0ea6024fa 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,18 @@ website generator that uses Markdown and Javascript. ### Installation +#### Unix-like systems + ```console asdf install corepack enable yarn install ``` +#### Windows + +Install [nvm-windows](https://github.com/coreybutler/nvm-windows). Make sure your `node` version matches the one specified in `.tool-versions`. + ### Starting your docs site server ```console diff --git a/docs/build/triggers.md b/docs/build/triggers.md index 32fa7a88004e..d247ae0af2e6 100644 --- a/docs/build/triggers.md +++ b/docs/build/triggers.md @@ -19,6 +19,10 @@ real-time event-based automation. ![Webhook Trigger](/img/webhook_trigger.png) +To learn about how to add an additional layer of security to your Webhook +Trigger by adding authentication, head over to our +[Webhook Security](../manage-projects/webhook-auth.md) page. + ### Cron Triggers (formerly timers) `Cron Triggers` run Workflows based on a cron schedule, and are good for diff --git a/docs/manage-projects/webhook-auth.md b/docs/manage-projects/webhook-auth.md new file mode 100644 index 000000000000..572632b162c8 --- /dev/null +++ b/docs/manage-projects/webhook-auth.md @@ -0,0 +1,75 @@ +--- +title: Webhook Security +sidebar_label: Webhook Security +slug: /webhook-security +--- + +This page guides you through the steps of adding an additional layer of security +to your webhook. + +## Adding a Webhook Authentication Method + +In your OpenFn projects, you can utilize webhooks to receive data from external +applications using a +[Webhook Trigger](../build/triggers.md). When using a +webhook, you can require external applications to authenticate before sending +your project data for more security. + +OpenFn supports Basic HTTP Authentication using username and password, and API +Key Authentication using the `x-api-key` request header. + +### Adding Authentication Via `Project Settings` + +You can add a new Authentication Method under `Webhook Security` of your +`Project Settings`. The authentication you set up here can then be used in any +of your Workflows within this Project. + +![Project Settings Webhook Security](/img/lightning_auth_project_settings.png) + +After clicking `New auth method`, choose the type - Basic HTTP or API Key +Authentication. + +![New Auth Method](/img/lightning_choose_auth_method.png) + +#### Basic Auth + +For Basic Auth, give it a name, choose a username and password, and hit +`Create Auth Method`. + +![Basic Auth](/img/lightning_basic_auth.png) + +#### API Key + +For API Key, just choose a name, and click `Create Auth Method`. An API key is +generated for you. + +![API auth](/img/lightning_api_auth.png) + +You can edit or delete your auth methods on this page as well. + +// screenshot + +Once you added an auth method to a webhook, it will show up under +`Linked Triggers`. + +![Linked Triggers](/img/lightning_linked_triggers.png) + +![Linked Triggers](/img/lightning_linked_triggers2.png) + +### Adding Authentication Via a Workflow + +On your Workflows you can use the auth methods you created under +`Project Settings`, or you can create a new one. + +When you click on `Add authentication` under `Webhook Authentication`, select a +(or multiple) existing method(s), or hit `Create a new webhook auth method`. +Refer to the `Basic Auth` and `API Key` sections above for details on adding +these. + +Once you've added an auth method, it will show up in your Webhook Trigger +configuration. + +![Linked Triggers](/img/lightning_workflow_trigger_added.png) + +Only requests using these required auth details will be able to send data to +your Workflow. diff --git a/sidebars-main.js b/sidebars-main.js index 856a6c129112..4cf49f5fc9e9 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -104,6 +104,7 @@ module.exports = { 'manage-projects/user-roles-permissions', 'manage-projects/notifications', 'manage-projects/link-to-gh', + 'manage-projects/webhook-auth', ], }, { diff --git a/static/img/lightning_api_auth.png b/static/img/lightning_api_auth.png new file mode 100644 index 000000000000..d74688071e41 Binary files /dev/null and b/static/img/lightning_api_auth.png differ diff --git a/static/img/lightning_auth_from_workflow.png b/static/img/lightning_auth_from_workflow.png new file mode 100644 index 000000000000..39c79c4046c1 Binary files /dev/null and b/static/img/lightning_auth_from_workflow.png differ diff --git a/static/img/lightning_auth_project_settings.png b/static/img/lightning_auth_project_settings.png new file mode 100644 index 000000000000..e8332356ef82 Binary files /dev/null and b/static/img/lightning_auth_project_settings.png differ diff --git a/static/img/lightning_basic_auth.png b/static/img/lightning_basic_auth.png new file mode 100644 index 000000000000..d668bc1dc033 Binary files /dev/null and b/static/img/lightning_basic_auth.png differ diff --git a/static/img/lightning_choose_auth_method.png b/static/img/lightning_choose_auth_method.png new file mode 100644 index 000000000000..7a5d9c6b94ed Binary files /dev/null and b/static/img/lightning_choose_auth_method.png differ diff --git a/static/img/lightning_edit_auth_method.png b/static/img/lightning_edit_auth_method.png new file mode 100644 index 000000000000..e345fa245335 Binary files /dev/null and b/static/img/lightning_edit_auth_method.png differ diff --git a/static/img/lightning_linked_triggers.png b/static/img/lightning_linked_triggers.png new file mode 100644 index 000000000000..b55255d616ad Binary files /dev/null and b/static/img/lightning_linked_triggers.png differ diff --git a/static/img/lightning_linked_triggers2.png b/static/img/lightning_linked_triggers2.png new file mode 100644 index 000000000000..2b048d66f0d2 Binary files /dev/null and b/static/img/lightning_linked_triggers2.png differ diff --git a/static/img/lightning_workflow_trigger_added.png b/static/img/lightning_workflow_trigger_added.png new file mode 100644 index 000000000000..216b10c32cc0 Binary files /dev/null and b/static/img/lightning_workflow_trigger_added.png differ