OmniAuth Slack Strategy

omniauth-slack2 provides a Slack OpenID Connect strategy for OmniAuth.

Installation

Add this line to your application's Gemfile:

gem 'omniauth-slack2'

Then run:

bundle install

Usage

Configure OmniAuth in your Rack/Rails app:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :slack2,
           ENV.fetch('SLACK_CLIENT_ID'),
           ENV.fetch('SLACK_CLIENT_SECRET')
end

Compatibility alias is available, so you can keep existing callback paths using slack:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :slack,
           ENV.fetch('SLACK_CLIENT_ID'),
           ENV.fetch('SLACK_CLIENT_SECRET')
end

If you support both names during a migration, register both callback paths in Slack:

https://your-app.example.com/auth/slack2/callback
https://your-app.example.com/auth/slack/callback

Provider App Setup

Slack API Dashboard: https://api.slack.com/apps
Enable Sign in with Slack under OAuth & Permissions
Register the callback URL that matches your provider name:
- slack2: https://your-app.example.com/auth/slack2/callback
- slack: https://your-app.example.com/auth/slack/callback
If your Slack app enforces PKCE, this strategy sends code_challenge / code_verifier with S256 by default
Required scopes: openid, email, profile

Options

Supported request options include:

scope (default: openid email profile)
nonce (auto-generated by default)
team (pre-select a Slack workspace)
pkce (default: true — sends code_challenge / code_verifier using S256)
skip_jwt (default: false — set to true to skip id_token RS256 verification)

Troubleshooting

If Slack rejects a local callback while your app is enforcing PKCE, prefer a real HTTPS hostname over localhost for interactive testing
The same callback/PKCE rules apply to the compat slack alias, not just slack2

Auth Hash

Example payload from request.env['omniauth.auth'] (realistic shape, anonymized):

{
  "uid": "U0R7MFMJM",
  "info": {
    "name": "Sample User",
    "email": "sample@example.test",
    "unverified_email": "sample@example.test",
    "email_verified": true,
    "first_name": "Sample",
    "last_name": "User",
    "image": "https://secure.gravatar.com/avatar/example.jpg?s=512&d=https%3A%2F%2Fa.slack-edge.com%2Fexample.png",
    "locale": "en-US"
  },
  "credentials": {
    "token": "xoxp-...",
    "refresh_token": "xoxe-1-...",
    "expires_at": 1772691847,
    "expires": true,
    "scope": "openid email profile"
  },
  "extra": {
    "raw_info": {
      "ok": true,
      "sub": "U0R7MFMJM",
      "https://slack.com/user_id": "U0R7MFMJM",
      "https://slack.com/team_id": "T0123ABC456",
      "email": "sample@example.test",
      "email_verified": true,
      "date_email_verified": 1775000482,
      "name": "Sample User",
      "picture": "https://secure.gravatar.com/avatar/example.jpg?s=512&d=https%3A%2F%2Fa.slack-edge.com%2Fexample.png",
      "given_name": "Sample",
      "family_name": "User",
      "locale": "en-US",
      "https://slack.com/team_name": "Sample Workspace",
      "https://slack.com/team_domain": "sampleworkspace",
      "https://slack.com/user_image_512": "https://secure.gravatar.com/avatar/example.jpg?s=512&d=https%3A%2F%2Fa.slack-edge.com%2Fexample.png",
      "https://slack.com/team_image_230": "https://avatars.slack-edge.com/example-team_132.jpg",
      "https://slack.com/team_image_default": false
    },
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "id_info": {
      "iss": "https://slack.com",
      "sub": "U0R7MFMJM",
      "aud": "your-client-id",
      "exp": 1775009314,
      "iat": 1775009014,
      "auth_time": 1775009014,
      "nonce": "auto-generated-nonce",
      "https://slack.com/team_id": "T0123ABC456",
      "https://slack.com/user_id": "U0R7MFMJM",
      "email": "sample@example.test",
      "email_verified": true,
      "date_email_verified": 1775000482,
      "locale": "en-US",
      "name": "Sample User",
      "picture": "https://secure.gravatar.com/avatar/example.jpg?s=512&d=https%3A%2F%2Fa.slack-edge.com%2Fexample.png",
      "given_name": "Sample",
      "family_name": "User",
      "https://slack.com/team_name": "Sample Workspace",
      "https://slack.com/team_domain": "sampleworkspace",
      "https://slack.com/team_image_230": "https://avatars.slack-edge.com/example-team_132.jpg",
      "https://slack.com/team_image_default": false
    },
    "team_id": "T0123ABC456",
    "team_name": "Sample Workspace",
    "team_domain": "sampleworkspace"
  }
}

Development

bundle install
bundle exec standardrb --fix
bundle exec rake

Run Rails integration tests with an explicit Rails version:

RAILS_VERSION='~> 8.1.0' bundle install
RAILS_VERSION='~> 8.1.0' bundle exec rake test_rails_integration

Compatibility

Ruby: >= 3.2 (tested on 3.2, 3.3, 3.4, 4.0)
omniauth-oauth2: >= 1.8, < 2.0
Rails integration lanes: ~> 7.1.0, ~> 7.2.0, ~> 8.0.0, ~> 8.1.0

Endpoints

This gem uses Slack OpenID Connect endpoints:

https://slack.com/openid/connect/authorize
https://slack.com/api/openid.connect.token
https://slack.com/api/openid.connect.userInfo
https://slack.com/openid/connect/keys (JWKS for id_token verification)

Test Structure

test/omniauth_slack2_test.rb: strategy/unit behavior
test/rails_integration_test.rb: full Rack/Rails request+callback flow
test/test_helper.rb: shared test bootstrap

Release

Tag releases as vX.Y.Z; GitHub Actions publishes the gem to RubyGems.

License

MIT

omniauth-slack2

Runtime