You can configure Opal to integrate with your Slack workspace in order to send notifications to requesters and reviewers about permission and group access requests. Opal supports using a single Slack workspace or using multiple workspaces through Slack Enterprise Grid. See the section below for installing to an enterprise grid.

Setup

You must be an Opal administrator and a Slack workspace administrator to set up the Slack integration.

1. Log into the Slack workspace you want to integrate with Opal.

2. Go to the Settings page under the Configuration section of the sidebar.

Installation varies between the Cloud Opal app and self-hosted instances.

For cloud instances

1. Click "Connect" on the Slack integration on the Opal Configuration page.

2. Select an option for installing to a single workspace or multiple workspaces via Slack Enterprise Grid. Note that you can choose to install to a single workspace even if that workspace belongs to an enterprise grid.

If you are installing to a single workspace, enter the Slack workspace's domain for the "Organization Name" field. For example, if your workspace is called opal-test-workspace (with the associated URL opal-test-workspace.slack.com), then input opal-test-workspace.

3. Next, you will be redirected to the Slack authorization page asking you to grant the Opal Slack app permissions to access your workspace or organization. See the section below for installing to an enterprise grid.

For self-hosted instances

For self-hosted, it is first necessary to create a new Slack app representing the Opal app.

1. Navigate to the Slack App Dashboard and click on the "Create New App" button.

2. Choose to create "From an app manifest"

3. Select the Slack workspace associated with your self-hosted integration, and click "Next"

4. Copy/paste the following app manifest json, editing the <your-opal-hostname> field.

{
    "display_information": {
        "name": "Opal",
        "description": "Taking the pain out of permissions",
        "background_color": "#00020d"
    },
    "features": {
        "bot_user": {
            "display_name": "Opal",
            "always_online": false
        },
        "slash_commands": [
            {
                "command": "/opal",
                "description": "Request a resource",
                "usage_hint": "Request a resource",
                "should_escape": false
            }
        ]
    },
    "oauth_config": {
        "redirect_urls": [
            "https://<your-opal-hostname>/callback/slack"
        ],
        "scopes": {
            "user": [
                "channels:read",
                "groups:read"
            ],
            "bot": [
                "app_mentions:read",
                "chat:write",
                "chat:write.public",
                "commands",
                "groups:read",
                "im:history",
                "im:write",
                "users.profile:read",
                "users:read",
                "users:read.email",
                "groups:write",
                "channels:manage",
                "channels:read",
                "channels:history"
            ]
        }
    },
    "settings": {
        "event_subscriptions": {
            "user_events": [
                "channel_deleted",
                "group_deleted"
            ],
            "bot_events": [
                "channel_deleted",
                "group_deleted",
                "message.channels",
                "message.im",
                "team_access_granted",
                "team_access_revoked"
            ]
        },
        "interactivity": {
            "is_enabled": true
        },
        "org_deploy_enabled": true,
        "socket_mode_enabled": true,
        "token_rotation_enabled": false
    }
}

5. After the app is created, add the Opal logo to the Slackbot "Display Information" using the image below:

6. Click on "Basic Information" on the left sidebar, and record the Client ID, Client Secret and Signing Secret fields. We will use these values in subsequent steps.

7. Generate an app-level token.

Click on "Basic Information" on the left sidebar, and navigate to the "App-Level Tokens" section. Click on the "Generate Tokens and Scopes" button to create the app-level token. Give the token the connections:write scope, and make sure to record the token, which will be input later.

This app-level token is needed to use Slack's socket mode, which lets your self-hosted Opal instance avoid requiring an open port on the instance to receive Slack events.

8. Click on "App Home" on the left sidebar. Make sure the "Messages Tab" and "Allow users to send Slack commands and messages from the messages tab" is turned on:

9. Click on "Basic Information" on the left sidebar. Click on "Install your app" and "Install to Workspace". The Slack app you just created will appear in your Slack workspace.

10. Go to the settings page in your Opal instance under the Configuration section in the sidebar. Click "Connect" on the Slack integration.

11. Select an option for installing to a single workspace or multiple workspaces via Slack Enterprise Grid. Note that you can choose to install to a single workspace even if that workspace belongs to an enterprise grid.

12. For the "Client ID" field, input the Client ID from Step 6.

13. Next, for the "Client secret" field, input the Client Secret from Step 6.

14. Then, for the "Signing secret" field, input the Signing Secret from Step 6.

15. Lastly, for the "App level token" field, input the app-level token from Step 7.

16. On the last step, you will be redirected to the Slack authorization page asking you to grant the Opal Slack app permissions to access your workspace or organization. See section below for installing to an enterprise grid.

Note: to update your existing Slack integration to use socket mode, follow step 6 to generate the app-level-token and enable socket mode. Then, navigate to the Opal Configuration page, and disconnect then reconnect Slack.

Setup - Enterprise Grid

Installing the integration to an enterprise grid has the same steps above. However, the Slack integration authorization page can be confusing when indicating if you're installing to the enterprise grid or just one workspace in it.

On the authorization step, use the dropdown in the upper-right hand corner to choose an organization under "Your organizations."

In the above example, the Slack organization "Opal Grid 1" has two workspaces: "Opal Grid Test 0" and "Opal Grid Test 2." There are two options:

• Choosing the organization will allow you to install Opal to multiple workspaces in the enterprise grid
• Choosing a workspace will only install Opal to that specific workspace.

Note that by default, no workspaces in the enterprise grid will have access to Opal after your initial installation. See the following section to add workspaces from the enterprise grid.

Granting access to specific workspaces in the enterprise grid

After installing the Slack integration, you can add or remove Opal from workspaces in your Slack enterprise organization using the link provided in the settings page:

Use the "Manage" dropdown to add or remove workspaces:

Installation Status

If the installation succeeds, on the Configuration page, you will see a "Disconnect" button in place of the "Connect" button inside the Slack tile. Opal is ready to send Slack messages to members of your workspace.

For self-hosted Opal instances, there will be a status that says either "active" or "inactive" beside the "Disconnect" button. This corresponds to the state of the web socket connection with Slack. If the connection is inactive wait a few minutes to see if the connection re-establishes itself (refresh the page and see if the status updates). If the problem does not resolve itself within 10 minutes, try disconnecting and reconnecting the Slack integration.

Finally, you can verify that everything works by trying the /opal command in Slack.

User settings

To enable Slack notifications for your own user, navigate to the top-right of the Opal page and click your avatar. Click "Account Settings" and under "Notification Preferences", toggle "Slack" on:

Please note visibility settings apply to user(s) who are attempting to create the linked channel. If the user does not have access to the channel, we will return the error Error: you do not have access to the selected Slack workspace.

Linked reviewer channels

Slack channels can be linked to any owner as a reviewer channel. Opal will notify the Slack channel whenever there is an access request to review for the owner.

Linked audit channels

Opal will notify the Slack channel whenever there is an event related to the resource or group.

To configure this, go to the resource or group that you wish to set this up for and edit. To make private channels visible here, the Opal app must first be invited to them.