Skip to content

Commit af326db

Browse files
stayseesongstayseesong
authored
Merge pull request #5422 from segmentio/DOC-735
OAuth 2.0 [DOC-735]
2 parents f716fe3 + de5f6a3 commit af326db

File tree

3 files changed

+152
-1
lines changed

3 files changed

+152
-1
lines changed

‎src/api/public-api/index.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,14 @@ Within seconds, GitHub scans each commit in public repositories for Public API t
3939

4040
Learn more about [GitHub's secret scanning program](https://docs.github.com/en/developers/overview/secret-scanning-partner-program){:target="_blank"}.
4141

42-
### Frequently Asked Questions
42+
## OAuth 2.0
43+
44+
> info ""
45+
> This feature is currently in pilot and is governed by Segment’s [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}.
46+
47+
You can authenticate and authorize the Public API using [OAuth 2.0](/docs/connections/oauth).
48+
49+
### Frequently asked questions
4350
#### What should I do if I see a notification that my token was exposed?
4451
In most cases, identifying and revoking an exposed token takes seconds. Segment recommends you check the [audit trail](/docs/segment-app/iam/audit-trail/) to ensure no unauthorized actions were taken with the token.
4552

‎src/connections/functions/source-functions.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,13 @@ Once configured, find the webhook URL - either on the **Overview** or **Settings
385385

386386
Copy and paste this URL into the upstream tool or service to send data to this source.
387387

388+
## OAuth 2.0
389+
390+
> info ""
391+
> OAuth 2.0 is currently in pilot and is governed by Segment’s [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}.
392+
393+
You can authenticate source functions with [OAuth 2.0](/docs/connections/oauth).
394+
388395
## Source function FAQs
389396

390397
##### What is the retry policy for a webhook payload?

‎src/connections/oauth.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: OAuth 2.0
3+
hidden: true
4+
---
5+
6+
OAuth 2.0 is an online authorization standard that uses tokens to grant access to API resources like Segment’s tracking API. You can use OAuth 2.0 as a security requirement for connections to third-party tools.
7+
8+
> info ""
9+
> This feature is currently in pilot and is governed by Segment’s [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. OAuth 2.0 only supports server to Segment communication, a machine-to-machine workflow. Take a look at the [supported sources](#supported-sources) to see what sources Segment supports.
10+
11+
## Permissions
12+
Depending on your workspace permissions, your access to OAuth apps is limited.
13+
14+
Segment Role | Permission
15+
------------ | -----------
16+
Workspace Owner | You can view, create, and edit OAuth apps.
17+
Workspace Member | You cannot view, create, or edit OAuth apps.
18+
Source Admin | You can view and edit OAuth apps. <br> You can connect and disconnect OAuth apps. <br> You can enable or disable OAuth enforcement.
19+
Source Read-only | You can only view OAuth apps.
20+
Function Admin | You can view and edit OAuth apps. <br>You can connect and disconnect OAuth apps. <br>You can enable and disable OAuth enforcement.
21+
Function Read-only | You can only view OAuth apps.
22+
23+
## Create an OAuth app
24+
25+
> info ""
26+
> You must have already created a workspace in Segment to use OAuth.
27+
28+
To create a new OAuth application:
29+
30+
1. Navigate to **Settings > Workspace settings** and select the Access Management tab.
31+
2. Select the **OAuth application** tab within the **Access Management** page.
32+
3. Click **Create OAuth app**.
33+
4. Enter the configuration settings:
34+
35+
Settings | Details
36+
-------- | -------
37+
Application name | The name of the OAuth app.
38+
Public key | Upload a public key in PEM format to authenticate through the OAuth application. You can upload a second public key after you create the OAuth application. You can create a public key by running the script: `openssl rsa -in private.pem -pubout -outform PEM -out public.pem`
39+
Public key name | Enter a name for your public key.
40+
Token expiration period | You can choose between: 1 day, 2 days, 3 days, 1 week, 2 weeks, 3 weeks, 30 days.
41+
Scope | This specifies what type of access you need for each API. See the list of [supported scopes](#supported-scopes).
42+
5. Click **Create**.
43+
44+
Once you create your OAuth app, you can now connect a source to your OAuth app.
45+
46+
## Connect a source to OAuth
47+
> info ""
48+
> OAuth only supports server-side sources. See the list of [supported sources](#supported-sources).
49+
50+
To connect a source to OAuth:
51+
52+
1. Navigate to **Connections > Sources**.
53+
2. Select the source you want to enable OAuth for.
54+
3. Go to the **Settings** tab of the source page and select **OAuth app**.
55+
4. Click **Connect OAuth app**.
56+
5. Select the OAuth app you want to connect the source to.
57+
6. Click **Connect**.
58+
59+
To disconnect your source from OAuth, click **Disconnect**.
60+
61+
## Enable a source to OAuth
62+
Once you've connected your source to OAuth, you can enable it. To enable your source:
63+
64+
1. Navigate to **Connections > Sources** and select your source.
65+
2. Go to the **Settings** tab of the source and select **OAuth app**.
66+
3. Turn the toggle on for **Enable OAuth**.
67+
68+
To disable your source from OAuth, turn the toggle off for **Enable OAuth**.
69+
70+
<!-- ## Request the access token
71+
72+
To request the access token, run:
73+
74+
```
75+
./gentoken.sh -k <private-key.pem> -i <key_id> -a <oauth_app_id> | jq '.access_token'
76+
```
77+
-->
78+
79+
## Edit an OAuth application
80+
To edit an existing OAuth application:
81+
82+
1. Navigate to **Settings > Workspace settings** and select the **Access Management** tab.
83+
2. Select the **OAuth application** tab within the **Access Management** page.
84+
3. Click the application name of the OAuth application you want to edit.
85+
4. On the **Overview** tab you can:
86+
* Revoke a token
87+
* Copy the Application ID and the Public key
88+
* Delete the OAuth application
89+
5. Select the **Settings** tab on the right window where you can:
90+
* Edit the **Application name**
91+
* Delete a public key
92+
* Add a new public key
93+
* Change the token expiration period
94+
* Edit your scope
95+
6. Click **Save changes**.
96+
97+
98+
## Delete an OAuth app
99+
> info ""
100+
> To delete an OAuth app, you must remove all connected sources from the app.
101+
102+
To delete an OAuth app:
103+
1. Navigate to **Settings > Workspace settings** and select the **Access Management** tab.
104+
2. Select the **OAuth application** tab within the **Access Management** page.
105+
3. Select the **App name** of the OAuth app you want to delete.
106+
4. Select **Delete OAuth app**.
107+
5. Enter the name of the OAuth app you want to delete.
108+
6. Click **Delete OAuth app**.
109+
110+
## Revoke a token
111+
112+
When security incidents expose access tokens, you can revoke your access token. To revoke a token:
113+
1. Navigate to **Settings > Workspace settings** and select the **Access Management** tab.
114+
2. Select the *OAuth application tab within the **Access Management** page.
115+
3. Select the **App name** with the token you want to delete.
116+
4. Enter the complete token
117+
5. Click **Revoke token**.
118+
119+
## Supported sources
120+
OAuth 2.0 currently supports these sources:
121+
* [HTTP Tracking API](/docs/connections/sources/catalog/libraries/server/http-api/)
122+
* [Node.js](/docs/connections/sources/catalog/libraries/server/node/)
123+
* [Public API](/docs/api/public-api/)
124+
* [Python](/docs/connections/sources/catalog/libraries/server/python/)
125+
* [Source Functions](/docs/connections/functions/source-functions/)
126+
127+
## Supported scopes
128+
OAuth 2.0 currently supports these scopes:
129+
130+
**Tracking API scopes**
131+
* `tracking_api:write`
132+
133+
**Source Functions scopes**
134+
* `functions:write`
135+
136+
**Public API scopes**
137+
* `public_api:read_write`

0 commit comments

Comments
 (0)