Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(scim): document okta integration with datahub for scim provisioning #11120

Merged
merged 8 commits into from
Aug 20, 2024
Merged

docs(scim): document okta integration with datahub for scim provisioning #11120

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2c16df0
docs(scim): document okta integration with datahub for scim provisioning
ksrinath Aug 8, 2024
41fb786
misc. fix
ksrinath Aug 8, 2024
5e5a193
doc edits
ksrinath Aug 8, 2024
7d2f8e9
doc edits
ksrinath Aug 8, 2024
1d39a8b
doc edits
ksrinath Aug 8, 2024
da3a730
doc edits
ksrinath Aug 8, 2024
e6a3b0a
doc edits
ksrinath Aug 8, 2024
608b707
doc edits
ksrinath Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs-website/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
117 changes: 117 additions & 0 deletions docs/managed-datahub/configuring-identity-provisioning-with-okta.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
title: "SCIM Integration: Okta and DataHub"
hide_title: true
---
import FeatureAvailability from '@site/src/components/FeatureAvailability';

## SCIM Integration: Okta and DataHub
<FeatureAvailability saasOnly />

## 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.

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`
- And it has two members `john` and `sid`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove repeated word.

The word "And" is repeated unnecessarily.

- - And it has two members `john` and `sid`
+ - It has two members `john` and `sid`
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- And it has two members `john` and `sid`
- It has two members `john` and `sid`
Tools
LanguageTool

[duplication] ~23-~23: Possible typo: you repeated a word
Context: ...e-team- And it has two membersjohnandsid- And the group has roleReader` Through SC...

(ENGLISH_WORD_REPEAT_RULE)

- 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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a missing comma.

Consider adding a comma for clarity in the sentence structure.

- called say, `DataHub-SCIM-SWA`.
+ called, say, `DataHub-SCIM-SWA`.
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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`.
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`.
Tools
LanguageTool

[uncategorized] ~40-~40: Possible missing comma found.
Context: ...s/apps_app_integration_wizard_swa.htm), called say, DataHub-SCIM-SWA. Note: this ap...

(AI_HYDRA_LEO_MISSING_COMMA)


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

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/appSettingsEnableScim.png"/>
</p>

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove unnecessary comma.

The conjunction “so that” does not require a comma.

- as shown in the above image, so that this application isn't visible to your users.
+ as shown in the above image so that this application isn't visible to your users.
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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.
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.
Tools
LanguageTool

[typographical] ~50-~50: The conjunction “so that” does not require a comma.
Context: ...r selections as shown in the above image, so that this application isn't visible to your ...

(SO_THAT_UNNECESSARY_COMMA)


### 2. Configure SCIM

a). In the `Provisioning` tab, configure the DataHub-SCIM endpoint as shown below:

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/scimConfig1.png"/>
</p>

**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:

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/scimConfig2.png"/>
</p>

**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.

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/profileEditor.png"/>
</p>

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

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/defineRoleAttribute.png"/>
</p>

* 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`.)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a comma before "i.e."

Consider putting a comma before the abbreviation “i.e.” for improved readability.

- for groups i.e. repeat step (b) above,
+ for groups, i.e., repeat step (b) above,
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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`.)
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`.)
Tools
LanguageTool

[typographical] ~91-~91: Consider putting a comma before the abbreviation “i.e.”.
Context: ...sonal c). Add a similar attribute for groups i.e. repeat step (b) above, but selectAttr...

(IE_COMMA)


### 4. Assign users & groups to the app
Assign users and groups to the app from the `Assignments` tab:

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/assignUsersGroups.png"/>
</p>

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:

<p>
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/scim/okta/pushGroups.png"/>
</p>

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.
Loading