feat(standardized-auth): add an acme sample for standardized app auth

.github/dependabot.yml

@@ -30,3 +30,15 @@ updates:
       slack:
         patterns:
           - "com.slack.api:*"
+  - package-ecosystem: "maven"
+    directory: "standardized-auth"
+    schedule:
+      interval: "daily"
+    cooldown:
+      default-days: 7
+      exclude:
+        - "com.slack.api:*"
+    groups:
+      slack:
+        patterns:
+          - "com.slack.api:*"

.github/workflows/test.yml

@@ -16,6 +16,7 @@ jobs:
         showcase:
           - "block-kit"
           - "methods"
+          - "standardized-auth"
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

README.md

@@ -6,3 +6,4 @@ This collections of examples highlights features of a Slack app in the language
 
 - **[Block Kit](./block-kit)**: The framework of visual components arranged to create app layouts.
 - **[Methods](./methods)**: An interface for querying information from and enacting change in a Slack workspace.
+- **[Standardized Auth](./standardized-auth)**: Connect user accounts with the Slack-owned Connect and Manage connection controls.

standardized-auth/.env.example

@@ -0,0 +1,5 @@
+SLACK_CLIENT_ID=
+SLACK_CLIENT_SECRET=
+SLACK_SIGNING_SECRET=
+BASE_URL=https://1234-56-78-90-0.ngrok-free.app
+PORT=3000

standardized-auth/.gitignore

@@ -0,0 +1,7 @@
+.classpath
+.project
+.settings
+target
+data/
+.env*
+!.env.example

standardized-auth/.slack/.gitignore

@@ -0,0 +1,2 @@
+apps.dev.json
+cache/

standardized-auth/.slack/config.json

@@ -0,0 +1,6 @@
+{
+  "manifest": {
+    "source": "local"
+  },
+  "project_id": "00000000-0000-0000-0000-000000000000"
+}

standardized-auth/.slack/hooks.json

@@ -0,0 +1,8 @@
+{
+  "hooks": {
+    "start": "mvn --quiet compile exec:java"
+  },
+  "config": {
+    "sdk-managed-connection-enabled": true
+  }
+}

standardized-auth/README.md

@@ -0,0 +1,31 @@
+# Standardized Auth
+
+Connect your Acme account to Slack with the Slack-owned **Connect** and **Manage connection** controls. Rocket skates, anvils, and giant magnets not included.
+
+Read the docs: https://docs.slack.dev/authentication/standardized-auth
+
+## How it works
+
+Acme keeps every connection in Bolt's installation service: a user is connected when it holds their user token.
+
+- **Connect** opens `/slack/install`. When the OAuth flow saves the user's token, the app reports the connection with `apps.user.connection.requestAuth` and refreshes App Home.
+- **Disconnect** forgets the user's token, reports the user as disconnected, then revokes the token.
+- **`user_connection_status_requested`** answers with `apps.user.connection.update` whenever Slack asks about a user it doesn't know yet.
+- **`tokens_revoked`** forgets users who remove Acme from their Slack settings and reports them as disconnected.
+- **App Home** shows an `auth_provider` block with the user's current connection.
+
+## Setup
+
+```sh
+$ ngrok http 3000  # Replace 1234-56-78-90-0.ngrok-free.app in manifest.json
+$ slack install --environment local  # Create a new app
+$ slack app settings  # Gather the client ID, client secret, and signing secret
+$ slack env init  # Update defaults with them and your ngrok URL
+$ slack manifest  # Validate fields
+$ slack run
+$ open https://1234-56-78-90-0.ngrok-free.app/slack/install  # Install the app
+```
+
+Then open the app's **Home** tab and click **Connect**.
+
+Swap the `users:read` and `users.profile:read` scopes for the ones your connection needs.

standardized-auth/manifest.json

@@ -0,0 +1,45 @@
+{
+  "display_information": {
+    "name": "Acme",
+    "description": "Rocket skates, anvils, and giant magnets for every plan",
+    "background_color": "#4A154B"
+  },
+  "features": {
+    "app_home": {
+      "home_tab_enabled": true,
+      "messages_tab_enabled": false
+    },
+    "bot_user": {
+      "display_name": "Acme",
+      "always_online": true
+    },
+    "user_connections": {
+      "is_enabled": true,
+      "auth_hosts": ["1234-56-78-90-0.ngrok-free.app"]
+    }
+  },
+  "oauth_config": {
+    "redirect_urls": ["https://1234-56-78-90-0.ngrok-free.app/slack/oauth_redirect"],
+    "scopes": {
+      "bot": ["users:read"],
+      "user": ["users.profile:read"]
+    }
+  },
+  "settings": {
+    "event_subscriptions": {
+      "request_url": "https://1234-56-78-90-0.ngrok-free.app/slack/events",
+      "bot_events": [
+        "app_home_opened",
+        "tokens_revoked",
+        "user_connection_status_requested"
+      ]
+    },
+    "interactivity": {
+      "is_enabled": true,
+      "request_url": "https://1234-56-78-90-0.ngrok-free.app/slack/events"
+    },
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}

standardized-auth/pom.xml

@@ -0,0 +1,90 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.slack.api</groupId>
+  <artifactId>standardized-auth-example</artifactId>
+  <version>0.1-SNAPSHOT</version>
+  <packaging>jar</packaging>
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <exec.mainClass>acme.Main</exec.mainClass>
+  </properties>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.16.0</version>
+        <configuration>
+          <release>17</release>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>exec-maven-plugin</artifactId>
+        <version>3.6.4</version>
+        <configuration>
+          <cleanupDaemonThreads>false</cleanupDaemonThreads>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>com.diffplug.spotless</groupId>
+        <artifactId>spotless-maven-plugin</artifactId>
+        <version>3.10.4</version>
+        <configuration>
+          <formats>
+            <format>
+              <includes>
+                <include>.gitignore</include>
+              </includes>
+              <trimTrailingWhitespace/>
+              <endWithNewline/>
+              <indent>
+                <tabs>true</tabs>
+                <spacesPerTab>4</spacesPerTab>
+              </indent>
+            </format>
+          </formats>
+          <java>
+            <palantirJavaFormat/>
+          </java>
+          <pom/>
+          <markdown>
+            <includes>
+              <include>**/*.md</include>
+            </includes>
+            <flexmark/>
+          </markdown>
+        </configuration>
+        <executions>
+          <execution>
+            <goals>
+              <goal>apply</goal>
+            </goals>
+            <phase>compile</phase>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  <dependencies>
+    <dependency>
+      <groupId>com.slack.api</groupId>
+      <artifactId>bolt-jetty</artifactId>
+      <version>1.52.1-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+      <version>1.7.36</version>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <version>6.1.3</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>

standardized-auth/src/main/java/acme/AcmeAccounts.java

@@ -0,0 +1,33 @@
+package acme;
+
+import com.slack.api.bolt.context.Context;
+import com.slack.api.bolt.model.Installer;
+import com.slack.api.bolt.service.InstallationService;
+import java.util.Optional;
+
+public final class AcmeAccounts {
+    private final InstallationService installations;
+
+    public AcmeAccounts(InstallationService installations) {
+        this.installations = installations;
+    }
+
+    public Optional<Installer> find(Context context, String userId) {
+        return Optional.ofNullable(installations.findInstaller(context.getEnterpriseId(), context.getTeamId(), userId))
+                .filter(installer -> installer.getInstallerUserAccessToken() != null);
+    }
+
+    public Optional<String> forget(Context context, String userId) {
+        Optional<Installer> account = find(context, userId);
+        account.ifPresent(this::delete);
+        return account.map(Installer::getInstallerUserAccessToken);
+    }
+
+    private void delete(Installer installer) {
+        try {
+            installations.deleteInstaller(installer);
+        } catch (Exception error) {
+            throw new IllegalStateException("Failed to forget the Acme account", error);
+        }
+    }
+}

standardized-auth/src/main/java/acme/AcmeApp.java

@@ -0,0 +1,58 @@
+package acme;
+
+import com.slack.api.bolt.App;
+import com.slack.api.bolt.AppConfig;
+import com.slack.api.bolt.service.InstallationService;
+import com.slack.api.bolt.service.OAuthStateService;
+import com.slack.api.model.event.AppHomeOpenedEvent;
+import com.slack.api.model.event.TokensRevokedEvent;
+import com.slack.api.model.event.UserConnectionStatusRequestedEvent;
+
+public final class AcmeApp {
+    private AcmeApp() {}
+
+    public static AppConfig config() {
+        return AppConfig.builder()
+                .singleTeamBotToken(null)
+                .scope("users:read")
+                .userScope("users.profile:read")
+                .oauthInstallPath("install")
+                .oauthRedirectUriPath("oauth_redirect")
+                .oAuthInstallPathEnabled(true)
+                .oAuthRedirectUriPathEnabled(true)
+                .oAuthInstallPageRenderingEnabled(false)
+                .build();
+    }
+
+    public static App api(AppConfig config, InstallationService installations, AcmeListeners listeners) {
+        App app = new App(config).service(installations);
+        app.event(AppHomeOpenedEvent.class, (payload, ctx) -> {
+            listeners.publishHome(ctx.client(), ctx, payload.getEvent().getUser());
+            return ctx.ack();
+        });
+        app.event(UserConnectionStatusRequestedEvent.class, (payload, ctx) -> {
+            listeners.answerStatusRequest(ctx.client(), ctx, payload.getEvent().getUser());
+            return ctx.ack();
+        });
+        app.event(TokensRevokedEvent.class, (payload, ctx) -> {
+            listeners.forgetRevokedUsers(
+                    ctx.client(), ctx, payload.getEvent().getTokens().getOauth());
+            return ctx.ack();
+        });
+        app.blockAction(AcmeProvider.CONNECT_ACTION_ID, (req, ctx) -> ctx.ack());
+        app.blockAction(AcmeProvider.DISCONNECT_ACTION_ID, (req, ctx) -> {
+            listeners.disconnect(ctx.client(), ctx, req.getPayload().getUser().getId());
+            return ctx.ack();
+        });
+        return app;
+    }
+
+    public static App oauth(
+            AppConfig config, InstallationService installations, OAuthStateService states, AcmeListeners listeners) {
+        return new App(config)
+                .asOAuthApp(true)
+                .service(installations)
+                .service(states)
+                .oauthPersistenceCallback(listeners::reportConnected);
+    }
+}