Chapter 6

Connecting each system

Connect Salesforce, MuleSoft, GitHub, Slack and Postman, test-drive accounts first, then the notes for real systems.

Before you connect anything

Do this chapter in two passes. Pass one connects the throwaway accounts from chapter 3. Pass two, only after the test drive, covers what changes when the systems are real; it is at the end of the chapter.

Before connecting checklist

You are signed in to Cockpit and the mode chip says Sandbox.
The password manager is open, with the Cockpit test drive vault ready for each key and secret.
You are signed in to each vendor's website as the test account in a browser profile that holds nothing else.
You have two tabs open: Cockpit's Connectors page, and the vendor.

ADVISORY

Every connector's connect page shows a value you must copy exactly (a callback or redirect URL). Copy it from Cockpit's page each time. Do not type it, and do not reuse one from an earlier environment: Cockpit shows the address that belongs to the console you are using.

How each system connects
System	Door	You create	You paste into Cockpit
Salesforce	Your own External Client App, sign-in with PKCE	An External Client App in each org	Consumer Key (and Secret, if the app has one)
MuleSoft	Your own connected app, client credentials	A connected app in Anypoint	Client id and client secret
GitHub	Cockpit's GitHub sign-in	Nothing	Nothing
Slack	Your own Slack app, sign-in	A Slack app in your workspace	Client id and client secret
Postman	An API key	A key in Postman	The key

6.1 Salesforce

Salesforce only lets an outside program in through an app that you create and control. Salesforce calls it an External Client App. You make one per org, copy its Consumer Key (and Secret) into Cockpit, and Cockpit sends you to Salesforce to sign in and approve. You decide the permissions. Do this once for org 1, then once for org 2; allow about ten minutes each.

In Cockpit

Open Connectors, find the Salesforce card and click Add Salesforce org.
You should see A guided page with four numbered steps.
Step 1. Where do you log in to Salesforce? Choose Production (login.salesforce.com) for a Developer Edition org. The other choices are Sandbox (test.salesforce.com) and My own domain (type an address like your-company.my.salesforce.com).
Caution This names the login address only. It is not Cockpit's Sandbox or Production mode.
Step 2. Copy the Callback URL and the Scopes boxes. Leave this tab open.
You should see The Scopes box reads: api refresh_token.

[Screenshot: The four-step Salesforce guide in Cockpit]Figure 23

Figure 23. The four-step Salesforce guide in Cockpit. Capture details are item 23 in the list of screenshots to capture. Call-outs to draw: 1 Org type choice; 2 Callback URL; 3 Scopes box reading api refresh_token; 4 Step 4 button.

In Salesforce (second tab, signed in to org 1)

Click the gear icon, then Setup. In Quick Find type External Client App Manager and open it. Click New External Client App.
You should see A form for a new external client app.
Name it Cockpit and enter your email as the contact.
Under OAuth Settings, tick Enable OAuth and paste the Callback URL you copied.
Add exactly two scopes: Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access). Cockpit's own list is api and refresh_token; the second Salesforce label is how Salesforce names that scope.
Caution Add no other scopes.
Tick Require Proof Key for Code Exchange (PKCE) and the authorization code flow. Leave every other flow off.
Click Create. Wait about two minutes: Salesforce needs a moment to switch the app on.
Open the app, then Settings, then OAuth Settings, and click Consumer Key and Secret. Copy both into the password manager.
You should see Two long codes.

[Screenshot: The External Client App's OAuth settings in Salesforce]Figure 24

Figure 24. The External Client App's OAuth settings in Salesforce. Capture details are item 24 in the list of screenshots to capture. Call-outs to draw: 1 Callback URL; 2 The two scopes; 3 PKCE option.

Back in Cockpit

Step 3. Paste the Consumer Key. Paste the Consumer Secret too if your app has one; the box says it is optional if the app uses PKCE only. The secret is encrypted and never shown again.
Step 4. Click Step 4. Sign in and approve. A Salesforce page asks you to allow Cockpit. Click Allow.
You should see You return to Connectors, a line says Salesforce is connected, and the card lists your org with its name, an org-type chip and the health label Working or Not checked yet.
Repeat the whole procedure for org 2 with Add Salesforce org.
You should see Two orgs on the card. Each chat now lets you pick one.

Prove it: start a chat, pick the org, and ask the first prompt in chapter 7 ("How close is this org to its API limits?"). A real number means the connection works.

ADVISORY

Rename each org on its card to something you will recognise, such as dev1 and dev2. The names appear in the org chip and in approval cards.

CAUTION

Salesforce says "redirect_uri_mismatch"? The callback in the app differs from the one in Cockpit's step 2. Copy it again with no spaces and save the app. "invalid client"? Wait two minutes after creating the app, then copy the key again. An approval error after sign-in? In the app's policies, let all users self-authorize, or approve your user, then retry. Chapter 10 has the full list.

6.2 MuleSoft

Cockpit reads your Anypoint organisation through a connected app that you create and that acts on its own behalf (client credentials). Cockpit only reads from Anypoint, so the app gets read-only scopes. Do this once for each trial account.

In Cockpit, open Connectors and click Add MuleSoft connector on the MuleSoft card.
You should see A guided page with five steps: region, create the app, choose read-only permissions, paste the client id and secret, test.
Pick your Anypoint region: United States, Europe or Government. Use the region you wrote down from the address bar in chapter 3.
In Anypoint (signed in as that trial), open the menu, then Access Management, then Connected Apps, then Create app.
Name it Cockpit. Choose the type App that acts on its own behalf (client credentials). Do not choose the other types: they need a person to sign in and will not work here.
Add only scopes that start with View or Read: View Organization, View Environment, Read Applications and View APIs Configuration. When Anypoint asks which business group and environments a scope applies to, choose every environment you want Cockpit to see. Save.
Caution Never add Create, Edit, Delete, Deploy or Manage.
Anypoint shows the client id and client secret once. Keep that page open. Copy both into the password manager.
In Cockpit, paste both, optionally give the connection a name, and save. They are encrypted and never shown again.
Press Test.
You should see "Anypoint accepted the credentials ... Cockpit can read this organisation." Then the organisation's name and its environments, for example Sandbox and Production. Nothing is changed.

[Screenshot: The Cockpit connected app's scopes in Anypoint]Figure 25

Figure 25. The Cockpit connected app's scopes in Anypoint. Capture details are item 25 in the list of screenshots to capture. Call-outs to draw: 1 App type; 2 The four read scopes; 3 Environments chosen.

Repeat for the second trial. Cockpit lets you pick which Anypoint organisation each chat uses. If Test fails with 401 or 403, the region, the app type or the scopes are wrong: recreate the app as client credentials with the four scopes.

6.3 GitHub

GitHub connects through Cockpit's own GitHub sign-in, so you create nothing. It asks for GitHub's standard repo access (and read:user). GitHub offers no read-only version of repo for private repositories, so GitHub describes it as read and write. What keeps Cockpit to reading is its mode, not the sign-in.

In Cockpit, open Connectors, find GitHub and click Connect.
You should see A guide page explaining what Cockpit reads (repositories, code, history, pull requests, checks, Actions runs, issues) and what the sign-in grants.
Click Connect GitHub. GitHub asks whether to let Cockpit access your account. Check that you are signed in as the test account, read the request, and click Authorize.
You should see You return to Connectors and GitHub says connected, with your login.
Press Test.
You should see "GitHub accepted the sign-in (your login) ... can read your repositories."

[Screenshot: GitHub asking to authorize Cockpit]Figure 26

Figure 26. GitHub asking to authorize Cockpit. Capture details are item 26 in the list of screenshots to capture. Call-outs to draw: 1 Signed-in account; 2 Requested access; 3 Authorize button.

ADVISORY · Taking it back

Disconnect in Cockpit stops Cockpit using the sign-in at once. To also revoke the access at GitHub, open GitHub Settings, then Applications, then Authorized OAuth Apps, find Cockpit and press Revoke.

6.4 Slack

Slack connects through your own Slack app in your workspace, so you control the permissions. Cockpit connects as you (a user token), so it can read what you can see and search it. It reads channels only; direct messages are a separate, optional consent that you can decline. Allow about fifteen minutes.

In Cockpit

Open Connectors, find Slack and click Connect. On the guide, click Connect Slack. With no app saved yet, it opens the page that saves your app.
You should see A page showing a Redirect URL, a list of scopes and boxes for Client id and Client secret.
Copy the Redirect URL. Leave this tab open.

In Slack (signed in to your test workspace)

Open api.slack.com/apps, choose Create New App, then From scratch. Name it Cockpit and pick your test workspace.
You should see The app's settings page.
Under OAuth & Permissions, add the Redirect URL you copied, and save it.
Add these User Token Scopes: channels:read, groups:read, channels:history, groups:history, search:read, users:read and chat:write. Also add the three Bot Token Scopes that Cockpit's page lists: channels:read, chat:write and users:read.
Under Basic Information, find App Credentials. Copy the Client ID and Client Secret into the password manager.
You should see Two values.

[Screenshot: The Slack app's OAuth and Permissions page]Figure 27

Figure 27. The Slack app's OAuth and Permissions page. Capture details are item 27 in the list of screenshots to capture. Call-outs to draw: 1 Redirect URL; 2 User Token Scopes; 3 Bot Token Scopes.

Back in Cockpit

Paste the Client id and Client secret and click Connect Slack. The secret is encrypted and never shown again.
Slack asks to let your app into the workspace. Check the workspace name at the top, then click Allow.
You should see You return to Connectors and Slack says connected, with the workspace name.
Press Test.
You should see "Slack accepted the sign-in (workspace) ... can read your channels." The access granted is listed in plain words, and it says Channels only.

TO BE CONFIRMED · Scope list

The save-your-app page lists only the three bot scopes, while Cockpit asks Slack for the user scopes above when Slack reading is switched on. The list here is the union of both, taken from the code. Confirm on the test drive that the connection succeeds with it, and tell the owner if Slack asks for anything else.

ADVISORY

Direct messages are a separate step on a page of their own, and a separate consent. Skip it in the test drive. If Slack returns direct-message access you did not ask for, Cockpit stores nothing and says so.

6.5 Postman

WARNING

A Postman API key can do everything its owner can do, and Postman cannot limit it to read-only. Use the Postman account you made for this test, never your main one.

In Postman, open your account settings, then API keys (go.postman.co/settings/me/api-keys).
You should see The API keys page.
Click Generate API Key. Name it Cockpit and choose when it expires. A shorter life is safer: 30 days suits a test.
You should see Postman shows the key once. Keep that page open.
Copy the key into the password manager.
In Cockpit, open Connectors, find Postman and click Connect. Read the first step (why a dedicated key), then paste the key in step 3. It is encrypted and never shown again.
Press Test in step 4.
You should see "Postman accepted the key (your username) ... Cockpit can read this account." Nothing is changed.

[Screenshot: Postman's API keys page with the new key]Figure 28

Figure 28. Postman's API keys page with the new key. Capture details are item 28 in the list of screenshots to capture. Call-outs to draw: 1 Key name; 2 Expiry.

CAUTION · When you finish testing

Disconnecting in Cockpit deletes the stored key but does not cancel it in Postman. Open Postman, Settings, API keys, and revoke the Cockpit key yourself.

6.6 Check everything

[Screenshot: The Connectors page with every test account connected]Figure 29

Figure 29. The Connectors page with every test account connected. Capture details are item 29 in the list of screenshots to capture. Call-outs to draw: 1 Two Salesforce orgs; 2 Two MuleSoft connections; 3 Capability tags.

Connected checklist

Salesforce shows two orgs, each Working or Not checked yet.
MuleSoft shows two connections, each with a passed Test.
GitHub, Slack and Postman each say connected, and each Test passed.
Every card's capability tag says Read only (Sandbox).
No secret, key or password is anywhere but the password manager.

6.7 Pass two: real systems

When the test drive has shown you what Cockpit reads and asks for, you can connect real systems. The procedures are the same. What changes is who is affected and what you should decide first.

WARNING

A real credential carries real power. Cockpit's Sandbox mode keeps Cockpit from using it to change anything, but the credential itself is not narrowed to read-only (except what you choose when creating a MuleSoft connected app). Anyone who gets the Consumer Secret, the client secret or the key can use it. Treat each as a password.

System	Decide before connecting a real one
Salesforce	Start with a sandbox (choose Sandbox, test.salesforce.com, or your My Domain in step 1) before any production org. Sign in as a user whose permissions are what you want the Copilot to see: the Copilot can read what that user can read, and with writes on, change what that user can change. Prefer a dedicated integration user.
MuleSoft	Choose scopes of View and Read only, and limit them to the environments Cockpit should see. Create a separate connected app for Cockpit so it can be revoked on its own.
GitHub	The sign-in covers every private repository the signed-in GitHub user can see. Use an account that can see only the repositories you want read, such as a dedicated user in your organisation. If your GitHub organisation restricts third-party apps, an organisation owner may need to approve Cockpit.
Slack	Cockpit connects as you and can read channels you are in and search what you can see. Use a workspace, or a user, that matches what you want read. Your Slack admin may need to approve the app.
Postman	Use a dedicated Postman user or service account that can only view the workspaces you want read, and a short expiry. Revoke the key in Postman when you are done.

Before a real system checklist

The test drive is complete and the answers in chapter 7 were as described.
The people who own the system know Cockpit will read it, and have agreed.
The credential belongs to a user or app with only the access you intend.
You know how to revoke it at the vendor, and have written it on your accounts sheet.
The mode chip says Sandbox.