diff --git a/README.md b/README.md index fff713ef..3a0b7c2d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repo hosts documentation for: * [Unstructured Open Source Library](https://github.com/Unstructured-IO/unstructured) * [Unstructured APIs](https://unstructured.io/api-key-hosted) -* [Unstructured Enterprise platform](https://unstructured.io/platform) +* [Unstructured Business platform](https://unstructured.io/platform) 👉 Looking for the live documentation site powered by this repo? Visit [docs.unstructured.io](https://docs.unstructured.io/) diff --git a/business/idp/overview.mdx b/business/idp/overview.mdx new file mode 100644 index 00000000..65b5cbe0 --- /dev/null +++ b/business/idp/overview.mdx @@ -0,0 +1,57 @@ +--- +title: IdP overview +sidebarTitle: Overview +--- + + + The following information applies only to dedicated instance and in-VPC deployments of [Unstructured Enterprise](/business/overview). + + IdP integration is not available for Unstructured **Let's Go**, **Pay-As-You-Go**, or **Business SaaS** accounts. + + +An _identity provider_ (IdP) is a service that manages and verifies the digital identities of users. +It authenticates who a user is and provides that information to other systems (known as _service providers_) to control access. +You can connect your organization's IdP to Unstructured so you can manage who has access across all your connected systems from one place. +Instead of having to manually create and manage user accounts and roles within your Unstructured account, Unstructured can use your organization's IdP to determine +things such as: + +- Who can sign in to your Unstructured account's organizational accounts. +- Which roles and permissions they should have within your organizational accounts. +- Revoking access to your organizational accounts—for example, when someone leaves your organization. + +## Supported IdPs + +Unstructured supports IdPs that use any of the following protocols: + +- Keycloak OpenID Connect +- OpenID Connect v1.0 +- SAML 2.0 + +## IdP groups + +_IdP groups_ are collections of users defined within your IdP—for example, an Engineering group, a Marketing group, or an +Administrators group. Unstructured can use your IdP groups to automatically assign roles and permissions within your Unstructured account +at the account level and for each of your account's workspaces. + +## Roles + +_Roles_ are the sets of permissions that Unstructured can assign to your IdP groups—as well as to individual users separately within your Unstructed account, if needed— through +a common security best-practice technique called _role-based access control_ (RBAC). Unstructured has two kinds of roles: + +- **Account roles**: These roles include **Super Administrator**, **Account Member**, and **Billing Administrator**. They apply at the account level. +- **Workspace roles**: These roles include **Workspace Administrator**, **Developer**, **Operator**, and **Viewer**. They apply to each of your account's workspaces. + +[Learn more about these roles](/ui/account/roles). + +## Getting started + +To have Unstructured connect your organization's IdP to your Unstructured account, contact your assigned +Unstructured Account Executive (AE) or Customer Success Manager (CSM). If you do not know who your assigned AE or CSM is, +email Unstructured Support at [support@unstructured.io](mailto:support@unstructured.io). + +## Next steps + +After Unstructured has connected your organization's IdP to your Unstructured account, you can manage access by your IdP groups and individual users to your +Unstructured account's organizational accounts and their workspaces. To do this, you can use your +Unstructured account's user interface (UI). For details, see +[IdP management with the Unstructured UI](/business/idp/ui). \ No newline at end of file diff --git a/business/idp/ui.mdx b/business/idp/ui.mdx new file mode 100644 index 00000000..db6a48d4 --- /dev/null +++ b/business/idp/ui.mdx @@ -0,0 +1,261 @@ +--- +title: IdP management with the Unstructured UI +sidebarTitle: UI +--- + + + The following information applies only to dedicated instance and in-VPC deployments of [Unstructured Business](/business/overview). + + IdP integration is not available for Unstructured **Let's Go**, **Pay-As-You-Go**, or **Business SaaS** accounts. + + +The following information assumes that Unstructured has already connected your organization's IdP to your Unstructured account. +For more information, see [Getting started](/business/idp/overview#getting-started). + +## Add an IdP group to an organizational account + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that you want to add the IdP group to. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +4. In the top navigation bar, click **IdP Groups**. +5. Click **+ New Group**. +6. On the **Connect Group** page, for **Identity Provider Group**, type the name of the IdP group that you want to add, and then click **Continue**. + + + You must type the name of the IdP group exactly as it appears in your IdP. Otherwise, Unstructured will not be able to + successfully complete the connection to that IdP group through your IdP. + + +7. On the **Assign Account Role** page, for **Account Role**, select the name of the [organizational account role](/ui/account/roles#organizational-account-roles) that you want to assign to the IdP group for this + organizational account, and then click **Continue**. +8. On the **Assign Workspaces** page, for **Workspaces and permissions**, select each workspace—and the + [workspace role](/ui/account/roles#workspace-roles) for that workspace—that you want to assign to the IdP group, and then click **Add**. + + + The **Assign Workspaces** page does not apply if the IdP group is assigned the **Super Administrator** organizational account role. + This is because an IdP group with the **Super Administrator** role automatically has full access to all of the organizational account's workspaces. + + +9. Click **Save Group**. + +The organizational account and workspaces' roles' permissions are enabled for each of the IdP group's existing users the first (or next) time they sign in to your Unstructured account and then choose +this organizational account. + +Whenever you add a user to the IdP group, they get the associated account and workspace roles' permissions the next time they +sign in to your Unstructured account and then choose this organizational account. + +If a user is already signed in to your Unstructured account and has chosen this organizational account, but they are not getting the permissions they expect, the user should try signing out of your Unstructured account and then signing back in and choosing this organizational account again, to get those permissions. + +If you remove a user from the IdP group, the associated account and workspace roles' permissions are revoked for them the next time they sign in to your Unstructured account and then choose this organizational account. An exception to this is if the user was otherwise [added as an individual user to the account](#add-individual-users-to-an-account). + +## Add an IdP group to a workspace + +This procedure assumes you have already added the IdP group to your Unstructured account. [Learn how](#add-an-idp-group-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the workspace you want to add the IdP group to. +3. In the top navigation bar, in the workspace selector, select the name of the workspace you want to add the IdP group to. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of the workspace you want to add the IdP group to. + + +4. On the **Members** tab, click **Add New +**, and then click **+ Add Group**. +5. Select the IdP group to add and its [workspace role](/ui/account/roles#workspace-roles) for this workspace, and then click **Continue**. + +## Change a workspace role for an IdP group + +This procedure assumes you have already added the IdP group to your Unstructured account and the workspace within that account. [Learn how](#add-an-idp-group-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the workspace that refers to the IdP group whose role you want to change. +3. In the top navigation bar, in the workspace selector, select the name of the workspace that refers to the IdP group whose role you want to change. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of the workspace that refers to the IdP group whose role you want to change. + + +4. On the **Members** tab, click the ellipsis (three dots) next to the name of the IdP group whose workspace role you want to change. +5. Click **Edit Permissions**. +6. Select the IdP group's new [workspace role](/ui/account/roles#workspace-roles) for this workspace, and then click **Continue**. + +## Change an account role for an IdP group + +This procedure assumes you have already added the IdP group to your Unstructured account. [Learn how](#add-an-idp-group-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the IdP group whose organizational account role you want to change. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +4. In the top navigation bar, click **IdP Groups**. +5. Click the name of the IdP group whose organizational account role you want to change. +6. Next to **Account Role**, click the edit (pencil) icon. +7. Select the new [organizational account role](/ui/account/roles#organizational-account-roles) for the IdP group whose organizational account role you want to change, and then click the apply (check mark) icon. + +## Add individual users to an account + +Unstructured recommends that you add IdP groups to an organizational account, instead of adding individual users. +Managing IdP groups can be easier, faster, and less error-prone than managing individual users. + +However, if you must add individual users to an organizational account (for example, if you want to give a user +access to an organizational account at a different level than the access that is granted to them through their IdP groups), +you can do so by following these steps. + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +3. On the **Members** tab, click **New Member +**. +4. In the **Add New Member** dialog, for **Email**, type the email address of each individual user to add. +5. For all of the email addresses that you typed, select the [organizational account role](/ui/account/roles#organizational-account-roles) for all of the individual users at once, and then click **Continue**. + + + An organizational account role that is assigned to an individual user always overrides any organizational account role that is assigned to any IdP group to which that user belongs. + This override happens the next time they sign in to your Unstructured account and then choose this organizational account. + + +6. Click **Continue**. + +## Add individual users to a workspace + +Unstructured recommends that you add IdP groups to your workspaces, instead of adding individual users. +Managing IdP groups can be easier, faster, and less error-prone than managing individual users. + +However, if you must add individual users to workspaces (for example, if you want to give a user +access to a workspace at a different level than the access than is granted to them through their IdP groups), +you can do so by following these steps. + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the workspace for the individual users you want to add. +3. In the top navigation bar, in the workspace selector, select the name of the workspace that you to add the individual users to. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of the workspace you want to add the individual users to. + + +4. On the **Members** tab, click **Add New+**, and then click **+ Add Member**. +5. In the **Add New Member** dialog, for **Email**, type the email address of each individual user to add. +6. For all of the email addresses that you typed, select the [workspace role](/ui/account/roles#workspace-roles) for all of the individual users at once, and then click **Continue**. + + + A workspace role that is assigned to an individual user always overrides any workspace role that is assigned to any IdP group to which that user belongs. + This override happens the next time they sign in to your Unstructured account and then choose this organizational account. + + +7. Click **Continue**. + +## Change a workspace role for an individual user + +This procedure assumes you have already added the individual user to your Unstructured account and the workspace within that account. [Learn how](#add-individual-users-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account. +3. In the top navigation bar, in the workspace selector, select the name of the workspace. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of the workspace that contains the user for whom you want to change the workspace role. + + +4. On the **Members** tab, next to the user's email, click the ellipsis (three dots), and then click **Edit Permissions**. +5. Select the new [workspace role](/ui/account/roles#workspace-roles) for the user, and then click **Continue**. + +## Change an account role for an individual user + +This procedure assumes you have already added the individual user to your Unstructured account. [Learn how](#add-individual-users-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the user for whom you want to change their organizational account role. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +4. On the **Members** tab, click the user's email. +5. Next to **Role**, click the edit (pencil) icon. +4. Select the new [organizational account role](/ui/account/roles#organizational-account-roles) for the user, and then click the apply (check mark) icon. + +## Remove an individual user from a workspace + +This procedure assumes you have already added the individual user to your Unstructured account and the workspace within that account. [Learn how](#add-individual-users-to-your-unstructured-account). + + + Removing an individual user from a workspace does not necessarily revoke all access to that workspace! + + After you remove an individual user from a workspace, any workspace role that is assigned to any IdP group to which that user belongs will then be applied. + This happens the next time they sign in to your Unstructured account. + + +This procedure assumes you have already added the user to your Unstructured account and the workspace within that account. [Learn how](#add-individual-users-to-your-unstructured-account). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the workspace. +3. In the top navigation bar, in the workspace selector, select the name of the workspace. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of the workspace that contains the user you want to remove. + + +4. On the **Members** tab, next to the user's email, click the ellipsis (three dots), and then click **Remove Member**. +5. To confirm the removal, click **Continue**. + +## Remove an individual user from an account + +This procedure assumes you have already added the individual user to your Unstructured account. [Learn how](#add-individual-users-to-your-unstructured-account). + + + Removing an individual user from an organizational account does not necessarily revoke all access to that organizational account! + + After you remove an indivdual user from an account, any organizational account role that is assigned to any IdP group to which that user belongs will then be applied. + This happens the next time they sign in to your Unstructured account. + + +This procedure assumes you have already assigned the user to the account. [Learn how](#assign-an-account-role-to-an-individual-user). + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +4. On the **Members** tab, next to the user's email, click the ellipsis (three dots), and then click **Remove Member**. +5. To confirm the removal, click **Continue**. + +## Remove an IdP group from a workspace + +This procedure assumes you have already added the IdP group to your Unstructured account and the workspace within that account. [Learn how](#add-an-idp-group-to-your-unstructured-account). + + + After you remove an IdP group from a workspace, all users in that group will lose access to the workspace, + unless they were otherwise [added as individual users to the account](#add-individual-users-to-a-workspace). + + If they were not otherwise added as individual users to the workspace, they will lose access to that workspace + the next time they sign in to your Unstructured account. + + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account that contains the workspace. +3. In the top navigation bar, in the workspace selector, select the name of the workspace you want to remove the IdP group from. + + + If the workspace selector is not showing next to the organizational account selector then, in the top navigation bar, + click the **Workspaces** tab, and then click the name of workspace that contains the IdP group you want to remove. + + +4. On the **Members** tab, next to the IdP group's name, click the ellipsis (three dots), and then click **Remove Member**. +5. To confirm the removal, click **Continue**. + +## Remove an IdP group from an account + +This procedure assumes you have already added the IdP group to your Unstructured account. [Learn how](#add-an-idp-group-to-your-unstructured-account). + + + After you remove an IdP group from an organizational account, all users in that group will lose access to the organizational account, + unless they were otherwise [added as individual users to the account](#add-individual-users-to-an-account). + + If they were not otherwise added as individual users to the organizational account, they will lose access to that organizational account + the next time they sign in to your Unstructured account. + + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the organizational account selector, select the name of the organizational account. +3. In the sidebar, above your user icon, click the **Settings** (gear) icon, and then click **Manage Account**. +4. In the top navigation bar, click **IdP Groups**. +5. Click the name of the IdP group you want to remove from the organizational account. +6. In the settings pane, click **Delete Group**. +7. To confirm the removal, click **Continue**. diff --git a/docs.json b/docs.json index c9f17849..4545170a 100644 --- a/docs.json +++ b/docs.json @@ -318,6 +318,13 @@ "business/security-compliance/overview" ] }, + { + "group": "IdP integration", + "pages": [ + "business/idp/overview", + "business/idp/ui" + ] + }, { "group": "AWS", "pages": [