From edbe8214d5da7fb3cd54a6f0f768cda3900a2d26 Mon Sep 17 00:00:00 2001 From: Nicholas Koh Date: Fri, 8 May 2020 23:57:45 +0800 Subject: [PATCH 1/4] docs: Add brief migration guide --- DEPLOYMENT.md | 4 +++- MIGRATION.md | 11 +++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 MIGRATION.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 6af7b41..4d3b040 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -12,6 +12,8 @@ Once created, go to the app's Basic Info tab and grab the Client ID and Client S Alternatively, you can still [generate a legacy API token](https://api.slack.com/custom-integrations/legacy-tokens) for your app and use it for some interactions. +If you have a legacy API token, and would like to migrate to the new Slack apps, a brief [migration guide](MIGRATION.md) is provided. + #### SLACK_API_TOKEN Set the SLACK_API_TOKEN environment variable using the token received above. @@ -81,7 +83,7 @@ passenger_pre_start http://example.com:80/; Allow from all Options -MultiViews - Require all granted + Require all granted diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..61af1b3 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,11 @@ +# Migrating from Legacy API Tokens + +New Slack Apps require authentication via OAuth, returning an access token that should be a drop-in replacement for `SLACK_API_TOKEN`. As of the time of writing, the tokens never expire, so you could potentially write your own OAuth flow to retrieve the access token separately. Alternatively, you could migrate to [slack-ruby-bot-server](https://github.com/slack-ruby/slack-ruby-bot-server). + +## Migrating to slack-ruby-bot-server +Overview: +- Create a new Slack App as [advised by Slack](https://api.slack.com/legacy/custom-integrations/legacy-tokens#migrating-from-legacy). +- Figure out how you want to persist your token. The gem supports ActiveRecord and Mongoid out-of-the-box and will create a `Team` model. +- Using a [sample app](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps) as a base, move your `SlackRubyBot::Commands::Base` or `SlackRubyBot::Bot` concrete classes into the [`commands` folder](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps/sample_app_activerecord/commands) and require it in `commands.rb`. +- Create a [Slack Button](https://api.slack.com/docs/slack-button), setting the redirect URL to `.../api/teams`. This is the OAuth grant redirect URL that will be run in the sample `config.ru` file. The endpoint will create a `Team` and store the access token in it. +- Run your app and authenticate with the Slack button. From 73ceea5d819b50ef6e0e00f4a203d1c156979815 Mon Sep 17 00:00:00 2001 From: Nicholas Koh Date: Sat, 9 May 2020 00:04:15 +0800 Subject: [PATCH 2/4] docs: Add changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d3d760..2d51900 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ ### 0.15.1 (Next) * Your contribution here. +* [#260](https://github.com/slack-ruby/slack-ruby-bot/pull/260): Add brief migration guide - [@wasabigeek](https://github.com/wasabigeek). ### 0.15.0 (2020/5/8) From e04f05b9a018f46c534065b29134b31e65d79591 Mon Sep 17 00:00:00 2001 From: Nicholas Koh Date: Sat, 16 May 2020 23:07:56 +0800 Subject: [PATCH 3/4] docs: Tweak migration guide --- MIGRATION.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 61af1b3..1f79099 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,11 +1,13 @@ # Migrating from Legacy API Tokens -New Slack Apps require authentication via OAuth, returning an access token that should be a drop-in replacement for `SLACK_API_TOKEN`. As of the time of writing, the tokens never expire, so you could potentially write your own OAuth flow to retrieve the access token separately. Alternatively, you could migrate to [slack-ruby-bot-server](https://github.com/slack-ruby/slack-ruby-bot-server). +New Slack Apps require authentication via OAuth, returning an access token that should be a drop-in replacement for `SLACK_API_TOKEN`. As of the time of writing, the tokens never expire, so you could potentially write your own OAuth flow to retrieve the access token separately. + +Alternatively, you could migrate to [slack-ruby-bot-server](https://github.com/slack-ruby/slack-ruby-bot-server). Note that this requires more infrastructure to support the OAuth flow. ## Migrating to slack-ruby-bot-server -Overview: -- Create a new Slack App as [advised by Slack](https://api.slack.com/legacy/custom-integrations/legacy-tokens#migrating-from-legacy). -- Figure out how you want to persist your token. The gem supports ActiveRecord and Mongoid out-of-the-box and will create a `Team` model. -- Using a [sample app](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps) as a base, move your `SlackRubyBot::Commands::Base` or `SlackRubyBot::Bot` concrete classes into the [`commands` folder](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps/sample_app_activerecord/commands) and require it in `commands.rb`. -- Create a [Slack Button](https://api.slack.com/docs/slack-button), setting the redirect URL to `.../api/teams`. This is the OAuth grant redirect URL that will be run in the sample `config.ru` file. The endpoint will create a `Team` and store the access token in it. -- Run your app and authenticate with the Slack button. +1. Setup a new `slack-ruby-bot-server` project, following the [guidelines](https://github.com/slack-ruby/slack-ruby-bot-server#run-your-own). +2. Copy over the `SlackRubyBot::Commands::Base` or `SlackRubyBot::Bot` concrete classes from your `slack-ruby-bot` project into the new project. If you used a [sample app](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps), copy them into the [`commands` folder](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps/sample_app_activerecord/commands) and require it in `commands.rb`. +3. Create a [Slack Button](https://api.slack.com/docs/slack-button), setting the redirect URL to your OAuth grant endpoint. (In the sample app, this would be `/api/teams`. +4. Run your app and authenticate with the Slack button. + +**NOTE**: By default, other teams would be able to authenticate and connect their workspaces using the same Slack button. If this is not what you want, you would need to prevent it. From 6fc7653ccf413ee5ecbee2a1377d86216cf99943 Mon Sep 17 00:00:00 2001 From: Nicholas Koh Date: Mon, 18 May 2020 23:32:29 +0800 Subject: [PATCH 4/4] docs: Minor text fixes --- DEPLOYMENT.md | 2 +- MIGRATION.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 4d3b040..9e5a9ab 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -12,7 +12,7 @@ Once created, go to the app's Basic Info tab and grab the Client ID and Client S Alternatively, you can still [generate a legacy API token](https://api.slack.com/custom-integrations/legacy-tokens) for your app and use it for some interactions. -If you have a legacy API token, and would like to migrate to the new Slack apps, a brief [migration guide](MIGRATION.md) is provided. +If you have a legacy API token, and would like to migrate to [slack-ruby-bot-server](https://github.com/slack-ruby/slack-ruby-bot-server), a brief [migration guide](MIGRATION.md) is provided. #### SLACK_API_TOKEN diff --git a/MIGRATION.md b/MIGRATION.md index 1f79099..a7d638f 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -7,7 +7,7 @@ Alternatively, you could migrate to [slack-ruby-bot-server](https://github.com/s ## Migrating to slack-ruby-bot-server 1. Setup a new `slack-ruby-bot-server` project, following the [guidelines](https://github.com/slack-ruby/slack-ruby-bot-server#run-your-own). 2. Copy over the `SlackRubyBot::Commands::Base` or `SlackRubyBot::Bot` concrete classes from your `slack-ruby-bot` project into the new project. If you used a [sample app](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps), copy them into the [`commands` folder](https://github.com/slack-ruby/slack-ruby-bot-server/tree/master/sample_apps/sample_app_activerecord/commands) and require it in `commands.rb`. -3. Create a [Slack Button](https://api.slack.com/docs/slack-button), setting the redirect URL to your OAuth grant endpoint. (In the sample app, this would be `/api/teams`. +3. Create a [Slack Button](https://api.slack.com/docs/slack-button), setting the redirect URL to your OAuth grant endpoint. In the sample app, this would be `/api/teams`. 4. Run your app and authenticate with the Slack button. **NOTE**: By default, other teams would be able to authenticate and connect their workspaces using the same Slack button. If this is not what you want, you would need to prevent it.