docs: directory sync providers specific issues & limitations (#347)

* okta * onelogin * Google Workspace * Google Workspace sections. * Update FAQ * Microsoft Entra ID SCIM * Update faq
boxyhq · Jan 17, 2024 · 6b09de1 · 6b09de1
1 parent 405eda2
commit 6b09de1
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 0 deletions.
diff --git a/docs/directory-sync/faq.md b/docs/directory-sync/faq.md
@@ -0,0 +1,37 @@
+---
+title: Faq
+sidebar_label: FAQ
+hide_table_of_contents: true
+---
+
+# Frequently asked questions
+
+Frequently asked questions about the common issues and limitations of the directory sync providers.
+
+### Why don't I see any event when a group is removed in OneLogin?
+
+It is a known issue with OneLogin SCIM. OneLogin does not dispatch a specific deprovisioning event for groups that are deleted, so you won't see any event such as `group.deleted` or `group.user_removed` when a group is removed. It is recommended to remove the users from the group before deleting the group itself from the SCIM application.
+
+### Why don't I see a DELETE event for a user that was removed in Okta?
+
+Instead of executing a DELETE operation, Okta sends a request to the SCIM application to set the `active` attribute to `false`. Consequently, you will observe a `user.updated` event with the `active` attribute changed to `false` for users removed from the Okta application. [Read More](https://developer.okta.com/docs/reference/scim/scim-20/#delete-users)
+
+### Why is there no event for a user that was deactivated in Okta?
+
+Okta does not dispatch a specific deprovisioning event for users that are suspended. This omission of a deactivation event is a known issue with Okta.
+
+### Does Google Workspace sync in real time?
+
+No, Google Workspace sync is not real-time. Jackson syncs the Google Workspace directory on a schedule (e.g. every 2 hours). In a self-hosted deployment, you can configure a cron job to sync the directory on a schedule of your choice.
+
+### Can I sync specific groups from Google Workspace?
+
+Not possible at the moment. Jackson syncs all the groups from Google Workspace. You have to filter the groups from your application's side.
+
+### How frequently does Microsoft Entra ID SCIM perform sync by default?
+
+Microsoft Entra ID automatically provisions and updates user accounts in an app based on things like user and group assignment. The sync happens at a regularly scheduled time interval, typically every 20-40 minutes. [Read More](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user#how-long-will-it-take-to-provision-users)
+
+### Why does the PATCH request fail in Microsoft Entra ID SCIM?
+
+This is a known issue with Entra ID SCIM implementation. You have to add the query param `?aadOptscim062020` to the SCIM endpoint URL to make PATCH requests work. This query param update PATCH behavior and ensure SCIM compliance. [Read More](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility#flags-to-alter-the-scim-behavior)
diff --git a/docs/directory-sync/providers/azure.md b/docs/directory-sync/providers/azure.md
@@ -72,3 +72,13 @@ Select **None Selected** under the **Users**.
 From the right side of the screen, select the users you want to assign to the app and click the **Select** button, then click **Assign** to those users to the app.
 
 ![img alt](/img/dsync/providers/azure/12.png)
+
+### FAQ
+
+#### How frequently does Microsoft Entra ID SCIM perform sync by default?
+
+Microsoft Entra ID automatically provisions and updates user accounts in an app based on things like user and group assignment. The sync happens at a regularly scheduled time interval, typically every 20-40 minutes.
+
+#### Why does the PATCH request fail in Microsoft Entra ID SCIM?
+
+This is a known issue with Entra ID SCIM implementation. You have to add the query param `?aadOptscim062020` to the SCIM endpoint URL to make PATCH requests work. This query param update PATCH behavior and ensure SCIM compliance. [Read More](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility#flags-to-alter-the-scim-behavior)
diff --git a/docs/directory-sync/providers/google.md b/docs/directory-sync/providers/google.md
@@ -60,3 +60,13 @@ curl -X POST \
 ```
 
 Learn more about [Google Directory Sync API](/docs/directory-sync/api-reference#4-sync-directory).
+
+### FAQ
+
+#### Does Google Workspace sync in real time?
+
+No, Google Workspace sync is not real-time. Jackson syncs the Google Workspace directory on a schedule (e.g. every 2 hours). In a self-hosted deployment, you can configure a cron job to sync the directory on a schedule of your choice.
+
+#### Can I sync specific groups from Google Workspace?
+
+Not possible at the moment. Jackson syncs all the groups from Google Workspace. You have to filter the groups from your application's side.
diff --git a/docs/directory-sync/providers/okta.md b/docs/directory-sync/providers/okta.md
@@ -79,3 +79,13 @@ Navigate to the tab **Push Groups** and select **Find group by name** from the d
 Find the group you want to assign to the app and click the **Save** button.
 
 ![img alt](/img/dsync/providers/okta/12.png)
+
+### FAQ
+
+#### Why don't I see a DELETE event for a user that was removed in Okta?
+
+Instead of executing a DELETE operation, Okta sends a request to the SCIM application to set the `active` attribute to `false`. Consequently, you will observe a `user.updated` event with the `active` attribute changed to `false` for users removed from the Okta application.
+
+#### Why is there no event for a user that was deactivated in Okta?
+
+Okta does not dispatch a specific deprovisioning event for users that are suspended. This omission of a deactivation event is a known issue with Okta.
diff --git a/docs/directory-sync/providers/onelogin.md b/docs/directory-sync/providers/onelogin.md
@@ -119,3 +119,9 @@ Click the **Users** tab on the left, you may see **Pending** provisions in the t
 Click **Approve** in the next modal to confirm the assignment.
 
 ![img alt](/img/dsync/providers/onelogin/18.png)
+
+### FAQ
+
+#### Why don't I see any event when a group is removed in OneLogin?
+
+It is a known issue with OneLogin SCIM. OneLogin does not dispatch a specific deprovisioning event for groups that are deleted, so you won't see any event such as `group.deleted` or `group.user_removed` when a group is removed. It is recommended to remove the users from the group before deleting the group itself from the SCIM application.
diff --git a/sidebars.js b/sidebars.js
@@ -69,6 +69,7 @@ module.exports = {
         'directory-sync/webhooks',
         'directory-sync/events',
         'directory-sync/observability',
+        'directory-sync/faq',
         {
           type: 'category',
           label: 'Providers',