少しつづ暖かくなってきて、もうすぐ春が来ますね。春の象徴はやっぱり「さくら」🌸 ですよね。実は日本で桜を見るのが初めてで、花見をするのをとても楽しみにしています！花粉さえなければいいのですが。改めまして、Slack で Developer Relations を担当している Jason と申します。
はじめに
このガイドでは、Slack アプリの作成と Postman を使った Slack の OAuth フローをご紹介いたします。Postman は、ユーザーやボットトークンを一度だけ取得したい場合や Slack API で遊んでみたりしたい場合におすすめです。なお、この記事は主にボットトークンの取得を中心に書かれていますが、このチュートリアルの最後にはユーザートークンの取得方法についても説明しています。
必要なもの
- アプリをインストールできる Slack ワークスペース。ワークスペースの設定によっては Admin または Owner に承認を依頼する必要があります。特に理由がなければ、テスト用の新しい Slack ワークスペースを作ることをおすすめします。
- OAuth フローをテストするための Postman アプリ。
Postman でボットトークンを取得する手順
1. Slack アプリの作成
上記のリンクから Slack アプリを作成します。From Scratch を選択し、アプリの名前と開発に使用するワークスペースを指定してください。
2. クライアント ID と シークレットの取得
新しいアプリを作成すると「Basic Information」 ページに遷移するはずです。少し下にスクロールして、App Credentials セクションにある Client ID と Signing Secret を保管しておいてください。
3. Postman の OAuth Callback URL を Redirect URL の指定
Redirect URL とは Slack が OAuth フローの認可確認画面から認可コードとともにユーザーをリダイレクトする URL のことです。この URL に Postman の URL を指定することで、Postman 側でその認可コードをトークンに交換してくれます。もっと詳しく知りたい方は、OAuth のドキュメント（英語） をお読みください。
左側のペインで、「OAuth & Permissions（ OAuth と権限）」 をクリックし、Redirect URLs までにスクロールしてください。ここで、以下の URL を Redirect URLs のリストに追加してください。
https://oauth.pstmn.io/v1/callback
4. Slack アプリにスコープを付与
Slack アプリにボットユーザーを追加するためには、Slack アプリの管理画面で少なくとも一つのボットスコープを指定する必要があります。スコープを一つ以上指定することも可能です。スコープを付与するには、「OAuth & Permissions」 ページに移動し、Scopes までスクロールし、必要なスコープを追加してください。画像では例として、ボットユーザーとしてメッセージを送信するための権限である chat:write スコープを追加しています。
5. Postman 側の OAuth 設定
認証できる Slack アプリの作成が終わったので、次は Postman 側で OAuth クライアントの設定を行います。 Postman の Authorization メニューで、Type を OAuth 2.0 に指定してください。表示されるフォームに必要な項目を入力し、 OAuth クライアントをセットアップしましょう。
| 項目 | 値 | コメント |
|---|---|---|
| Add auth data to Request Headers | Request Headers | これは、リクエストのヘッダーにトークンが追加されることを意味します。Slack API を呼び出すときトークンをリクエストボディまたはヘッダーに追加する必要があります。 |
| Token Name | お好きな名前を指定できます | トークンを管理するための名前です。 |
| Grant Type | Authorization Code | 今回使用する OAuth フローでは、 Slack API が発行する認可コードを使ってトークンをリクエストします。この項目を指定することで、Postman に OAuth フローの種別を伝えます。 |
| Callback URL | https://oauth.pstmn.io/v1/callback | 「Authorize Using Browser」チェックボックスをオンにすると、この項目が自動的に入力されます。ブラウザで Postman を利用している方はここの URL が異なる場合があります。表示されている URL とステップ 3 の Redirect URL と同じものに指定してください。 |
| Auth URL | https://slack.com/oauth/v2/authorize | Slack の OAuth フローの最初のステップでは、ユーザーをこの URL に誘導する必要があります。この項目に設定しておくことで、Postman が自動的にこれを利用して OAuth フローを開始します。 |
| Access Token URL | https://slack.com/api/oauth.v2.access | Slack の OAuth フローの最後のステップでは、認可コードを使って oauth.v2.access という API を呼び出すことで、アクセストークンを取得します。 |
| Client ID | ステップ 2 の Client ID の値 | API を呼び出すときに、認可コードと共に使用される値です。 |
| Client Secret | ステップ 2 の Client Secret の値 | API を呼び出すときに、認可コードと共に使用される値です。 |
| Scope | 例：chat:write
|
OAuth のスコープをカンマで区切った文字列です。全てのスコープは、ここを参照してください。 |
| Client Authentication | Send client credentials in the body |
そのままで OK です。 |
すべて正しく入力されていれば、以下のようになります。
6. アクセストークンの取得
Get New Access Token（新しいアクセストークンを発行する）ボタンをクリックすると、新しいブラウザウィンドウが開き、ワークスペースへのアクセス許可を求める画面が表示されます。要求されたスコープを承認すると、自動的に Postman にリダイレクトされ、トークンが発行されるはずです。トークンの文字列は xoxb- で始まります。
番外編: ユーザトークンまたは OrG レベルのトークンを取得する方法
ユーザートークンや OrG レベルのスコープ（ auditlogs:read や admin.*で始まるスコープ）を取得する場合は Slack の OAuth フローから複数のトークンが発行されるため、上記の Postman の方法では処理できません。その場合は、以下の手順でやってみてください。
1. アプリを任意のワークスペースで利用できるようにする（ OrG レベルのスコープを利用したい場合のみ）
OrG レベルのスコープを付与しない場合、このステップは任意です。OrG レベルのスコープを使用するには、アプリを複数のワークスペースにインストールできるようにする必要があります。これは英語で Public Distribution と言います。この点に関する詳細は、こちらのドキュメント（英語） を参照してください。
この設定を有効にするには、Slack アプリの管理画面の左側のペインにある「Manage Distribution（配布の管理）」ページに遷移してください。そして、「Share Your App with Other Workspaces（アプリを他のワークスペースに共有する）」までスクロールしてください。ここに表示される項目は右に緑のチェックマークが付いているはずです。アプリにワークスペース固有の情報がハードコードされていないことを確認した上で「Remove Hard Coded Information（ハードコードされた情報の削除）」という項目をクリックしてください。最後に「Activate Public Distribution（公開配布を有効にする）」をクリックします。
2. 必要なユーザースコープの追加
ユーザートークンを取得する場合、「Postman でボットトークンを取得する手順」で説明した手順のうち 1〜4 のステップは同じです。ステップ 5 の Auth URL の値のみが異なります。https://slack.com/oauth/v2/authorize?user_scope= の後にリクエストしたい ユーザースコープをカンマ区切り文字列を追加する必要があります。例えば、chat:write と admin のスコープを付与したい場合、以下のような Auth URL を使用します。
https://slack.com/oauth/v2/authorize?user_scope=chat:write,admin
3. トークンの取得
先ほどと同じ手順で、「Get New Access Token」ボタンを押し、OAuth 画面で承認を行ってください。その後、Postman の 「Manage Access Tokens（アクセストークンの管理）」 モーダルで表示される Slack からのペイロードを確認する必要があります。ペイロードの中で authed_user を探してください。このオブジェクトの中に access_token というキーがあるはずです。その xoxp- から始まる文字列の値をコピーしてください。
Postman での API リクエストでは、度に一つのトークンしか使うことができません。ボットトークンがある場合、それがデフォルトになります。ボットトークンとユーザートークン両方を発行していて、API リクエストでユーザートークンを使用したいという場合は Postman の Access Token パラメーターに、そのユーザートークンを貼り付ける必要があります。
まとめ
これで、ボットトークンとユーザートークンを使って Slack API メソッドを呼び出す準備が整いました 🎉！早速お好きな API メソッドを呼び出してみてください。このチュートリアルをお読みになって、少しでもお役に立ったら嬉しいです。
ついでに、この記事は元々英語で書いたものですが、興味があれば英語でもお読みください。
もし何か質問・ご不明な点があれば、気軽にコメントしてください。🤗
それでは、また！ 👋