python-slackclient/docs/auth.html at master · anthony-coder/python-slackclient

History

250 lines (225 loc) · 20.4 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

<!DOCTYPE html>

<head>

<title>Tokens & Authentication — Slack Developer Kit for Python</title>

</head>

</a>

</a>

<a style="color: #555459;" href="./index.html">Slack Developer Kit for Python</a>

<a href="https://github.com/SlackAPI/python-slackclient" class="btn header_btn float_right" data-qa="go_to_slack">Go to GitHub</a>

</div>

</header>

<li class="toctree-l1"><a class="reference internal" href="index.html">Slack Developer Kit for Python</a></li>

<li class="toctree-l1 current"><a class="current reference internal" href="#">Tokens & Authentication</a><ul>

<li class="toctree-l2"><a class="reference internal" href="#handling-tokens-and-other-sensitive-data">Handling tokens and other sensitive data</a></li>

<li class="toctree-l2"><a class="reference internal" href="#test-tokens">Test Tokens</a></li>

<li class="toctree-l2"><a class="reference internal" href="#the-oauth-flow">The OAuth flow</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="basic_usage.html">Basic Usage</a><ul>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#sending-a-message">Sending a message</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#updating-the-content-of-a-message">Updating the content of a message</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#deleting-a-message">Deleting a message</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#adding-or-removing-an-emoji-reaction">Adding or removing an emoji reaction</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#getting-a-list-of-channels">Getting a list of channels</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#getting-a-channel-s-info">Getting a channel’s info</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#joining-a-channel">Joining a channel</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#leaving-a-channel">Leaving a channel</a></li>

<li class="toctree-l2"><a class="reference internal" href="basic_usage.html#get-a-list-of-team-members">Get a list of team 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-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>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>

<li class="toctree-l2"><a class="reference internal" href="faq.html#what-even-is-product-name-and-why-should-i-care">What even is Slack Developer Kit for Python and why should I care?</a></li>

<li class="toctree-l2"><a class="reference internal" href="faq.html#omg-i-found-a-bug">OMG I found a bug!</a></li>

<li class="toctree-l2"><a class="reference internal" href="faq.html#hey-there-s-a-feature-missing">Hey, there’s a feature missing!</a></li>

<li class="toctree-l2"><a class="reference internal" href="faq.html#i-d-like-to-contribute-but-how">I’d like to contribute...but how?</a></li>

<li class="toctree-l2"><a class="reference internal" href="faq.html#how-do-i-compile-the-documentation">How do I compile the documentation?</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a><ul>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="about.html">About</a><ul>

<li class="toctree-l2"><a class="reference internal" href="about.html#product-name">Slack Developer Kit for Python</a></li>

</ul>

</li>

</ul>

<li><a href="https://github.com/SlackAPI/python-slackclient/blob/master/LICENSE">License</a></li>

<li><a href="https://github.com/SlackAPI/python-slackclient/blob/master/CODE_OF_CONDUCT.md">Code of Conduct</a></li>

<li><a href="https://github.com/SlackAPI/python-slackclient/blob/master/CONTRIBUTING.md">Contributing</a></li>

<li><a href="https://docs.google.com/a/slack-corp.com/forms/d/e/1FAIpQLSfzjVoCM7ohBnjWf7eDYQxzti1EPpinsIJQA5RAUBwJKRUQHg/viewform">Contributor License Agreement</a></li>

</ul>

Made with by Slack and our Lovely

Community

</div>

</nav>

<div class="section-title">Tokens & Authentication</div>

<h1>Tokens & Authentication<a class="headerlink" href="#tokens-authentication" title="Permalink to this headline">¶</a></h1>

<h2>Handling tokens and other sensitive data<a class="headerlink" href="#handling-tokens-and-other-sensitive-data" title="Permalink to this headline">¶</a></h2>

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.

Try to avoid this when possible:

<div class="highlight-python"><div class="highlight"><pre>token = 'xoxb-abc-1232'

</pre></div>

</div>

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:

<div class="highlight-python"><div class="highlight"><pre>SLACK_BOT_TOKEN="xoxb-abc-1232" python myapp.py

</pre></div>

</div>

Then in your code retrieve the key with:

<div class="highlight-python"><div class="highlight"><pre>import os

SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"]

</pre></div>

</div>

You can use the same technique for other kinds of sensitive data that ne’er-do-wells could use in nefarious ways, including

<li>Incoming webhook URLs</li>

<li>Slash command verification tokens</li>

<li>App client ids and client secrets</li>

</ul>

For additional information, please see our <a class="reference external" href="https://api.slack.com/docs/oauth-safety">Safely Storing Credentials</a> page.

</div>

<h2>Test Tokens<a class="headerlink" href="#test-tokens" title="Permalink to this headline">¶</a></h2>

During development (prior to implementing OAuth) you can use a test token provided by the <a class="reference external" href="https://api.slack.com/docs/oauth-test-tokens">Test Token Generator</a>. These tokens provide access to your private data and that of your team.

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.

Never share test tokens with other users or applications. Do not publish test tokens in public code repositories.

</div>

<h2>The OAuth flow<a class="headerlink" href="#the-oauth-flow" title="Permalink to this headline">¶</a></h2>

Authentication for Slack’s APIs is done using OAuth, so you’ll want to read up on <a class="reference external" href="https://api.slack.com/docs/oauth">OAuth</a>.

In order to implement OAuth in your app, you will need to include a web server. In this example, we’ll use <a class="reference external" href="http://flask.pocoo.org/">Flask</a>.

As mentioned above, we’re setting the app tokens and other configs in environment variables and pulling them into global variables.

Depending on what actions your app will need to perform, you’ll need different OAuth permission scopes. Review the available scopes <a class="reference external" href="https://api.slack.com/docs/oauth-scopes">here</a>.

<div class="highlight-python"><div class="highlight"><pre>import os

from flask import Flask, request

from slackclient import SlackClient

client_id = os.environ["SLACK_CLIENT_ID"]

client_secret = os.environ["SLACK_CLIENT_SECRET"]

oauth_scope = os.environ["SLACK_BOT_SCOPE"]

app = Flask(__name__)

</pre></div>

</div>

The OAuth initiation link:

To begin the OAuth flow, you’ll need to provide the user with a link to Slack’s OAuth page,

This directs the user to Slack’s OAuth acceptance page, where the user will review and accept

or refuse the permissions your app is requesting as defined by the requested scope(s).

For the best user experience, use the <a class="reference external" href="https://api.slack.com/docs/slack-button">Add to Slack button</a> to direct users to approve your application for access or <a class="reference external" href="https://api.slack.com/docs/sign-in-with-slack">Sign in with Slack</a> to log users in.

<div class="highlight-python"><div class="highlight"><pre>@app.route("/begin_auth", methods=["GET"])

def pre_install():

return '''

Add to Slack

</a>

'''.format(oauth_scope, client_id)

</pre></div>

</div>

The OAuth completion page

Once the user has agreed to the permissions you’ve requested on Slack’s OAuth

page, Slack will redirect the user to your auth completion page. Included in this

redirect is a <code class="docutils literal">code</code> query string param which you’ll use to request access

tokens from the <code class="docutils literal">oauth.access</code> endpoint.

Generally, Web API requests require a valid OAuth token, but there are a few endpoints

which do not require a token. <code class="docutils literal">oauth.access</code> is one example of this. Since this

is the endpoint you’ll use to retrieve the tokens for later API requests,

an empty string <code class="docutils literal">""</code> is acceptable for this request.

<div class="highlight-python"><div class="highlight"><pre>@app.route("/finish_auth", methods=["GET", "POST"])

def post_install():

# Retrieve the auth code from the request params

auth_code = request.args['code']

# An empty string is a valid token for this request

sc = SlackClient("")

# Request the auth tokens from Slack

auth_response = sc.api_call(

"oauth.access",

client_id=client_id,

client_secret=client_secret,

code=auth_code

)

</pre></div>

</div>

A successful request to <code class="docutils literal">oauth.access</code> will yield two tokens: A <code class="docutils literal">user</code>

token and a <code class="docutils literal">bot</code> token. The <code class="docutils literal">user</code> token <code class="docutils literal">auth_response['access_token']</code>

is used to make requests on behalf of the authorizing user and the <code class="docutils literal">bot</code>

token <code class="docutils literal">auth_response['bot']['bot_access_token']</code> is for making requests

on behalf of your app’s bot user.

If your Slack app includes a bot user, upon approval the JSON response will contain

an additional node containing an access token to be specifically used for your bot

user, within the context of the approving team.

When you use Web API methods on behalf of your bot user, you should use this bot

user access token instead of the top-level access token granted to your application.

<div class="highlight-python"><div class="highlight"><pre># Save the bot token to an environmental variable or to your data store

# for later use

os.environ["SLACK_USER_TOKEN"] = auth_response['user_access_token']

os.environ["SLACK_BOT_TOKEN"] = auth_response['bot']['bot_access_token']

# Don't forget to let the user know that auth has succeeded!

return "Auth complete!"

</pre></div>

</div>

Once your user has completed the OAuth flow, you’ll be able to use the provided

tokens to make a variety of Web API calls on behalf of the user and your app’s bot user.

See the <a class="reference internal" href="basic_usage.html#web-api-examples">Web API usage</a> section of this documentation for usage examples.

</div>

</div>

</div>

</footer>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

auth.html

Latest commit

History

auth.html

File metadata and controls