Add automatic access token rotation for workspace apps (#347)

Author: Roach

.gitignore

@@ -21,3 +21,6 @@ cov_*
 # due to using tox and pytest
 .tox
 .cache
+.pytest_cache/
+.python-version
+pip

.vscode/settings.json

@@ -1,5 +1,9 @@
 // Place your settings in this file to overwrite default and user settings.
 {
   "python.linting.pylintEnabled": false,
-  "python.linting.flake8Enabled": true
+  "python.linting.flake8Enabled": true,
+  "python.venvPath": "./venv",
+  "python.pythonPath": "${workspaceFolder}/venv/bin/python",
+  "python.formatting.provider": "black",
+  "editor.formatOnSave": true,
 }

README.rst

@@ -25,6 +25,15 @@ Whether you're building a custom app for your team, or integrating a third party
 service into your Slack workflows, Slack Developer Kit for Python allows you to leverage the flexibility
 of Python to get your project up and running as quickly as possible.
 
+Documentation
+***************
+
+For comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
+
+If you're building a project to receive content and events from Slack, check out the `Python Slack Events API Adapter <https://github.com/slackapi/python-slack-events-api/>`_ library.
+
+You may also review our `Development Roadmap <https://github.com/slackapi/python-slackclient/wiki/Slack-Python-SDK-Roadmap>`_ in the project wiki.
+
 
 Requirements and Installation
 ******************************
@@ -43,16 +52,8 @@ by pulling down the source code directly into your project:
 	git clone https://github.com/slackapi/python-slackclient.git
 	pip install -r requirements.txt
 
-Documentation
---------------
-
-For comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
-
-
-You may also review our `Development Roadmap <https://github.com/slackapi/python-slackclient/wiki/Slack-Python-SDK-Roadmap>`_ in the project wiki.
-
 Getting Help
--------------
+*************
 
 If you get stuck, we’re here to help. The following are the best ways to get assistance working through your issue:
 
@@ -68,7 +69,6 @@ This package is a modular wrapper designed to make Slack `Web API <https://api.s
 app. Provided below are examples of how to interact with commonly used API endpoints, but this is by no means
 a complete list. Review the full list of available methods `here <https://api.slack.com/methods>`_.
 
-See `Tokens & Authentication <http://slackapi.github.io/python-slackclient/auth.html#handling-tokens>`_ for API token handling best practices.
 
 Sending a message
 ********************
@@ -79,6 +79,7 @@ To send a message to a channel, use the channel's ID. For IMs, use the user's ID
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -99,6 +100,7 @@ as sending a regular message, but with an additional ``user`` parameter.
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -127,6 +129,7 @@ appear directly in the channel, instead relegated to a kind of forked timeline d
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -145,6 +148,7 @@ set the ``reply_broadcast`` boolean parameter to ``True``.
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -174,6 +178,7 @@ Sometimes you need to delete things.
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -196,6 +201,7 @@ This method adds a reaction (emoji) to an item (``file``, ``file comment``, ``ch
 
 .. code-block:: python
 
+  import os
   from slackclient import SlackClient
 
   slack_token = os.environ["SLACK_API_TOKEN"]
@@ -230,22 +236,12 @@ At some point, you'll want to find out what channels are available to your app.
 
 .. code-block:: python
 
-  from slackclient import SlackClient
-
-  slack_token = os.environ["SLACK_API_TOKEN"]
-  sc = SlackClient(slack_token)
-
   sc.api_call("channels.list")
 
 Archived channels are included by default. You can exclude them by passing ``exclude_archived=1`` to your request.
 
 .. code-block:: python
 
-  from slackclient import SlackClient
-
-  slack_token = os.environ["SLACK_API_TOKEN"]
-  sc = SlackClient(slack_token)
-
   sc.api_call(
     "channels.list",
     exclude_archived=1
@@ -259,11 +255,6 @@ Once you have the ID for a specific channel, you can fetch information about tha
 
 .. code-block:: python
 
-  from slackclient import SlackClient
-
-  slack_token = os.environ["SLACK_API_TOKEN"]
-  sc = SlackClient(slack_token)
-
   sc.api_call(
     "channels.info",
     channel="C0XXXXXXX"
@@ -277,11 +268,6 @@ Channels are the social hub of most Slack teams. Here's how you hop into one:
 
 .. code-block:: python
 
-  from slackclient import SlackClient
-
-  slack_token = os.environ["SLACK_API_TOKEN"]
-  sc = SlackClient(slack_token)
-
   sc.api_call(
     "channels.join",
     channel="C0XXXXXXY"
@@ -299,18 +285,71 @@ joined one by accident. This is how you leave a channel.
 
 .. code-block:: python
 
-  from slackclient import SlackClient
-
-  slack_token = os.environ["SLACK_API_TOKEN"]
-  sc = SlackClient(slack_token)
-
   sc.api_call(
     "channels.leave",
     channel="C0XXXXXXX"
   )
 
 See `channels.leave <https://api.slack.com/methods/channels.leave>`_ for more info.
 
+
+Tokens and Authentication
+**************************
+
+The simplest way to create an instance of the client, as shown in the samples above, is to use a bot (xoxb) access token:
+
+.. code-block:: python
+
+  # Get the access token from environmental variable
+  slack_token = os.environ["SLACK_API_TOKEN"]
+  sc = SlackClient(slack_token)
+
+
+The SlackClient library allows you to use a variety of Slack authentication tokens.
+
+To take advantage of automatic token refresh, you'll need to instantiate the client a little differently than when using
+a bot access token. With a bot token, you have the access (xoxb) token when you create the client, when using refresh tokens,
+you won't know the access token when the client is created.
+
+Upon the first request, the SlackClient will request a new access (xoxa) token on behalf of your application, using your app's
+refresh token, client ID, and client secret.
+
+.. code-block:: python
+
+    # Get the access token from environmental variable
+    slack_refresh_token = os.environ["SLACK_REFRESH_TOKEN"]
+    slack_client_id = os.environ["SLACK_CLIENT_ID"]
+    slack_client_secret = os.environ["SLACK_CLIENT_SECRET"]
+
+
+Since your app's access tokens will be expiring and refreshed, the client requires a callback method to be passed in on creation of the client.
+Once Slack returns an access token for your app, the SlackClient will call your provided callback to update the access token in your datastore.
+
+.. code-block:: python
+
+    # This is where you'll add your data store update logic
+    def token_update_callback(update_data):
+        print("Enterprise ID: {}".format(update_data["enterprise_id"]))
+        print("Workspace ID: {}".format(update_data["team_id"]))
+        print("Access Token: {}".format(update_data["access_token"]))
+        print("Access Token expires in (ms): {}".format(update_data["expires_in"]))
+
+    # When creating an instance of the client, pass the client details and token update callback
+    sc = SlackClient(
+      refresh_token=slack_refresh_token,
+      client_id=slack_client_id,
+      client_secret=slack_client_secret,
+      token_update_callback=token_update_callback
+    )
+
+
+Slack will send your callback function the **app's access token**, **token expiration TTL**, **team ID**, and **enterprise ID** (for enterprise workspaces)
+
+
+See `Tokens & Authentication <http://slackapi.github.io/python-slackclient/auth.html#handling-tokens>`_ for API token handling best practices.
+
+
+
 Additional Information
 ********************************************************************************************
 For comprehensive method information and usage examples, see the `full documentation`_.

docs-src/auth.rst

@@ -5,21 +5,25 @@ Tokens & Authentication
 
 Handling tokens and other sensitive data
 ----------------------------------------
-Slack tokens are the keys to your—or your customers’—teams. Keep them secret. Keep them safe. One way to do that is to never explicitly hardcode them.
+⚠️ **Slack tokens are the keys to your—or your customers’—data.Keep them secret. Keep them safe.**
+
+One way to do that is to never explicitly hardcode them.
 
 Try to avoid this when possible:
 
 .. code-block:: python
 
   token = 'xoxb-abc-1232'
 
-If you commit this code to GitHub, the world gains access to this token’s team. Rather, we recommend you pass tokens in as environment variables, or persist them in a database that is accessed at runtime. You can add a token to the environment by starting your app as:
+⚠️ **Never share test tokens with other users or applications. Do not publish test tokens in public code repositories.**
+
+We recommend you pass tokens in as environment variables, or persist them in a database that is accessed at runtime. You can add a token to the environment by starting your app as:
 
 .. code-block:: python
 
   SLACK_BOT_TOKEN="xoxb-abc-1232" python myapp.py
 
-Then in your code retrieve the key with:
+Then retrieve the key with:
 
 .. code-block:: python
 
@@ -34,13 +38,15 @@ You can use the same technique for other kinds of sensitive data that ne’er-do
 
 For additional information, please see our `Safely Storing Credentials <https://api.slack.com/docs/oauth-safety>`_ page.
 
-Test Tokens
+Single-Workspace Apps
 -----------------------
-During development (prior to implementing OAuth) you can use a test token provided by the `Test Token Generator <https://api.slack.com/docs/oauth-test-tokens>`_. These tokens provide access to your private data and that of your team.
+If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow.
 
-**Tester tokens are not intended to replace OAuth 2.0 tokens.** Once your app is ready for users, replace this token with a proper OAuth token implementation.
+Once you've setup your features, click on the **Install App to Team** button found on the **Install App** page.
+If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to
+your workspace for changes to take effect.
 
-**Never share test tokens with other users or applications. Do not publish test tokens in public code repositories.**
+For additional information, see the `Installing Apps <https://api.slack.com/slack-apps#installing_apps>`_ of our `Building Slack apps <https://api.slack.com/slack-apps#installing_apps>`_ page.
 
 The OAuth flow
 -------------------------

docs-src/metadata.rst

@@ -14,6 +14,6 @@
 .. _Contributing: https://github.com/slackapi/python-slackclient/blob/master/.github/contributing.md
 .. _contributing guidelines: https://github.com/slackapi/python-slackclient/blob/master/.github/contributing.md
 .. _Contributor License Agreement: https://docs.google.com/a/slack-corp.com/forms/d/e/1FAIpQLSfzjVoCM7ohBnjWf7eDYQxzti1EPpinsIJQA5RAUBwJKRUQHg/viewform
-.. _Real Time Messaging API: https://api.slack.com/rtm
+.. _Real Time Messaging (RTM) API: https://api.slack.com/rtm
 .. _Web API: https://api.slack.com/web
 

docs-src/real_time_messaging.rst

@@ -1,9 +1,9 @@
 .. _real-time-messaging:
 
 ==============================================
-Real Time Messaging
+Real Time Messaging (RTM)
 ==============================================
-The `Real Time Messaging API`_ is a WebSocket-based API that allows you to
+The `Real Time Messaging (RTM) API`_ is a WebSocket-based API that allows you to
 receive events from Slack in real time and send messages as users.
 
 If you prefer events to be pushed to you instead, we recommend using the
@@ -13,7 +13,7 @@ in `the Events API <https://api.slack.com/events/api>`_.
 
 See :ref:`Tokens & Authentication <handling-tokens>` for API token handling best practices.
 
-Connecting to the Real Time Messaging API
+Connecting to the RTM API
 ------------------------------------------
 ::
 

docs/_static/doctools.js

@@ -70,7 +70,9 @@ jQuery.fn.highlightText = function(text, className) {
     if (node.nodeType === 3) {
       var val = node.nodeValue;
       var pos = val.toLowerCase().indexOf(text);
-      if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
+      if (pos >= 0 &&
+          !jQuery(node.parentNode).hasClass(className) &&
+          !jQuery(node.parentNode).hasClass("nohighlight")) {
         var span;
         var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
         if (isInSVG) {

docs/_static/documentation_options.js

@@ -1,5 +1,5 @@
 var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: '',
+    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
     VERSION: '1.0.1',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,

docs/about.html

@@ -47,7 +47,7 @@
 <li class="toctree-l1"><a class="reference internal" href="index.html">Slack Developer Kit for Python</a></li>
 <li class="toctree-l1"><a class="reference internal" href="auth.html">Tokens &amp; Authentication</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="auth.html#handling-tokens-and-other-sensitive-data">Handling tokens and other sensitive data</a></li>
-<li class="toctree-l2"><a class="reference internal" href="auth.html#test-tokens">Test Tokens</a></li>
+<li class="toctree-l2"><a class="reference internal" href="auth.html#single-workspace-apps">Single-Workspace Apps</a></li>
 <li class="toctree-l2"><a class="reference internal" href="auth.html#the-oauth-flow">The OAuth flow</a></li>
 </ul>
 </li>
@@ -75,8 +75,8 @@
 <li class="toctree-l2"><a class="reference internal" href="conversations.html#get-conversation-members">Get conversation members</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="real_time_messaging.html">Real Time Messaging</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#connecting-to-the-real-time-messaging-api">Connecting to the Real Time Messaging API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="real_time_messaging.html">Real Time Messaging (RTM)</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#connecting-to-the-rtm-api">Connecting to the RTM API</a></li>
 <li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#rtm-start-vs-rtm-connect">rtm.start vs rtm.connect</a></li>
 <li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#rtm-events">RTM Events</a></li>
 <li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#sending-messages-via-the-rtm-api">Sending messages via the RTM API</a></li>