Skip to content

Commit b1443fe

Browse files
Paul-CornellPaul-Cornell
authored
Salesforce source connector: how-to video link, update how-to instructions (#417)
1 parent 383509f commit b1443fe

File tree

1 file changed

+86
-87
lines changed

1 file changed

+86
-87
lines changed

‎snippets/general-shared-text/salesforce.mdx‎

Lines changed: 86 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,103 @@
1-
- A Salesforce account. [Create an account](https://developer.salesforce.com/signup).
2-
- Your Salesforce username.
3-
- The Salesforce categories (objects) that you want to access, specified as a comma-separated list. Available categories include `Account`, `Campaign`, `Case`, `EmailMessage`, and `Lead`.
4-
- The OAuth consumer key (client ID) for the target Salesforce connected app in the account.
5-
- The contents of the private key (PEM) for the certificate that is associated for the Salesforce connected app. The PEM must be expressed as a
6-
single-line string without line breaks. To print this single-line string without line breaks, suitable for copying,
7-
you can run one of the following commands from your Terminal or Command Prompt. In this command, replace
8-
`<path-to-private-key-file>` with the path to the `.pem` file.
9-
10-
For macOS or Linux:
11-
12-
- The Salesforce categories (objects) that you want to access, specified as a comma-separated list. Available categories include `Account`, `Campaign`, `Case`, `EmailMessage`, and `Lead`.
13-
- The OAuth consumer key (client ID) for the Salesforce connected app.
14-
15-
1. If you do not already have a connected app, you will first need a certificate for the connected app that you will create later. If you do not already have a certificate, see
16-
[Certificates and Keys](https://help.salesforce.com/s/articleView?id=sf.security_keys_about.htm&language=en_US&type=5), for
17-
example to [generate a self-signed certificate](https://help.salesforce.com/s/articleView?id=sf.security_keys_creating.htm&type=5) and to download the
18-
resulting `.crt` file.
19-
2. To [create the connected app](https://help.salesforce.com/s/articleView?id=sf.connected_app_create.htm&type=5), follow the steps in
20-
[Configure Basic Connected App Settings](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_basics.htm&type=5) and
21-
[Enable OAuth Settings for API Integration](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_api_integration.htm&type=5) to create
22-
create and configure the app to use the JWT OAuth flow. The minimum fields to set for the app are:
1+
<iframe
2+
width="560"
3+
height="315"
4+
src="https://www.youtube.com/embed/5a-nh4t78V8"
5+
title="YouTube video player"
6+
frameborder="0"
7+
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
8+
allowfullscreen
9+
></iframe>
10+
11+
- A [Salesforce account](https://developer.salesforce.com/signup).
12+
- Your Salesforce username. To get this username, do the following:
13+
14+
1. Log in to your Salesforce account.
15+
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
16+
3. In the **Home** tab, under **Administration**, expand **Users**, and then click **Users**.
17+
4. Note the **User Name** value (_not_ the **Name** value) for your user.
18+
19+
- The names of the Salesforce categories (objects) that you want to access, specified as a comma-separated list.
20+
Available categories include `Account`, `Campaign`, `Case`, `EmailMessage`, and `Lead`.
21+
- A Salesforce connected app in your Salesforce account.
22+
23+
If you do not already have a Salesforce connected app, to create one, start by creating or getting the certificate (`.crt`) and private key (`.pem`) files
24+
that you will associate with the connected app.
25+
26+
If you do not have the certificate and private key files, you can use the `openssl` utility on your local machine to create your own
27+
private key and self-signed certificate, if your organization allows, by running the following commands, one command at a time:
28+
29+
```bash
30+
openssl genrsa -out MyPrivateKey.pem -traditional
31+
openssl req -new -key MyPrivateKey.pem -out MyCertificateSigningRequest.csr
32+
openssl x509 -req -in MyCertificateSigningRequest.csr -signkey MyPrivateKey.pem -out MyCertificate.crt -days 365
33+
```
34+
35+
Of course, you can change these preceding example filenames as needed. Be sure to store these generated files in a secure location.
36+
37+
To create a Salesforce connected app, do the following:
38+
39+
1. Log in to your Salesforce account.
40+
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
41+
3. In the **Home** tab, under **Platform Tools**, expand **Apps**, and then click **App Manager**.
42+
4. Click **New Connected App**.
43+
5. With **Create a Connected App** selected, click **Continue**.
44+
6. At a minimum, fill in the following, and then click **Save**:
2345

2446
- **Connected App Name**
25-
- **API Name**
47+
- **API Name** (can be the same as **Connected App Name**, but do not use spaces or punctuation)
2648
- **Contact Email**
27-
- Check **Enable OAuth Settings**
28-
- **Callback URL** - Can be set to `https://localhost` if you have no special requirements for additional authentication for this app outside of Unstructured.
29-
- Check **Use digital signatures**, and
30-
- **Selected OAuth Scopes** - Select **Manage user data via APIs (api)** (recommended), or **Full access (full)**.
49+
- Under **API (Enable OAuth Settings)**, check **Enable OAuth Settings**.
50+
- For **Callback URL**, entering `https://localhost` is okay if you won't be using this connected app for other special authentication scenarios.
51+
- Check **Use digital signatures**, click **Choose File**, and browse to and select your certificate (`.crt`) file.
52+
- For **Selected OAuth Scopes**, move the following entries from the **Available OAuth Scopes** list to the **Selected OAuth Scopes** list:
53+
54+
- **Manage user data via APIs (api)**
55+
- **Perform requests on your behalf at any time (refresh_token, offline_access)**
56+
57+
- Uncheck **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows**.
58+
- Leave **Require Secret for Web Server Flow** checked.
59+
- Leave **Require Secret for Refresh Token Flow** checked.
60+
- Check **Enable Authorization Code and Credentials Flow**.
61+
62+
7. On the connected app's details page, click **Manage**, click **Edit Policies**, set the following under **OAuth Policies**, and then click **Save**:
63+
64+
- Set **Permitted Users** to **All users may self-authorize**.
65+
- Set **IP Relaxation** to **Relax IP restrictions**.
66+
- Set **Refresh Token Policy** to **Refresh token is valid until revoked**.
67+
68+
- The OAuth consumer key (client ID) for the Salesforce connected app.
3169

32-
3. [Get the consumer key (client ID)](https://help.salesforce.com/s/articleView?id=sf.connected_app_rotate_consumer_details.htm&type=5) for the app.
33-
4. [Get the private key](https://help.salesforce.com/s/articleView?id=sf.task_create_a_certificate_and_private_key.htm&type=5) for the app.
70+
To get the Salesforce connected app's consumer key, do the following:
3471

35-
- The private key (`.pem`) file for the certificate (`.crt`) file. To generate the private key file, you can use a utility such as `openssel`, as follows:
72+
1. Log in to your Salesforce account.
73+
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
74+
3. In the **Home** tab, under **Platform Tools**, expand **Apps**, and then click **App Manager**.
75+
4. In the list of apps, click the arrow next to the target connected app, and click **View**.
76+
5. Click **Manage Consumer Details**.
77+
6. Complete the on-screen security verification.
78+
7. Note the **Consumer Key** value.
3679

37-
```bash
38-
openssl x509 -in MyCertificate.crt -out MyCertificate.pem -outform PEM
80+
- You must use your Salesforce account to do a one-time approval of the Salesforce connected app by using its consumer key and callback URL. To do this, while you are logged in to your
81+
Salesforce account, browse to the following URL, replacing `<client-id>` with the consumer key value. This URL assumes that the callback URL
82+
is `https://localhost`:
83+
84+
```
85+
https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=<client-id>&redirect_uri=https%3A%2F%2Flocalhost
3986
```
4087

41-
To ensure maximum compatibility across Unstructured service offerings, you should give the private key information to Unstructured as
42-
a single-line string that contains the contents of the downloaded private key file (and not the prviate key file itself).
43-
To print this single-line string without line breaks, suitable for copying, you can run one of the following commands from your Terminal or Command Prompt.
44-
In this command, replace `<path-to-downloaded-key-file>` with the path to the private key file that you generated by following the preceding instructions.
88+
- To ensure maximum compatibility across Unstructured service offerings, you should give the contents of the private key (`.pem`) file to Unstructured as
89+
a string that contains the contents of the file (_not_ the private key file itself).
90+
To print this string suitable for copying, you can run one of the following commands from your Terminal or Command Prompt.
91+
In this command, replace `<path-to-private-key-file>` with the path to the private key file.
4592

4693
- For macOS or Linux:
4794

4895
```bash
49-
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <path-to-private-key-file>
96+
cat <path-to-private-key-file>
5097
```
5198

5299
- For Windows:
53100

54-
55101
```text
56-
(Get-Content -Path "<path-to-private-key-file>" -Raw).Replace("`r`n", "\n")
57-
```
58-
59-
To get your Salesforce username, do the following:
60-
61-
1. Log in to your Salesforce account.
62-
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
63-
3. In the search box, search for and go to **Users**.
64-
4. Note the **Name** value (_not_ the **User Name** value) for your user.
65-
66-
If you do not already have a Salesforce connected app, to create one, start by creating or getting the certificate (`.crt`) and private key (`.pem`) files
67-
that you will associate with the connected app. If you do not have the certificate and private key, you can use your local machine to create your own
68-
private key and self-signed certificate, if your organization allows, by running the following commands, one command at a time:
69-
70-
```bash
71-
openssl genrsa -out MyPrivateKey.pem -traditional
72-
openssl req -new -key MyPrivateKey.pem -out MyCertificateSigningRequest.csr
73-
openssl x509 -req -in MyCertificateSigningRequest.csr -signkey MyPrivateKey.pem -out MyCertificate.crt -days 365
74-
```
75-
76-
Be sure to store these generated files in a secure location.
77-
78-
To create a Salesforce connected app, do the following:
79-
80-
1. Log in to your Salesforce account.
81-
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
82-
3. In the search box, search for and go to **App Manager**.
83-
4. Click **New Connected App**.
84-
5. With **Create a Connected App** selected, click **Continue**.
85-
6. At a minimum, fill in the following, and then click **Save**:
86-
87-
- **Connected App Name**
88-
- **API Name** (can be same as **Connected App Name**, but do not use spaces or punctuation)
89-
- **Contact Email**
90-
- Check **Enable OAuth Settings**.
91-
- For **Callback URL**, entering `http://localhost` is okay if you won't be using this connected app for other special authentication scenarios.
92-
- Check **Use Digital Signatures**. Click **Choose File**, and browse to and select your certificate (`.crt`) file.
93-
- For **Selected OAuth Scopes**, add **Manage user data via APIs (api)** (recommended) or **Full access (full)**.
94-
95-
To get the Salesforce connected app's consumer key, do the following:
96-
97-
1. Log in to your Salesforce account.
98-
2. In the top navigation bar, click the **Quick Settings** (gear) icon, and then click **Open Advanced Setup**.
99-
3. In the search box, search for and go to **App Manager**.
100-
4. In the list of apps, click the arrow next to the target connected app, and click **View**.
101-
5. Click **Manage Consumer Details**.
102-
6. Complete the on-screen security verification.
103-
7. Note the **Consumer Key** value.
104-
102+
Get-Content <path-to-private-key-file>
103+
```

0 commit comments

Comments
 (0)