update documentation and comments with oauth information

Author: yasunariw

documentation/secret_docs.md

@@ -20,9 +20,14 @@ A secrets file stores sensitive information. Unlike the repository configuration
 | `slack_access_token` | slack bot access token to enable message posting to the workspace | Yes | try to use webhooks defined in `slack_hooks` instead |
 | `slack_hooks` | list of channel names and their corresponding webhook endpoint | Yes | try to use token defined in `slack_access_token` instead |
 | `slack_signing_secret` | specify to verify incoming slack requests | Yes | - |
+| `slack_client_id` | slack client ID, used for [oauth](https://api.slack.com/authentication/oauth-v2) authentication | Yes | - |
+| `slack_client_secret` | slack client secret, used for [oauth](https://api.slack.com/authentication/oauth-v2) authentication | Yes | - |
+| `slack_oauth_state` | specify some unique value to maintain state b/w oauth request and callback and prevent CSRF (see [RFC6749](https://tools.ietf.org/html/rfc6749#section-4.1.1)) | Yes | - |
 
 Note that either `slack_access_token` or `slack_hooks` must be defined.
 
+The fields `slack_client_id`, `slack_client_secret`, and `slack_oauth_state` only apply if you need to distribute the app to multiple users.
+
 ## `gh_token`
 
 Some operations, such as fetching a config file from a private repository, or the commit corresponding to a commit comment event, require a personal access token. Refer [here](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for detailed instructions on token generation.
@@ -35,6 +40,8 @@ Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks
 
 Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.
 
+If automatic OAuth exchange is set up, the bot will configure this value at runtime.
+
 ## `slack_hooks`
 
 *Note: If `slack_access_token` is also defined, the bot will authenticate over Slack's Web API and this option will not be used.*

lib/action.ml

@@ -281,6 +281,28 @@ module Action (Github_api : Api.Github) (Slack_api : Api.Slack) = struct
     match notification.event with
     | Link_shared event -> process_link_shared_event ctx event
 
+  (**
+
+    If there is a need to distribute the app, automatic OAuth exchange must be enabled.
+
+    The fields `slack_client_id` and `slack_client_secret` must be configured in the
+    secrets file. The `slack_oauth_state` field can be optionally provided to avoid
+    forgery attacks during the OAuth exchange.
+    (see: https://tools.ietf.org/html/rfc6749#section-4.1.1)
+
+    All of these fields are retrievable from the Slack app dashboard.
+
+    Once the server has been configured and launched, it will listen on `/slack/oauth`
+    for incoming OAuth requests from Slack. Each user should then go to the following
+    address, replacing the appropriate values (the `state` argument is only needed
+    if `slack_oauth_state` is set).
+      
+    https://slack.com/oauth/v2/authorize?scope=chat:write&client_id=<slack_client_id>&redirect_uri=<server_domain>/slack/oauth&state=<slack_oauth_state>
+
+    A page should open asking the user permission to install the bot to their
+    workspace. Clicking `allow` will trigger the OAuth exchange.
+
+  *)
   let process_slack_oauth (ctx : Context.t) args =
     try%lwt
       let secrets = Context.get_secrets_exn ctx in