Skip to content

Commit a3b8970

Browse files
stayseesongstayseesong
authored
Merge pull request #1755 from segmentio/DOC-270
DOC-270 Added warnings for using the Workspace ID as the External/Secret ID
2 parents c318fd6 + 9794ac9 commit a3b8970

File tree

4 files changed

+107
-89
lines changed

4 files changed

+107
-89
lines changed

‎src/connections/destinations/catalog/amazon-kinesis-firehose/index.md

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -178,27 +178,33 @@ Replace that snippet with the following, and replace the contents of the array w
178178

179179
#### Use a single secret ID
180180

181-
If you have so many sources using Kinesis that it is impractical to attach all of their IDs to your IAM role, you can set a single ID to use instead. **This approach requires that you securely store a secret value, so we recommend that you use the method above if at all possible. **
181+
If you have many sources using Kinesis that it's impractical to attach all of their IDs to your IAM role, you can set a single ID to use instead. *This approach requires that you securely store a secret value, so we recommend that you use the method above if at all possible.*
182182

183-
To set this value, go to the Kinesis Firehose destination settings from each of your Segment sources and set the **Secret ID'** to a value of your choosing. This value is a secret and should be treated as sensitively as a password. Once all of your sources have been updated to use this value, find the IAM role you created for this destination in the AWS Console in Services > IAM > Roles. Click on the role, and navigate to the **Trust Relationships** tab. Click **Edit trust relationship**. You should see a snippet that looks something that looks like this:
183+
To set this value for a single Secret ID:
184+
1. Go to the Kinesis Firehose destination settings from each of your Segment sources.
185+
2. Click **Secret ID** and enter your Workspace ID.
186+
* **NOTE:** For security purposes, Segment recommends you to use your Segment Workspace ID as your Secret ID. If you’re using a Secret ID different from your Workspace ID, you're susceptible to attacks. You can find your Workspace ID by going to: **Settings > Workspace Settings > ID** from the Segment dashboard.
187+
3. Once all of your sources are updated to use this value, find the IAM role you created for this destination in the AWS Console in **Services > IAM > Roles**.
188+
4. Select the role and navigate to the **Trust Relationships** tab.
189+
5. Click **Edit trust relationship**. You should see a snippet that looks something that looks like this:
184190

185-
```json
186-
{
187-
"Version": "2012-10-17",
188-
"Statement": [
191+
```json
189192
{
190-
"Effect": "Allow",
191-
"Principal": {
192-
"AWS": "arn:aws:iam::595280932656:root"
193-
},
194-
"Action": "sts:AssumeRole",
195-
"Condition": {
196-
"StringEquals": {
197-
"sts:ExternalId": "YOUR_SEGMENT_SOURCE_ID"
193+
"Version": "2012-10-17",
194+
"Statement": [
195+
{
196+
"Effect": "Allow",
197+
"Principal": {
198+
"AWS": "arn:aws:iam::595280932656:root"
199+
},
200+
"Action": "sts:AssumeRole",
201+
"Condition": {
202+
"StringEquals": {
203+
"sts:ExternalId": "YOUR_SEGMENT_SOURCE_ID"
204+
}
205+
}
198206
}
199-
}
207+
]
200208
}
201-
]
202-
}
203-
```
204-
Replace your source ID (found at "YOUR_SEGMENT_SOURCE_ID") with your secret ID.
209+
```
210+
6. Replace the value of `sts:ExternalId` ( "YOUR_SEGMENT_SOURCE_ID") with the Secret ID / Workspace ID value from the previous step.

‎src/connections/destinations/catalog/amazon-kinesis/index.md

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ Replace that snippet with the following, and replace the contents of the array w
182182

183183
### Update IAM to Support PutRecords
184184

185-
The Kinesis destination defaults to use PutRecords. A previous version of the IAM policy document only granted `PutRecord` access, which can slow down Kinesis write times and degrade data deliverability. Substitute the updated policy document above to grant Kinesis `PutRecords` (plural) and allow batching, like this:
185+
The Kinesis destination defaults to use PutRecords. A previous version of the IAM policy document only granted `PutRecord` access, which can slow down Kinesis write times and degrade data deliverability. Substitute the updated policy document above to grant Kinesis `PutRecords` (plural) and allow batching, like this:
186186
```json
187187
{
188188
"Version": "2012-10-17",
@@ -205,25 +205,31 @@ The Kinesis destination defaults to use PutRecords. A previous version of the IA
205205
After you update the IAM policy, Segment systems default to use PutRecords for more efficient data transmission. This is a zero-downtime change and does not impact your data other than increasing the deliverability success rate.
206206

207207
### Use a single secret ID
208-
If you have so many sources using Kinesis that it is impractical to attach all of their IDs to your IAM role, you can instead opt to set a single ID to use instead. This approach should be avoided in favor of the above approach if possible since it will result in you having to keep track of a secret value. To set this value, go to the Kinesis destination settings from each of your Segment sources and set the 'Secret ID' to a value of your choosing. This value is a secret and should be treated as sensitively as a password. Once all of your sources have been updated to use this value, find the IAM role you created for this destination in the AWS Console in Services > IAM > Roles. Click on the role, and navigate to the **Trust Relationships** tab. Click **Edit trust relationship**. You should see a snippet that looks something that looks like this:
209-
210-
```json
211-
{
212-
"Version": "2012-10-17",
213-
"Statement": [
208+
If you have many sources using Kinesis that it's impractical to attach all of their IDs to your IAM role, you can instead opt to set a single ID to use. To set this value:
209+
1. Go to **Connections > Destinations > Amazon Kinesis** for each of your Segment sources.
210+
2. Click **Secret ID** and enter your Workspace ID.
211+
* **NOTE:** For security purposes, Segment recommends you to use your Workspace ID as your Secret ID. If you’re currently using a Secret ID different from your Workspace ID, you’ll be susceptible to attacks. You can find your Workspace ID by going to: **Settings > Workspace Settings > ID**.
212+
3. Once all of your sources have been updated to use this value, find the IAM role you created for this destination in the AWS Console in **Services > IAM > Roles**.
213+
4. Click on the role and navigate to the **Trust Relationships** tab.
214+
5. Click **Edit trust relationship**. You should see a snippet that looks something that looks like this:
215+
216+
```json
214217
{
215-
"Effect": "Allow",
216-
"Principal": {
217-
"AWS": "arn:aws:iam::595280932656:root"
218-
},
219-
"Action": "sts:AssumeRole",
220-
"Condition": {
221-
"StringEquals": {
222-
"sts:ExternalId": "YOUR_SEGMENT_SOURCE_ID"
218+
"Version": "2012-10-17",
219+
"Statement": [
220+
{
221+
"Effect": "Allow",
222+
"Principal": {
223+
"AWS": "arn:aws:iam::595280932656:root"
224+
},
225+
"Action": "sts:AssumeRole",
226+
"Condition": {
227+
"StringEquals": {
228+
"sts:ExternalId": "YOUR_SEGMENT_SOURCE_ID"
229+
}
230+
}
223231
}
224-
}
232+
]
225233
}
226-
]
227-
}
228-
```
229-
Replace your source ID (found at "YOUR_SEGMENT_SOURCE_ID") with your secret ID.
234+
```
235+
6. Replace the value of `sts:ExternalId` (`"YOUR_SEGMENT_SOURCE_ID"`) with your Secret ID.

‎src/connections/destinations/catalog/amazon-lambda/index.md

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -57,43 +57,47 @@ There are two options for setting up the IAM policy and role:
5757

5858
### Use CloudFormation
5959

60-
Using CloudFormation minimizes the set up steps needed, and is Segment's recommended way to create your Lambda's policy and role.
60+
Using CloudFormation minimizes the setup steps needed, and is Segment's recommended way to create your Lambda's policy and role. To use CloudFormation:
61+
1. Create the CloudFormation Template.
62+
1. Copy or download the [SegmentLambdaDestinationCFTemplate](https://github.com/segmentio/segment-lambda-recipes/blob/ead6c0f77deb38cea7ed486a7b98b47207796b5c/SegmentLambdaDestinationCFTemplate#L1){:target="_blank"} from the [segment-lambda-recipes](https://github.com/segmentio/segment-lambda-recipes){:target="_blank"} GitHub repo.
63+
2. Save the file with a name you like, but make sure it doesn't have a file extension.
64+
2. Create the CloudFormation stack.
65+
1. Within the AWS Console, navigate to **CloudFormation > Stacks**.
6166

62-
**Create the CloudFormation Template**
67+
![](images/CloudFormationStackNav.png)
6368

64-
Copy or download the [SegmentLambdaDestinationCFTemplate](https://github.com/segmentio/segment-lambda-recipes/blob/ead6c0f77deb38cea7ed486a7b98b47207796b5c/SegmentLambdaDestinationCFTemplate#L1) from our [segment-lambda-recipes](https://github.com/segmentio/segment-lambda-recipes) GitHub repo. Save the file with whatever name you like, but make sure it doesn't have a file extension.
69+
2. Click **Create Stack**.
6570

66-
**Create the CloudFormation stack**
71+
![](images/CloudFormationCreateStack.png)
6772

68-
Within the AWS Console, navigate to CloudFormation. Navigate to the Stacks page.
73+
3. On the **Select Template** page, select **Upload a template to Amazon S3**. Using **Choose File**, select the SegmentLambdaDestinationCFTemplate you downloaded in the previous step.
6974

70-
![](images/CloudFormationStackNav.png)
75+
4. Click **Next**.
7176

72-
Click the "Create Stack" button.
77+
![](images/CloudFormationUploadTemplate.png)
7378

74-
![](images/CloudFormationCreateStack.png)
79+
5. Give your stack a name.
80+
6. For the **ExternalId** parameter, enter the "External ID" setting in your Segment Lambda destination settings. This should be your **Workspace ID**.
81+
* **NOTE:** For security purposes, Segment recommends you to use your Workspace ID as your External ID. If you’re currently using an External ID different from your Workspace ID, you’ll be susceptible to attacks. You can find your Workspace ID by going to: **Settings > Workspace Settings > ID**.
82+
7. The **LambdaARN** parameter corresponds to the **Lambda** setting in your Segment Lambda destination settings.
7583

76-
On the "Select Template" page, select "Upload a template to Amazon S3", then using "Chose File", select the SegmentLambdaDestinationCFTemplate you created/downloaded in the previous step.
84+
![](images/CloudFormationStackDetails.png)
7785

78-
Click "Next".
86+
8. You can leave the next page as is, no changes needed.
87+
9. On the last page, review your template details and click **Create**.
88+
10. You will now see your new Stack listed in the Stacks page.
7989

80-
![](images/CloudFormationUploadTemplate.png)
90+
![](images/CloudFormationCreateInProgress.png)
8191

82-
Give your stack a meaningful name. The "ExternalId" parameter corresponds to the "External ID" setting in your Segment Lambda destination settings. The "LambdaARN" parameter corresponds to the "Lambda" setting in your Segment Lambda destination settings.
92+
11. Once the status is **CREATE_COMPLETE**, click on the name of your Stack.
93+
12. On the Stack Detail page under the **Resources** section, you will see a policy and role listed.
8394

84-
![](images/CloudFormationStackDetails.png)
95+
![](images/CloudFormationLambdaRole.png)
8596

86-
You can leave the next page as is, no changes needed. On the last page, review your template details and click "Create".
97+
13. Click the **Physical ID** of the role. You will be redirected to the summary page for the role within the IAM console.
98+
14. Copy the **Role ARN** and copy it into the **Role Address** setting in your Segment Lambda destination settings.
8799

88-
You should now see your new Stack listed in the Stacks page.
89-
90-
![](images/CloudFormationCreateInProgress.png)
91-
92-
Once the status is "CREATE_COMPLETE", click on the name of your Stack. On the Stack Detail page, under the "Resources" section, you should see a policy and role listed.
93-
94-
![](images/CloudFormationLambdaRole.png)
95-
96-
Click on the "Physical ID" of the role. You will be redirected to the summary page for the role within the IAM console. Copy the "Role ARN" and copy it into the "Role Address" setting in your Segment Lambda destination settings. Using the examples provided, your Segment Lambda destination settings would now look something like this:
100+
Using the examples provided, your Segment Lambda destination settings will look something like this:
97101

98102
![](images/SegmentLambdaSettingsPostCF.png)
99103

‎src/connections/destinations/catalog/amazon-personalize/index.md

Lines changed: 29 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -15,23 +15,23 @@ Developing the machine-learning capabilities necessary to produce these sophisti
1515

1616
{% include content/connection-modes.md %}
1717

18-
There are a few pre-requisites:
18+
There are a few pre-requisites before getting started. They are:
1919

2020
1. Segment data flowing into an S3 destination OR a warehouse
21-
1. Ability to create AWS Glue jobs (only required if using S3 to [train your model](#train-your-model))
22-
2. Ability to deploy Lambda functions in Amazon Web Services
23-
3. Access to AWS Personalize
21+
2. You have the ability to create AWS Glue jobs (only required if using S3 to [train your model](#train-your-model))
22+
3. You have the ability to deploy Lambda functions in Amazon Web Services
23+
4. You have access to AWS Personalize
2424

25-
don't have an S3, Redshift warehouse, or Snowflake warehouse set up? You can read more about setting up S3 [here](https://segment.com/docs/connections/storage/catalog/amazon-s3/), Redshift [here](https://segment.com/docs/connections/storage/catalog/redshift/), and Snowflake [here](https://segment.com/docs/connections/storage/catalog/snowflake/).
25+
If you don't have S3, Redshift warehouse, or Snowflake warehouse configured, you can read more about setting up [S3](/docs/connections/storage/catalog/amazon-s3/), [Redshift](/docs/connections/storage/catalog/redshift/), and [Snowflake](/docs/connections/storage/catalog/snowflake/).
2626

2727
***If you're a Segment business tier customer, contact your Success contact to initiate a replay to S3 or your Warehouse.***
2828

2929

3030
There are three main parts to using Amazon Personalize with Segment:
3131

32-
1. [**Train your model**]() on historical data in S3 or a Warehouse.
33-
2. [**Create a Personalize Dataset Group**]() and Campaign
34-
3. [**Connect Recommendations**] and Live Event Updates to your Campaign and Segment
32+
1. [**Train your model**](/docs/connections/destinations/catalog/amazon-personalize/#train-your-model) on historical data in S3 or a Warehouse.
33+
2. [**Create a Personalize Dataset Group**](/docs/connections/destinations/catalog/amazon-personalize/#create-personalize-dataset-group-solution-and-campaign) and Campaign
34+
3. [**Connect Recommendations**](/docs/connections/destinations/catalog/amazon-personalize/#getting-recommendations-and-live-event-updates) and Live Event Updates to your Campaign and Segment
3535

3636
## Train Your Model
3737

@@ -645,22 +645,23 @@ In the next section, we will build a real-time clickstream ingestion pipeline th
645645

646646
## Getting Recommendations and Live Event Updates
647647

648-
Once you deployed your Personalize solution and enabled a Campaign, your Lambda can consume event notifications from Segment and use the Solution and Campaign to react to events which will drive your business cases.
648+
Once you deploy your Personalize solution and enable a Campaign, your Lambda instance consumes event notifications from Segment and use the Solution and Campaign to react to events which drive your business cases.
649649

650-
The example code we provide below shows how to forward events to the Personalize Solution you deployed to keep your model updated. It then forwards an `identify` event back to Segment with the recommendations from your Solution.
650+
The example code Segment provides below shows how to forward events to the Personalize Solution you deployed to keep your model updated. It then forwards an `identify` event back to Segment with the recommendations from your Solution.
651651

652652

653653
### Set up Segment IAM policy & role for invoking your Lambda
654654

655655
Segment will need to be able to call ("invoke") your Lambda in order to process events. This requires you to configure an IAM role for your Lambda which allows the Segment account to invoke your function.
656656

657-
**Create an IAM policy.**
657+
#### Create an IAM policy
658+
To create an IAM policy:
659+
1. Sign in to the [Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/){:target="_blank"} and follow these instructions to [Create an IAM policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html){:target="_blank"} to allow Segment permission to invoke your Lambda function.
658660

659-
Sign in to the [Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/) and follow these instructions to [Create an IAM policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) to allow Segment permission to invoke your Lambda function.
661+
2. Select **Create Policy from JSON** and use the following template policy in the `Policy Document` field. Be sure to change the `{region}`, `{account-id}` and `{function-names}` with the applicable values. Here's example of a Lambda ARN `arn:aws:lambda:us-west-2:355207333203:function:``my-example-function`.
660662

661-
Select the **Create Policy from JSON** option and use the following template policy in the `Policy Document` field. Be sure to change the {region}, {account-id} and {function-names} with the applicable values. An example of a Lambda ARN `arn:aws:lambda:us-west-2:355207333203:function:``my-example-function`.
662-
663-
_Note: you can put in a placeholder ARN for now, as you will need to come back to this step to update with the ARN of your Lambda once that's been created._
663+
> note ""
664+
> **NOTE:** You can put in a placeholder ARN for now, as you will need to come back to this step to update with the ARN of your Lambda once that's been created.
664665
665666
```json
666667
{
@@ -682,21 +683,22 @@ _Note: you can put in a placeholder ARN for now, as you will need to come back t
682683
}
683684
```
684685

686+
#### Create an IAM role
687+
To create an IAM role:
688+
1. Sign in to the [Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/){:target="_blank"} and follow these instructions to [Create an IAM role](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console){:target="_blank"} to allow Segment permission to invoke your Lambda function.
689+
2. While setting up the new role, add the policy you created in the [previous step](/docs/connections/destinations/catalog/amazon-personalize/#create-an-iam-policy).
690+
3. Finish with any other set up items you may want (like `tags`).
691+
4. Search for and click on your new roles from the [IAM home](https://console.aws.amazon.com/iam/home#/home){:target="_blank"}.
692+
5. Select the **Trust Relationships** tab, then click **Edit trust relationship**.
685693

686-
**Create an IAM role**
687-
688-
Sign in to the [Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/) and follow these instructions to [Create an IAM role](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) to allow Segment permission to invoke your Lambda function.
689-
690-
While setting up the new role, add the policy you created in the previous step.
691-
692-
Finish with any other set up items you may want (like `tags`). Once that's complete, search for and click on your new roles from the [IAM home](https://console.aws.amazon.com/iam/home#/home).
693-
694-
Select the "Trust Relationships" tab, then click the "Edit trust relationship" button.
694+
![](images/LambdaTrustRelationship.png)
695695

696-
![](images/LambdaTrustRelationship.png)
696+
6. Copy and paste the following into your trust relationship. You should replace `<your-source-id>` with either the Source ID of the attached Segment source (the default) or the custom external ID you set in your Amazon Lambda destination settings.
697697

698-
Copy and paste the following into your trust relationship. You should replace `<your-source-id>` with either the Source ID of the attached Segment source (the default) or whatever custom external id you set in your Amazon Lambda destination settings.
699-
Note: Source ID *can be found by navigating to Settings > API Keys from your Segment source homepage.*
698+
> note ""
699+
> **NOTE:** Your Source ID can be found by navigating to **Settings > API Keys** from your Segment source homepage.
700+
>
701+
> If you're using an External ID, for security purposes, Segment recommends you to use your Segment Workspace ID as your External ID. If you use an External ID different from your Workspace ID, you’re susceptible to attacks. You can find your Workspace ID by going to: **Settings > Workspace Settings > ID** in the Segment dashboard.
700702
701703
```json
702704
{

0 commit comments

Comments
 (0)