From 2c16df0f93e273af03f2fa02ece254933733e851 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 18:30:26 +0530 Subject: [PATCH 1/8] docs(scim): document okta integration with datahub for scim provisioning --- docs-website/sidebars.js | 7 +- ...iguring-identity-provisioning-with-okta.md | 108 ++++++++++++++++++ 2 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 docs/managed-datahub/configuring-identity-provisioning-with-okta.md diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 75fc1f2dcd0c5d..6155bff352509c 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -527,7 +527,12 @@ module.exports = { "Advanced Guides": [ "docs/how/delete-metadata", "docs/how/configuring-authorization-with-apache-ranger", - "docs/managed-datahub/configuring-identity-provisioning-with-ms-entra", + { + "SCIM Provisioning": [ + "docs/managed-datahub/configuring-identity-provisioning-with-ms-entra", + "docs/managed-datahub/configuring-identity-provisioning-with-okta", + ] + } "docs/how/backup-datahub", "docs/how/restore-indices", "docs/advanced/db-retention", diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md new file mode 100644 index 00000000000000..4cfa975133db83 --- /dev/null +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -0,0 +1,108 @@ +--- +title: "SCIM Integration: Okta and DataHub" +hide_title: true +--- +import FeatureAvailability from '@site/src/components/FeatureAvailability'; + +## SCIM Integration: Okta and DataHub + + +## Overview +This document assumes you are using OIDC for SSO with DataHub. +Since Okta doesn't currently support SCIM with OIDC, you would need to create an additional SWA-app-integration to enable SCIM provisioning. +The rest of this document specifies the steps required for such a configuration. + +On completion of this setup Okta will automatically push changes to the assigned groups/users (and their roles) from Okta to DataHub. + +### Why SCIM provisioning? +Let us look at an example of the flows enabled through SCIM provisioning. + +Consider the following configuration in Okta +- A group `governance-team` group +- And it has two members `john` and `sid` +- And the group has role `Reader` + +Through SCIM provisioning, the following are enabled: +* If the `governance-team` group is assigned to the DataHub app in Okta with the role `Reader`, Okta will create the users `john` and `sid` in DataHub with the `Reader` role. +* If you remove `john` from group `governance-team` then `john` would automatically get deactivated in DataHub. +* If you remove `sid` from the DataHub app in Okta, then `sid` would automatically get deactivated in DataHub. + +Generally, any user assignment/unassignment to the app in Okta - directly or through groups - are automatically reflected in the DataHub application. + +This guide also covers other variations such as how to assign a role to a user directly, and how group-information can be pushed to DataHub. + +> Only Admin, Editor and Reader roles are supported in DataHub. These roles are preconfigured/created on DataHub. + +## Configuring SCIM provisioning + +### 1. Create an SWA app integration +a). Create a new [SWA app integration](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_swa.htm), called say, `DataHub-SCIM-SWA`. + +Note: this app-integration will only be used for SCIM provisioning. You would continue to use the existing OIDC-app-integration for SSO. + +b). In the `General` tab of the `DataHub-SCIM-SWA` application, check the `Enable SCIM provisioning` option +

+ +

+ +You may also want to configure the other selections as shown in the above image, so that this application isn't visible to your users. + +### 2. Configure SCIM + +a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown below: +

+ +

+ +* Note: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens). + +b). Configure the `To App` section as shown below: +

+ +

+ +* Note: We are not pushing passwords to DataHub over SCIM, since we are assuming SSO with OIDC as mentioned earlier. + +### 3. Add a custom attribute to represent roles +a). Navigate to `Directory` -> `Profile Editor`, and select the user-profile of this new application. +

+ +

+ +b). Click `Add Attribute` and define a new attribute that will be used to specify the role of a DataHub user. +

+ +

+ +* Set value of `External name` to `roles.^[primary==true].value` +* Set value of `External namespace` to `urn:ietf:params:scim:schemas:core:2.0:User` +* Define an enumerated list of values as shown in the above image +* Mark this attribute as required +* Select `Attribute type` as `Personal` + +c). Add a similar attribute for groups i.e. repeat step (b) above, but select `Attribute Type` as `Group`. (Specify the variable name as, say, `dataHubGroupRoles`.) + +### 4. Assign users & groups to the app +Assign users and groups to the app from the `Assignments` tab: +

+ +

+ +While assigning a user/group, choose an appropriate value for the dataHubRoles/dataHubGroupRoles attribute. +Note that when a role is selected for a group, the corresponding role is pushed for all users of that group in DataHub. + +### The provisioning setup is now complete +Once the above steps are completed, user assignments/unassignments to the DataHub-SCIM-SWA app in Okta will get reflected in DataHub automatically. + +> #### A note on user deletion +>Note that when users are unassigned or deactivated in Okta, the corresponding users in DataHub are also deactivated (marked "suspended"). +But when a user is *deleted* in Okta, the corresponding user in DataHub does *not* get deleted. +Refer the Okta documentation on [Delete (Deprovision)](https://developer.okta.com/docs/concepts/scim/#delete-deprovision) for more details. +### 5. (Optional): Configure push groups +When groups are assigned to the app, Okta pushes the group-members as users to DataHub, but the group itself isn't pushed. +To push group information to DataHub, configure the `Push Groups` tab accordingly as shown below: +

+ +

+ +Refer to the Okta [Group Push](https://help.okta.com/en-us/content/topics/users-groups-profiles/app-assignments-group-push.htm) documentation for more details. \ No newline at end of file From 41fb786e2fd608f014d67f2f169ebe7f4e2a11c9 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 18:32:20 +0530 Subject: [PATCH 2/8] misc. fix --- docs-website/sidebars.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 6155bff352509c..c90807721a5477 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -531,8 +531,8 @@ module.exports = { "SCIM Provisioning": [ "docs/managed-datahub/configuring-identity-provisioning-with-ms-entra", "docs/managed-datahub/configuring-identity-provisioning-with-okta", - ] - } + ], + }, "docs/how/backup-datahub", "docs/how/restore-indices", "docs/advanced/db-retention", From 5e5a193e993d5d659fa634a660a30e77b2df9097 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 19:05:21 +0530 Subject: [PATCH 3/8] doc edits --- .../configuring-identity-provisioning-with-okta.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index 4cfa975133db83..1e6250f4279c69 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -8,17 +8,18 @@ import FeatureAvailability from '@site/src/components/FeatureAvailability'; ## Overview +This document covers the steps required to enable SCIM provisioning from Okta to DataHub. + This document assumes you are using OIDC for SSO with DataHub. Since Okta doesn't currently support SCIM with OIDC, you would need to create an additional SWA-app-integration to enable SCIM provisioning. -The rest of this document specifies the steps required for such a configuration. -On completion of this setup Okta will automatically push changes to the assigned groups/users (and their roles) from Okta to DataHub. +On completing the steps in this guide, Okta will start automatically pushing changes to users/groups of this SWA-app-integration to DataHub, thereby simplifying provisioning of users/groups in DataHub. ### Why SCIM provisioning? Let us look at an example of the flows enabled through SCIM provisioning. Consider the following configuration in Okta -- A group `governance-team` group +- A group `governance-team` - And it has two members `john` and `sid` - And the group has role `Reader` @@ -98,6 +99,7 @@ Once the above steps are completed, user assignments/unassignments to the DataHu >Note that when users are unassigned or deactivated in Okta, the corresponding users in DataHub are also deactivated (marked "suspended"). But when a user is *deleted* in Okta, the corresponding user in DataHub does *not* get deleted. Refer the Okta documentation on [Delete (Deprovision)](https://developer.okta.com/docs/concepts/scim/#delete-deprovision) for more details. + ### 5. (Optional): Configure push groups When groups are assigned to the app, Okta pushes the group-members as users to DataHub, but the group itself isn't pushed. To push group information to DataHub, configure the `Push Groups` tab accordingly as shown below: From 7d2f8e9f78cb63325c6f7e0bbb3830cbc583f43b Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 19:28:35 +0530 Subject: [PATCH 4/8] doc edits --- ...iguring-identity-provisioning-with-okta.md | 49 +++++++++++-------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index 1e6250f4279c69..4155f97d2454b6 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -42,38 +42,43 @@ a). Create a new [SWA app integration](https://help.okta.com/en-us/content/topic Note: this app-integration will only be used for SCIM provisioning. You would continue to use the existing OIDC-app-integration for SSO. b). In the `General` tab of the `DataHub-SCIM-SWA` application, check the `Enable SCIM provisioning` option -

- -

+ +

+ +

You may also want to configure the other selections as shown in the above image, so that this application isn't visible to your users. ### 2. Configure SCIM a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown below: -

- -

+ +

+ +

* Note: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens). b). Configure the `To App` section as shown below: -

- -

+ +

+ +

* Note: We are not pushing passwords to DataHub over SCIM, since we are assuming SSO with OIDC as mentioned earlier. ### 3. Add a custom attribute to represent roles a). Navigate to `Directory` -> `Profile Editor`, and select the user-profile of this new application. -

- -

+ +

+ +

b). Click `Add Attribute` and define a new attribute that will be used to specify the role of a DataHub user. -

- -

+ +

+ +

* Set value of `External name` to `roles.^[primary==true].value` * Set value of `External namespace` to `urn:ietf:params:scim:schemas:core:2.0:User` @@ -85,9 +90,10 @@ c). Add a similar attribute for groups i.e. repeat step (b) above, but select `A ### 4. Assign users & groups to the app Assign users and groups to the app from the `Assignments` tab: -

- -

+ +

+ +

While assigning a user/group, choose an appropriate value for the dataHubRoles/dataHubGroupRoles attribute. Note that when a role is selected for a group, the corresponding role is pushed for all users of that group in DataHub. @@ -103,8 +109,9 @@ Refer the Okta documentation on [Delete (Deprovision)](https://developer.okta.co ### 5. (Optional): Configure push groups When groups are assigned to the app, Okta pushes the group-members as users to DataHub, but the group itself isn't pushed. To push group information to DataHub, configure the `Push Groups` tab accordingly as shown below: -

- -

+ +

+ +

Refer to the Okta [Group Push](https://help.okta.com/en-us/content/topics/users-groups-profiles/app-assignments-group-push.htm) documentation for more details. \ No newline at end of file From 1d39a8b9c2d1c4b5dca54a3aa4c25b9fe9cdbaec Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 20:06:57 +0530 Subject: [PATCH 5/8] doc edits --- .../configuring-identity-provisioning-with-okta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index 4155f97d2454b6..9122af74fbf845 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -57,7 +57,7 @@ a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown belo

-* Note: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens). +Note: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens) b). Configure the `To App` section as shown below: From da3a730c2c0c97a6966dda8122dfa92a01853b29 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 20:08:00 +0530 Subject: [PATCH 6/8] doc edits --- .../configuring-identity-provisioning-with-okta.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index 9122af74fbf845..2a6fff4bff4107 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -57,7 +57,7 @@ a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown belo

-Note: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens) +**Note**: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens) b). Configure the `To App` section as shown below: @@ -65,7 +65,7 @@ b). Configure the `To App` section as shown below:

-* Note: We are not pushing passwords to DataHub over SCIM, since we are assuming SSO with OIDC as mentioned earlier. +**Note**: We are not pushing passwords to DataHub over SCIM, since we are assuming SSO with OIDC as mentioned earlier. ### 3. Add a custom attribute to represent roles a). Navigate to `Directory` -> `Profile Editor`, and select the user-profile of this new application. From e6a3b0a3aa474af6dde47bcc2c4aff58d3186981 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 20:33:26 +0530 Subject: [PATCH 7/8] doc edits --- .../configuring-identity-provisioning-with-okta.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index 2a6fff4bff4107..e39462d1bf5eaf 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -56,7 +56,7 @@ a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown belo

- + **Note**: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens) b). Configure the `To App` section as shown below: From 608b70745d695f8f9556d66eaa792a9b31e12828 Mon Sep 17 00:00:00 2001 From: ksrinath Date: Thu, 8 Aug 2024 20:56:44 +0530 Subject: [PATCH 8/8] doc edits --- .../configuring-identity-provisioning-with-okta.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md index e39462d1bf5eaf..a7939b514166da 100644 --- a/docs/managed-datahub/configuring-identity-provisioning-with-okta.md +++ b/docs/managed-datahub/configuring-identity-provisioning-with-okta.md @@ -51,15 +51,17 @@ You may also want to configure the other selections as shown in the above image, ### 2. Configure SCIM -a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown below: +a). Generate a personal access token from [DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens). + +b). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown in the below image:

-**Note**: the Bearer token would be a [personal access token generated from DataHub](../../docs/authentication/personal-access-tokens.md#creating-personal-access-tokens) +**Note**: Set the value of the `Bearer` field to the personal access token obtained in step (a) above. -b). Configure the `To App` section as shown below: +c). Configure the `To App` section as shown below: