From bcabff85d56996f595b45ab3d9da27a4004fc977 Mon Sep 17 00:00:00 2001 From: John Joyce Date: Fri, 25 Feb 2022 16:49:57 -0800 Subject: [PATCH] docs(ui): Adding guide for adding users to DataHub. (#4262) --- docs-website/sidebars.js | 1 + docs/how/auth/add-users.md | 130 ++++++++++++++++++++++ docs/how/auth/sso/configure-oidc-react.md | 2 +- 3 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 docs/how/auth/add-users.md diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index 0ba39b4b29..b7ea742fc3 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -200,6 +200,7 @@ module.exports = { "docs/domains", "docs/ui-ingestion", "docs/how/search", + "docs/how/auth/add-users", ], "Developer Guides": [ // TODO: the titles of these should not be in question form in the sidebar diff --git a/docs/how/auth/add-users.md b/docs/how/auth/add-users.md new file mode 100644 index 0000000000..51d2fbf702 --- /dev/null +++ b/docs/how/auth/add-users.md @@ -0,0 +1,130 @@ +# Adding Users to DataHub + +Users can log into DataHub in 2 ways: + +1. Static credentials +2. Single Sign-On via [OpenID Connect](https://www.google.com/search?q=openid+connect&oq=openid+connect&aqs=chrome.0.0i131i433i512j0i512l4j69i60l2j69i61.1468j0j7&sourceid=chrome&ie=UTF-8) + +Option 1 is useful for running proof-of-concept exercises, while Option 2 is highly recommended for deploying DataHub in production. + + +# Configuring static credentials + +## Step 1: Define a user.props file + +To define a set of username / password combinations that should be allowed to log in to DataHub, create a new file called `user.props`. This file should contain username:password combinations, with 1 user per line. For example, to create a `user.props` file with 2 users, the root +"datahub" user and a custom user "johndoe", we would define the following file: + +``` +# user.props +datahub:rootpassword +johndoe:johnspassword +``` + +We strongly recommend keeping a root user named `datahub` in your user.props. Otherwise, the root user will not be able to log in! + +## Step 2: Mount user.props file to Docker container + +Once you've defined a `user.props` file, you'll need to mount the file into the `datahub-frontend` Docker container at the following path: + +``` +/datahub-frontend/conf/user.props +``` + +### Docker Compose + +You'll need to modify the `docker-compose.yml` file to mount a container volume mapping your local user.props to the standard location inside the container. + +For example, to mount a user.props file that is stored on my local filesystem at `/tmp/datahub/user.props`, we'd modify the YAML for the +`datahub-web-react` config to look like the following: + +```aidl + datahub-frontend-react: + build: + context: ../ + dockerfile: docker/datahub-frontend/Dockerfile + image: linkedin/datahub-frontend-react:${DATAHUB_VERSION:-head} + ..... + # The new stuff + volumes: + - :/datahub-frontend/conf/user.props +``` + +Once you've made this change, restarting DataHub enable authentication for the configured users. + +### Helm + +You'll need to create a Kubernetes secret, then mount the file as a volume to the `datahub-frontend` pod. + +First, create a secret from your local `user.props` file + +```aidl +kubectl create secret generic datahub-users-secret --from-file=user.props=./ +``` + +Then, configure your `values.yaml` to add the volume to the `datahub-frontend` container. + +```YAML +datahub-frontend: + ... + extraVolumes: + - name: datahub-users + secret: + defaultMode: 0444 + secretName: datahub-users-secret + extraVolumeMounts: + - name: datahub-users + mountPath: /datahub-frontend/conf/user.props + subPath: user.props +``` + +## URNs + +URNs are identifiers that uniquely identify an Entity on DataHub. The usernames defined in the `user.props` file will be used to generate the DataHub user "urn", which uniquely identifies +the user on DataHub. The urn is computed as: + +``` +urn:li:corpuser: +``` + +## Caveats + +If you add a new username / password to the `user.props` file, no other information about the user will exist +about the user in DataHub (full name, email, bio, etc). This means that you will not be able to search to find the user. + +In order to add information about the user in DataHub, you can use our Python Emitter SDK to produce aspects for the CorpUser, +where the URN will be computed as `urn:li:corpuser:`, where is the identifier defined in the user.props file. + +For a more comprehensive overview of how users & groups are managed within DataHub, check out [this video](https://www.youtube.com/watch?v=8Osw6p9vDYY). + + +# Configuring SSO via OpenID Connect + +Setting up SSO via OpenID Connect means that users will be able to login to DataHub via a central Identity Provider such as + +- Azure AD +- Okta +- Keycloak +- Ping! +- Google Identity + +and more. + +This option is recommended for production deployments of DataHub. For detailed information about configuring DataHub to use OIDC to +perform authentication, check out [OIDC Authentication](./sso/configure-oidc-react.md). + +## URNs + +URNs are identifiers that uniquely identify an Entity on DataHub. The username received from an Identity Provider +when a user logs into DataHub via OIDC is used to construct a unique identifier for the user on DataHub. The urn is computed as: + +``` +urn:li:corpuser: +``` + +For information about configuring which OIDC claim should be used as the username for Datahub, check out the [OIDC Authentication](./sso/configure-oidc-react.md) doc. + + +## Feedback / Questions / Concerns + +We want to hear from you! For any inquiries, including Feedback, Questions, or Concerns, reach out on Slack! \ No newline at end of file diff --git a/docs/how/auth/sso/configure-oidc-react.md b/docs/how/auth/sso/configure-oidc-react.md index 2c9023224f..8de70fb8c5 100644 --- a/docs/how/auth/sso/configure-oidc-react.md +++ b/docs/how/auth/sso/configure-oidc-react.md @@ -1,4 +1,4 @@ -# OIDC Authentication in React +# OIDC Authentication The DataHub React application supports OIDC authentication built on top of the [Pac4j Play](https://github.com/pac4j/play-pac4j) library. This enables operators of DataHub to integrate with 3rd party identity providers like Okta, Google, Keycloak, & more to authenticate their users.