Blake/exp 4488 update ssoscim docs (#586)

* re-order authentication options

* Add better SCIM docs

* Okta SCIM integration should be hidden

* kill dead images

* Warnings about only getting the chance to setup SCIM once

* Add internal link

Author: btthomas

docs/administration/authentication.md

@@ -8,13 +8,13 @@ sidebar_position: 3
 
 Eppo supports the following enterprise authentication options:
 
-- SAML
-- OpenID Connect
-  - [Okta](/administration/okta)
+- [Okta](/administration/okta)
 - Google Workspace
 - Microsoft Azure AD
 - ADFS
 - LDAP
 - Ping Federate
+- SAML
+- OpenID Connect  
 
 Follow the guides linked above or reach out to your Eppo team if you would like one of these options configured for your users.

docs/administration/scim.md

@@ -13,23 +13,26 @@ Provisioning users through SCIM (the System for Cross-domain Identity Management
 We partner with [WorkOS](https://workos.com/docs/integrations/scim) to provide a secure SCIM connection using the 2.0 version of the SCIM protocol. Please contact Eppo with the email of your IT admin; 
 they will receive an onboarding email from WorkOS with an onboarding wizard containing the necessary information to complete the setup tailored to your organization.
 
-Eppo offers support for:
+Eppo's SCIM integration will enable you to do the following via your IdP:
 
-* Provisioning new users
-* Updating user profiles: name & role.
-* De-provisioning users
+* Provision new users
+* Update user's profiles
+* De-provision users
+* Manage user roles via Groups
 
-:::note
-Users created with SCIM can only be updated through your IdP.
-:::
+Users managed with SCIM can only be updated through your IdP.
 
 Existing users can be populated through a programmatic process; please contact Eppo to request this.
 
+:::warning
+Once you complete the WorkOS setup, you will not be able to get back into WorkOS. Please read the instructions and prepare your Role groups before starting.
+:::
+
 ## Okta
 
 [Setup guide from WorkOS](https://workos.com/docs/integrations/okta-scim).
 
-* Create a new Okta app or use an existing one configured for SSO. 
+* Create a new Okta app, do not show it to end users.
 * Enable SCIM provisioning.
 
 <img src="/img/administration/scim/scim1.png" alt="enable SCIM provisioning" width="600" />
@@ -47,38 +50,42 @@ Fill out the fields as shown in the screenshot above: Paste the base URL from th
 * For Unique identifier field for users, set to "email". 
 * Check the Push New Users and Push Profile Updates. 
 * For Authentication Mode, select HTTP Header and paste the Bearer Token from the WorkOS set up to the field. 
-* Click Save.  
-
-### Attributes and Roles on Okta
-
-To setup Attribute Mapping, you will see that we support a custom attribute called `eppoMemberRole`. This optional custom attribute allows an IT admin to set the user's Eppo role from within the IdP.
-
-That attribute can only have the following attributes (strings): `default`, `viewer`, `experiment_editor`, `data_owner`, `admin`
-
-The `default` value is useful for migrating to managing roles in the Idp: it will keep the user's role as it is in Eppo, or if the user is new, it will assume the default user role as configured in Eppo.
-
-<img src="/img/administration/scim/scim-custom-attribute.png" alt="configure Okta API Integration" width="600" />
+* Click Save. 
+
+To assign users and groups:
+* Navigate to the assignments tab.
+* Click the Assign button and select Assign to Groups.
+* Select the groups you want to assign to the application.
+* Click Save.
+
+To push groups for role assignment: (see [User roles via Groups](#user-roles-via-groups) below for more details about roles)
+* Navigate to the Push Groups tab.
+* Click the Push Groups button and select Find groups by name.
+* Select the groups for each role.
+* Check the box for Push Immediately.
+* Click Save.
+* In WorkOS, you can now map the groups to the Eppo role.
 
 ## Microsoft Entra
 
 [Setup guide from WorkOS](https://workos.com/docs/integrations/entra-id-scim).
 
 * Create a new Entra app or use an existing one configured for SSO. 
 * Enable SCIM provisioning.
+* On the provisioning tab, enable Microsoft Entra ID Users and Microsoft Entra ID Groups.
 
-### Attributes and Roles on Entra
+## Other IdPs
 
-Enable mapping for Microsoft Entra ID Users.
+Eppo supports additional IdPs: OneLogin, PingFederate, Rippling and JumpCloud. Please contact Eppo for onboarding guides on these platforms.
 
-<img src="/img/administration/scim/scim-entra2.png" alt="configure Entra custom attribute" width="600" />
+## User roles via Groups
 
-Configure user mapping.
+[Directory group role assignment from WorkOS](https://workos.com/docs/directory-sync/identity-provider-role-assignment/directory-group-role-assignment).
 
-* Add a custom attribute called `eppoMemberRole`. This optional custom attribute allows an IT admin to set the user's Eppo role from within the IdP.
-* Create mapping for the attribute `eppoMemberRole` from your organization or define it with a static value.
+<img src="/img/administration/scim/scim-workos-groups.png" alt="Map groups to Eppo roles" width="600" />
 
-<img src="/img/administration/scim/scim-entra1.png" alt="configure Entra custom attribute" width="600" />
+To configure user roles via groups, you will need to create a group in your IdP for each Eppo role and map it to the Eppo role in the WorkOS setup.
 
-## Other IdPs
+Our roles are: `Admin`, `Data Owner`, `Experiment Editor`, and `Viewer`. See [our role documentation](/administration/users-and-permissions/) for more details.
 
-Eppo supports additional IdPs: OneLogin, PingFederate, Rippling and JumpCloud. Please contact Eppo for onboarding guides on these platforms.
+We recommend naming the groups after the role, e.g. `Eppo Admin`, `Eppo Data Owner`, `Eppo Experiment Editor`, and `Eppo Viewer`. Once your groups are pushed to WorkOS, you can map them to the Eppo role (see screenshot above).