From c6b4d2e1387d84545ba731201c5dcd46fa91b6ed Mon Sep 17 00:00:00 2001 From: Trygve Aaberge Date: Tue, 5 May 2020 23:50:12 +0200 Subject: Document usage of session tokens Fixes #764 --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++++-------------- docs/Commands.md | 8 ++++++-- wee_slack.py | 18 ++++++++++++++---- 3 files changed, 63 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index fc136d3..9ecea5a 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,11 @@ Table of Contents * [1. Install dependencies](#1-install-dependencies) * [2. Download wee_slack.py to ~/.weechat/python](#2-download-wee_slackpy-to-weechatpython) * [3. Start WeeChat](#3-start-weechat) - * [4. Add your Slack API key(s)](#4-add-your-slack-api-keys) + * [4. Add your Slack API token(s)](#4-add-your-slack-api-tokens) + * [Get a token with OAuth](#get-a-token-with-oauth) + * [Get a session token](#get-a-session-token) * [Optional: Connecting to multiple teams](#optional-connecting-to-multiple-teams) + * [Optional: Secure the tokens](#optional-secure-the-tokens) * [Commands and options](#commands-and-options) * [Threads](#threads) * [Emoji characters and tab completions of emoji names](#emoji-characters-and-tab-completions-of-emoji-names) @@ -98,7 +101,24 @@ weechat **NOTE:** If weechat is already running, the script can be loaded using `/python load wee_slack.py`. -### 4. Add your Slack API key(s) +### 4. Add your Slack API token(s) + +There are two types of tokens that can be used, OAuth tokens and session +tokens. The official way to get a token is to use OAuth. However, this has +several drawbacks, so an alternative way is to pull a session token out of the +web client. + +Drawbacks of OAuth tokens: +- If the team is restricting app installations, wee-slack has to be approved by an admin. +- For free teams, wee-slack will use one of the ten app slots. +- The subscribe and unsubscribe commands won't work. +- Marking threads, shared channels and channels that has been converted from public to private as read won't work. + +Drawbacks of session tokens: +- These tokens can't be revoked, so be careful not to loose them. +- They are not officially supported, and may stop working at any time. + +#### Get a token with OAuth Log in to Slack: @@ -128,19 +148,12 @@ Note that by default GitHub Pages will see a temporary code used to create your token (but not the token itself). If you're worried about this, you can use the `-nothirdparty` option, though the process will be a bit less user friendly. -The tokens you add will be stored in the option -`plugins.var.python.slack.slack_api_token`. If you don't want to store your API -token in plaintext you can use the secure features of WeeChat: - -``` -/secure passphrase this is a super secret password -/secure set slack_token -/set plugins.var.python.slack.slack_api_token ${sec.data.slack_token} -``` +#### Get a session token -Note that you will have to move your tokens manually from -`plugins.var.python.slack.slack_api_token` to the secure variable after each -time you run `/slack register `. +1. Open and sign into the [Slack customization page](https://my.slack.com/customize). Check that you end up on the correct team. +2. Type `javascript:` in the address field in the browser and paste this code after: `window.prompt("Session token:", TS.boot_data.api_token)` +3. A prompt with the token will appear. Copy the token, return to WeeChat and run `/slack register `. +4. Reload the script with `/python reload slack`. #### Optional: Connecting to multiple teams @@ -152,6 +165,22 @@ commas. /set plugins.var.python.slack.slack_api_token ,, ``` +#### Optional: Secure the tokens + +The tokens you add will be stored as plain text in the option +`plugins.var.python.slack.slack_api_token`. If you don't want to store your API +token in plain text you can use the secure features of WeeChat: + +``` +/secure passphrase this is a super secret password +/secure set slack_token +/set plugins.var.python.slack.slack_api_token ${sec.data.slack_token} +``` + +Note that you will have to move your tokens manually from +`plugins.var.python.slack.slack_api_token` to the secure variable after each +time you run `/slack register `. + Commands and options -------------------- diff --git a/docs/Commands.md b/docs/Commands.md index 8ba5dc3..a972d19 100644 --- a/docs/Commands.md +++ b/docs/Commands.md @@ -164,9 +164,11 @@ Prints current status if no arguments are given, unsets the status if -delete is /slack subscribe ``` -Subscribe to a thread, so that you are alerted to new messages. When in a +Subscribe to a thread, so that you are alerted to new messages. When in a thread buffer, you can omit the thread id. +Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens" + ### talk ``` @@ -199,9 +201,11 @@ If no message id is specified the last thread in channel will be opened. ``` Unsubscribe from a thread that has been previously subscribed to, so that -you are not alerted to new messages. When in a thread buffer, you can omit +you are not alerted to new messages. When in a thread buffer, you can omit the thread id. +Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens" + ### upload ``` diff --git a/wee_slack.py b/wee_slack.py index d6b5763..097cf37 100644 --- a/wee_slack.py +++ b/wee_slack.py @@ -2947,12 +2947,18 @@ def handle_subscriptionsthreadmark(json, eventrouter, team, channel, metadata): def handle_subscriptionsthreadadd(json, eventrouter, team, channel, metadata): if not json["ok"]: - print_error("Couldn't add thread subscription: {}".format(json['error'])) + if json['error'] == 'not_allowed_token_type': + print_error("Can only subscribe to a thread when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens") + else: + print_error("Couldn't add thread subscription: {}".format(json['error'])) def handle_subscriptionsthreadremove(json, eventrouter, team, channel, metadata): if not json["ok"]: - print_error("Couldn't remove thread subscription: {}".format(json['error'])) + if json['error'] == 'not_allowed_token_type': + print_error("Can only unsubscribe from a thread when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens") + else: + print_error("Couldn't remove thread subscription: {}".format(json['error'])) ###### New/converted process_ and subprocess_ methods @@ -4275,8 +4281,10 @@ def subscribe_helper(current_buffer, args, usage, api): def command_subscribe(data, current_buffer, args): """ /slack subscribe - Subscribe to a thread, so that you are alerted to new messages. When in a + Subscribe to a thread, so that you are alerted to new messages. When in a thread buffer, you can omit the thread id. + + Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens" """ return subscribe_helper(current_buffer, args, 'Usage: /slack subscribe ', "subscriptions.thread.add") @@ -4289,8 +4297,10 @@ def command_unsubscribe(data, current_buffer, args): """ /slack unsubscribe Unsubscribe from a thread that has been previously subscribed to, so that - you are not alerted to new messages. When in a thread buffer, you can omit + you are not alerted to new messages. When in a thread buffer, you can omit the thread id. + + Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens" """ return subscribe_helper(current_buffer, args, 'Usage: /slack unsubscribe ', "subscriptions.thread.remove") -- cgit