Skip to content
This repository was archived by the owner on Nov 15, 2024. It is now read-only.

Commit 7e7c488

Browse files
jimmyjaypjimmyjayp
committed
Documentation for OAuth handshake and Slack integration
1 parent a01d3b0 commit 7e7c488

File tree

4 files changed

+166
-49
lines changed

4 files changed

+166
-49
lines changed

‎api_server/docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# API Documentation Library
22

3-
- [Integrations and OAuth](integrations.md) - OAuth integration flow overview
3+
- [Integrations](integrations/README.md)
44
- [RabbitMQ Notes](rabbitmq.md)
55
- [Version Compatibility Matrix](version-matrix.md)
66
- [Unified Config File](unified-cfg-file.md) - Details on the unified structured config file used for backend services.

‎api_server/docs/integrations.md‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎api_server/docs/integrations/README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Integrations
2+
3+
## 3rd Party Services
4+
- [Slack](slack.md)
5+
6+
## OAuth & SSO Handshake
7+
8+
### OAuth Without SSO
9+
10+
1. User presses the **Connect to X** (3rd party) button in the webview.
11+
12+
1. Webview notifies the **LSP agent** which uses the IDE’s internal apis to
13+
hand-off a CS API request (URL) to a browser. This request initiates the
14+
handshake (`/web/provider-auth/<provider>`).
15+
16+
1. Browser makes CS API request which returns a 302 redirect link to the 3rd
17+
party site (referred to as the _**auth-me**_ link for purpose of this
18+
write-up). The redirect link contains:
19+
- CodeStream state object
20+
- 3rd party App ID
21+
- Callback URL (which we will call the provider-token URL) which also
22+
includes a state object containing the codestream runTime environment
23+
- App-specific scopes being requested
24+
25+
1. Browser makes the _**auth-me**_ request to the 3rd party site which ensures
26+
the request callback is valid & prompts the user to approve access to its
27+
service.
28+
29+
1. The 3rd party responding to the _**auth-me**_ request sends the callback URL
30+
(`/no-auth/provider-token` URL) as a 302 redirect to the browser along with:
31+
- A short-lived authorization code
32+
- The state object passed in from CodeStream
33+
34+
1. The browser, responding to the callback redirect, makes a
35+
`/no-auth/provider-token` request of the CS API which then:
36+
1. Validates the CodeStream state object
37+
1. Makes a server-to-server request from the CS API to the 3rd party service
38+
using the short-lived authorization code in order to get an **access token**.
39+
1. Stores the **access token** in the CodeStream database
40+
1. Responds with a 302 redirect for the browser to request a **Successful
41+
Auth** page on the marketing site.
42+
1. Publishes a broadcast message containing the **access token** on the
43+
user’s **me-channel** which the client's LSP agent receives. The client is
44+
now authorized and has the necessary token to place API requests directly
45+
to the 3rd party service.
46+
47+
### OAuth With SSO
48+
49+
Similar to non-SSO OAuth with a bit more apparatus.
50+
51+
1. User presses Sign-Up with X button in webview
52+
53+
1. CodeStream client generates a sign-up token (a guid)
54+
55+
1. This sign-up token is included in the initial CS API request URL (step 2
56+
above)
57+
58+
1. This sign-up token is also embedded within the state object within the
59+
auth-me link (step 3 above)
60+
61+
1. Once the IDE api’s pass the request off to a browser, the lsp agent enters a
62+
loop, polling the CS API waiting for the server to say that access is granted
63+
(the /no-auth/check-signup request).
64+
65+
1. The provider-token request (step 6 above) decodes and parses the embedded
66+
state object, including the sign-up token in the server-to-server call.
67+
68+
1. Once the CS API server completes the provider-token request, the polling
69+
check-signup request will respond successfully (access allowed) with a data
70+
package containing the me-object which includes the access token.
71+
72+
### Shared Development Apps
73+
74+
As CodeStream supports any number of development environments, including
75+
ephemeral ones, we have a mechanism to accommodate using one OAuth callback for
76+
multiple environments. In these cases, the state object that’s included in the
77+
callback URL (step 3 above) will contain the name of the CodeStream environment
78+
(sharedGeneral.runTimeEnvironment). Our nginx configuration will parse this
79+
state out of the URL’s query string and redirect it to the correct environment.
80+
This does not work in all cases. Some 3rd party apps are restrictive in their
81+
operation.
82+
83+
In these cases, the apiServer.authOrigin URL will be used to construct the
84+
callback URL in lieu of the apiServer.publicApiUrl value.
85+
86+
### Internal Environments
87+
88+
For environments that are only accessible behind the VPN, some integrations,
89+
notably **Slack** & **MS Teams**, which provide for server-to-server calls
90+
initiated by the 3rd party (such as **Interactive Components** in slack), will
91+
need to go through a proxy.
92+
93+
In these cases a predetermined URL will be configured in the CodeStream
94+
integration connector app on the 3rd party’s system, to send the requests to the
95+
CodeStream proxy which, in turn, will proxy them to the correct environment.
96+
97+
Today this is the same hostname as is used for the Shared Development Apps above
98+
(this should change).

‎api_server/docs/integrations/slack.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Integration with Slack
2+
3+
CodeStream's Slack integration allows for sharing codemark comments inside Slack
4+
channels. Once a CodeStream user completes the OAuth process with Slack and
5+
receives their access token, they are able to cross-post their CodeStream
6+
codemarks & replies to Slack.
7+
8+
From within a Slack channel, those cross-posted messages use Slack's
9+
**Interactive Components** App feature to allow Slack users to send replies back
10+
to CodeStream. Since this feature allows for only one callback URL per app, a
11+
dedicated CodeStream Slack App for each CodeStream environment is required.
12+
13+
All requests made by slack are signed and verified using [Slack's procedure for
14+
doing so](https://api.slack.com/docs/verifying-requests-from-slack).
15+
16+
17+
## Create the Slack App
18+
19+
Steps to create a Slack App for a non-production CodeStream environment.
20+
21+
1. Create a Slack App for connecting to CodeStream with the following
22+
settings.
23+
24+
* Go to https://api.slack.com/apps, make sure you're logged in to your
25+
workspace with administrative privileges, and press **Create New App**. We
26+
recommend naming it **CodeStream \<environment\>**.
27+
* Select the **OAuth & Permissions** feature, make these settings and save
28+
them.
29+
* Add the following Redirect URL:
30+
- `https://<codestream-api-host>/no-auth/provider-token/slack`
31+
* Add the following Scopes and save them (Request reasons included here):
32+
- **channels:read** - We allow users to select a public channel to share
33+
to.
34+
- **chat:write** - Users can send a copy of their messages from
35+
CodeStream to slack.
36+
- **groups:read** - We allow users to select a private channel to share
37+
to.
38+
- **im:read** - We allow users to select a direct message to share to.
39+
- **mpim:read** - We allow users to select a group DM to share to.
40+
- **users.profile:write** - We can update your slack status to reflect
41+
your current work.
42+
- **users:read** - We show the list of users.
43+
- **users:read.email** - We try to correlate CodeStream accounts with
44+
slack accounts via e-mail.
45+
* Select the **Interactivity & Shortcuts** section, make these settings
46+
and save them.
47+
* Turn on Interactivity (the switch on the upper right)
48+
* Add the following Request URL:
49+
- `https://<codestream-api-host>/no-auth/provider-action/slack`
50+
51+
## Add and/or Distribute Slack App
52+
53+
Add and/or distribute the Slack App as needed. It will need to be added to any
54+
workspaces that wish to connect with the corresponding CodeStream environment.
55+
56+
## Update the CodeStream Configuration
57+
58+
Finally, add the secrets and configuration data to the CodeStream API server's
59+
configuration file. The following data is needed:
60+
61+
From the **Basic Information** page of the Slack App, get these data and add
62+
them to the CodeStream configuration file.
63+
64+
- App ID
65+
- Client ID
66+
- Client Secret
67+
- Signing Secret

0 commit comments

Comments
 (0)