少しつづ暖かくなってきて、もうすぐ春が来ますね。春の象徴はやっぱり「さくら」🌸 ですよね。実は日本で桜を見るのが初めてで、花見をするのをとても楽しみにしています！花粉さえなければいいのですが。改めまして、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 メソッドを呼び出してみてください。このチュートリアルをお読みになって、少しでもお役に立ったら嬉しいです。

ついでに、この記事は元々英語で書いたものですが、興味があれば英語でもお読みください。

もし何か質問・ご不明な点があれば、気軽にコメントしてください。🤗

それでは、また！ 👋