Merge pull request #1107 from segmentio/leif/okta-updates

SCIM - Okta updates

Author: leifdreizler

src/segment-app/iam/images/okta_provisioning.png

@@ -15,11 +15,17 @@ To setup SCIM, you must first create an SSO connection. Once you [create your SS
 
 ## Configuration Instructions
 
-Segment officially supports [Okta](#okta-setup-guide), Azure AD, and OneLogin. However, you may still be able to use SCIM with another Identity Provider (IdP) by adapting the following instructions. If using a supported provider, start by searching for Segment in your provider's app catalog.
+Segment officially supports [Okta](#okta-setup-guide), Azure AD, and OneLogin. Each link includes specific setup instructions for that IdP. We recommend reading through the [features](#features) section of this page to understand which features of SCIM are supported.
 
-When you enable SCIM, your IdP asks for two values. One is the "base URL", the Segment base URL is: https://scim.segmentapis.com/scim/v2
+You may still be able to use SCIM with another Identity Provider (IdP) by adapting the following instructions.
 
-The other value needed is an API key or Authorization Header. To generate one, go to **Settings > Advanced Settings** in the Segment app, and find the SSO Sync section. Click **Generate SSO Token** and copy the generated token. Use this token for the API key or Authorization Header in your IdP.
+### Base URL
+
+Your IdP needs to know where to send SCIM requests. The Segment base URL is: https://scim.segmentapis.com/scim/v2
+
+### API Key
+
+The other value needed is an API key (sometimes referred to as an Authorization Header). To generate one, go to **Settings > Advanced Settings** in the Segment app, and find the SSO Sync section. Click **Generate SSO Token** and copy the generated token. Use this token for the API key or Authorization Header in your IdP.
 
 This page is located as part of the settings sidebar: https://app.segment.com/CUSTOMER_WORKSPACE_SLUG/settings/advanced
 
@@ -80,24 +86,28 @@ If your IdP supports the `displayName` attribute this can be mapped directly to
 ## Okta Setup Guide
 
 1. [Complete Okta Setup Guide for SSO](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Segment.html?baseAdminUrl=https://segment-admin.oktapreview.com&app=segment&instanceId=0oata15py1n3kQUo50h7)
-2. Click on the provisioning tab and follow the [Configuration Instructions](#configuration-instructions) to fill in the required fields.
-3. Once the credentials have been saved, select "To App" (left sidebar) under the provisioning tab. Click edit and select "Create Users" and "Deactivate Users," and then Save.
-4. Under the provisioning tab, click "Go to Profile Editor," and then "Mappings."
-5. The left tab represents the data that Segment will send to Okta. Click "do not map" for all attributes except `email` and `displayName`, click "Save Mappings," and "Apply Updates Now" (if prompted).
+2. Click on the "Provisioning" tab , click "Configure API Integration" and check "Enable API Integration"
+3. Follow the [instructions above](#api-key) to generate an API key. Copy and paste this value into the API Token field within Okta, and click Save.
+
+![](images/okta_provisioning.png)
+
+4. Once the credentials have been saved, select "To App" (left sidebar) under the provisioning tab. Click edit and select "Create Users" and "Deactivate Users," and then Save.
+5. Under the provisioning tab, click "Go to Profile Editor," and then "Mappings."
+6. The left tab represents the data that Segment will send to Okta. Click "do not map" for all attributes except `email` and `displayName`, click "Save Mappings," and "Apply Updates Now" (if prompted).
 
 ![](images/scim_attribute_mappings.png)
 
-6. Reopen "Mappings" and click the right right tab. This represents data that Okta will send to Segment. Again, click "do not map" for all attributes except `email` and `displayName`, "Save Mappings," and "Apply Updates Now" (if prompted).
-7. This should close the "Mappings" pop up. You can now delete all unused attributes from the bottom of the "Provisioning Tab". "Given Name" and "Family Name" are required by Okta, but unused by Segment.
+7. Reopen "Mappings" and click the right right tab. This represents data that Okta will send to Segment. Again, click "do not map" for all attributes except `email` and `displayName`, "Save Mappings," and "Apply Updates Now" (if prompted).
+8. This should close the "Mappings" pop up. You can now delete all unused attributes from the bottom of the "Provisioning Tab". "Given Name" and "Family Name" are required by Okta, but unused by Segment.
 
 ![](images/scim_delete_attributes.png)
 
-8. Navigate back to the Segment Okta app. You're now ready to assign people or groups! Please read through the [features](#features) sections of this doc to make sure you understand this functionality before continuing.
-9. We recommend assigning users to the Segment app by Okta group. Assignment by group allows you to easily manage which groups in your organization are able to authenticate to Segment. Users can also be assigned individually.
+9. Navigate back to the Segment Okta app. You're now ready to assign people or groups! Please read through the [features](#features) sections of this doc to make sure you understand this functionality before continuing.
+10. We recommend assigning users to the Segment app by Okta group. Assignment by group allows you to easily manage which groups in your organization are able to authenticate to Segment. Users can also be assigned individually.
 
 ![](images/scim_assignments.png)
 
-10. Once users have been assigned we recommend pushing your assigned Okta groups into Segment, and then going into the Segment app to assign permissions to these groups. You can also link Okta groups to an existing group within the Segment app using the Okta UI.
+11. Once users have been assigned we recommend pushing your assigned Okta groups into Segment, and then going into the Segment app to assign permissions to these groups. You can also link Okta groups to an existing group within the Segment app using the Okta UI.
 
 ![](images/scim_group_push.png)