yujunjun/datahub
2
0
Fork 0
mirror of https://github.com/datahub-project/datahub.git synced 2025-10-29 01:42:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs) better oidc setup docs (#11793)

Browse Source 
Co-authored-by: Maggie Hays <maggiem.hays@gmail.com>
This commit is contained in:
Jay 2024-11-12 12:38:08 -05:00 committed by GitHub
parent a908573265
commit c1fb876f67
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 298 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs-website/sidebars.js
View File

@ -250,9 +250,18 @@ module.exports = {
items: [
"docs/managed-datahub/welcome-acryl",
{
type: "doc",
id: "docs/managed-datahub/approval-workflows",
className: "saasOnly",
"Configure Single Sign-On": [
{
type: "doc",
id: "docs/authentication/guides/sso/initialize-oidc",
className: "saasOnly",
},
{
type: "doc",
id: "docs/managed-datahub/integrations/oidc-sso-integration",
className: "saasOnly",
},
],
},
{
"DataHub API": [
@ -268,20 +277,6 @@ module.exports = {
},
],
},
{
Integrations: [
{
type: "doc",
id: "docs/managed-datahub/integrations/aws-privatelink",
className: "saasOnly",
},
{
type: "doc",
id: "docs/managed-datahub/integrations/oidc-sso-integration",
className: "saasOnly",
},
],
},
{
Slack: [
{
@ -302,7 +297,7 @@ module.exports = {
],
},
{
"Operator Guide": [
"Operator Guides": [
{
type: "doc",
id: "docs/managed-datahub/operator-guide/setting-up-remote-ingestion-executor",
@ -313,8 +308,18 @@ module.exports = {
id: "docs/managed-datahub/operator-guide/setting-up-events-api-on-aws-eventbridge",
className: "saasOnly",
},
{
type: "doc",
id: "docs/managed-datahub/integrations/aws-privatelink",
className: "saasOnly",
},
],
},
{
type: "doc",
id: "docs/managed-datahub/approval-workflows",
className: "saasOnly",
},
{
type: "doc",
id: "docs/managed-datahub/chrome-extension",
@ -550,6 +555,7 @@ module.exports = {
{
"Frontend Authentication": [
"docs/authentication/guides/jaas",
"docs/authentication/guides/sso/initialize-oidc",
"docs/authentication/guides/sso/configure-oidc-react",
"docs/authentication/guides/sso/configure-oidc-behind-proxy",
],

199
docs/authentication/guides/sso/configure-oidc-react.md
View File

@ -1,202 +1,21 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# OIDC Authentication
# Configuring 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.
## 1. Register an app with your Identity Provider
## 1. Get your credentials
<Tabs>
<TabItem value="google" label="Google Identity">
Before you do anything, you'll want to set up DataHub with your SSO provider, and get prerequisite credentials:
1. _Client ID_ - A unique identifier for your application with the identity provider
2. _Client Secret_ - A shared secret to use for exchange between you and your identity provider.
3. _Discovery URL_ - A URL where the OIDC API of your identity provider can be discovered.
#### Create a project in the Google API Console
[👉 See the steps here](./initialize-oidc.md)
Using an account linked to your organization, navigate to the [Google API Console](https://console.developers.google.com/) and select **New project**.
Within this project, we will configure the OAuth2.0 screen and credentials.
#### Create OAuth2.0 consent screen
Navigate to **OAuth consent screen**. This is where you'll configure the screen your users see when attempting to
log in to DataHub. Select **Internal** (if you only want your company users to have access) and then click **Create**.
Note that in order to complete this step you should be logged into a Google account associated with your organization.
Fill out the details in the App Information & Domain sections. Make sure the 'Application Home Page' provided matches where DataHub is deployed
at your organization. Once you've completed this, **Save & Continue**.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google-setup-1.png"/>
</p>
#### Configure the scopes
Next, click **Add or Remove Scopes**. Select the following scope and click **Save & Continue**.
- .../auth/userinfo.email
- .../auth/userinfo.profile
- openid
</TabItem>
<TabItem value="okta" label="Okta">
#### Create an application in Okta Developer Console
Log in to your Okta admin account & navigate to the developer console. Select **Applications**, then **Add Application**, the **Create New App** to create a new app.
Select `Web` as the **Platform**, and `OpenID Connect` as the **Sign on method**.
Click **Create** and name your application under **General Settings** and save.
- **Login Redirect URI** : `https://your-datahub-domain.com/callback/oidc`.
- **Logout Redirect URI**. `https://your-datahub-domain.com/login`
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/okta-setup-2.png"/>
</p>
:::note Optional
If you're enabling DataHub login as an Okta tile, you'll need to provide the **Initiate Login URI**. You
can set if to `https://your-datahub-domain.com/authenticate`. If you're just testing locally, this can be `http://localhost:9002`.
:::
</TabItem>
<TabItem value="azure" label="Azure">
#### Create an application registration in Microsoft Azure portal
Using an account linked to your organization, navigate to the [Microsoft Azure Portal](https://portal.azure.com). Select **App registrations**, then **New registration** to register a new app.
Name your app registration and choose who can access your application.
- **Redirect URI** : Select **Web** as type and enter `https://your-datahub-domain.com/callback/oidc`
Azure supports more than one redirect URI, so both can be configured at the same time from the **Authentication** tab once the registration is complete.
At this point, your app registration should look like the following. Finally, click **Register**.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-app-registration.png"/>
</p>
:::note Optional
Once registration is done, you will land on the app registration **Overview** tab.
On the left-side navigation bar, click on **Authentication** under **Manage** and add extra redirect URIs if need be (if you want to support both local testing and Azure deployments).
For logout URI:
- **Front-channel logout URL**. `https://your-datahub-domain.com/login`
Finally, click **Save**.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-authentication.png"/>
</p>
:::
#### Configure Certificates & secrets
On the left-side navigation bar, click on **Certificates & secrets** under **Manage**.
Select **Client secrets**, then **New client secret**. Type in a meaningful description for your secret and select an expiry. Click the **Add** button when you are done.
Copy the value of your newly create secret since Azure will never display its value afterwards.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-certificates-secrets.png"/>
</p>
#### Configure API permissions
On the left-side navigation bar, click on **API permissions** under **Manage**. DataHub requires the following four Microsoft Graph APIs:
- User.Read _(should be already configured)_
- profile
- email
- openid
Click on **Add a permission**, then from the **Microsoft APIs** tab select **Microsoft Graph**, then **Delegated permissions**. From the **OpenId permissions** category, select `email`, `openid`, `profile` and click **Add permissions**.
At this point, you should be looking at a screen like the following:
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-api-permissions.png"/>
</p>
</TabItem>
</Tabs>
## 2. Obtain Client Credentials & Discovery URL
The goal of this step should be to obtain the following values, which will need to be configured before deploying DataHub:
- **Client ID** - A unique identifier for your application with the identity provider
- **Client Secret** - A shared secret to use for exchange between you and your identity provider
- **Discovery URL** - A URL where the OIDC API of your identity provider can be discovered. This should suffixed by
`.well-known/openid-configuration`. Sometimes, identity providers will not explicitly include this URL in their setup guides, though
this endpoint _will_ exist as per the OIDC specification. For more info see http://openid.net/specs/openid-connect-discovery-1_0.html.
<Tabs>
<TabItem value="google" label="Google Identity">
**Obtain Client Credentials**
Navigate to the **Credentials** tab. Click **Create Credentials** & select **OAuth client ID** as the credential type.
On the following screen, select **Web application** as your Application Type.
Add the domain where DataHub is hosted to your 'Authorized Javascript Origins'.
```
https://your-datahub-domain.com
```
Add the domain where DataHub is hosted with the path `/callback/oidc` appended to 'Authorized Redirect URLs'. Finally, click **Create**
```
https://your-datahub-domain.com/callback/oidc
```
You will now receive a pair of values, a client id and a client secret. Bookmark these for the next step.
</TabItem>
<TabItem value="okta" label="Okta">
**Obtain Client Credentials**
After registering the app, you should see the client credentials. Bookmark the `Client id` and `Client secret` for the next step.
**Obtain Discovery URI**
On the same page, you should see an `Okta Domain`. Your OIDC discovery URI will be formatted as follows:
```
https://your-okta-domain.com/.well-known/openid-configuration
```
For example, `https://dev-33231928.okta.com/.well-known/openid-configuration`.
At this point, you should be looking at a screen like the following:
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/okta-setup-1.png"/>
</p>
</TabItem>
<TabItem value="azure" label="Azure">
**Obtain Application (Client) ID**
On the left-side navigation bar, go back to the **Overview** tab. You should see the `Application (client) ID`. Save its value for the next step.
**Obtain Discovery URI**
On the same page, you should see a `Directory (tenant) ID`. Your OIDC discovery URI will be formatted as follows:
```
https://login.microsoftonline.com/{tenant ID}/v2.0/.well-known/openid-configuration
```
</TabItem>
</Tabs>
## 3. Configure DataHub Frontend Server
## 2. Configure DataHub Frontend Server
### Docker
@ -314,7 +133,7 @@ AUTH_OIDC_GROUPS_CLAIM=<your-groups-claim-name>
| AUTH_OIDC_EXTRACT_GROUPS_ENABLED | Only applies if `AUTH_OIDC_JIT_PROVISIONING_ENABLED` is set to true. This determines whether we should attempt to extract a list of group names from a particular claim in the OIDC attributes. Note that if this is enabled, each login will re-sync group membership with the groups in your Identity Provider, clearing the group membership that has been assigned through the DataHub UI. Enable with care! | false |
| AUTH_OIDC_GROUPS_CLAIM | Only applies if `AUTH_OIDC_EXTRACT_GROUPS_ENABLED` is set to true. This determines which OIDC claims will contain a list of string group names. Accepts multiple claim names with comma-separated values. I.e: `groups, teams, departments`. | groups |
## 4. Restart datahub-frontend-react
## 3. Restart datahub-frontend-react
Once configured, restarting the `datahub-frontend-react` container will enable an indirect authentication flow in which DataHub delegates authentication to the specified identity provider.

238
docs/authentication/guides/sso/initialize-oidc.md Normal file
View File

@ -0,0 +1,238 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Prerequisites for OIDC Authentication
This guide will walk you through the following steps with your identity provider:
1. Create and register an application with your identity provider.
2. Obtain client credentials and discovery URI to be used in DataHub.
Choose your identity provider to get started:
<Tabs>
<TabItem value="google" label="Google Identity">
### Step 1. Create and Register your App
#### 1. Create a project in the Google API Console
Using an account linked to your organization, navigate to the [Google API Console](https://console.developers.google.com/) and select **New project**.
Within this project, we will configure the OAuth2.0 screen and credentials.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-1-create-project.png"/>
</p>
#### 2. Create OAuth2.0 consent screen
Navigate to **OAuth consent screen**. This is where you'll configure the screen your users see when attempting to log in to DataHub. Select **Internal** (if you only want your company users to have access) and then click **Create**.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-3-oauth-consent-step1.png"/>
</p>
_Note that in order to complete this step you should be logged into a Google account associated with your organization._
Fill out the details in the App Information & Domain sections. Make sure the 'Application Home Page' provided matches where DataHub is deployed at your organization.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-3-oauth-consent-step2.png"/>
</p>
Once you've completed this, **Save & Continue**.
#### 3. Configure the appropriate scopes
Next, click **Add or Remove Scopes**. Select the following scopes and click **Save & Continue**.
- `.../auth/userinfo.email`
- `.../auth/userinfo.profile`
- `openid`
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-3-oauth-consent-step3.png"/>
</p>
### Step 2. Create Client Credentials
The following steps will walk you through generating a Client ID and Client Secret.
1. Navigate to the **Credentials** tab and click **Create Credentials**.
2. Select **OAuth client ID** as the credential type.
3. On the next screen, select **Web application** as your Application Type.
4. In **Authorized JavaScript Origins**, add the domain where you are hosting DataHub, i.e. `https://your-datahub-domain.com`.
5. In **Authorized Redirect URLs**, add the domain where you are hosting DataHub with the path `/callback/oidc` appended, i.e. `https://your-datahub-domain.com/callback/oidc`.
6. Click **Create**.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-4-oauth-client-id-2.png"/>
</p>
This will generate a **Client ID** and **Client Secret**:
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/google/google-setup-4-oauth-client-id-3.png"/>
</p>
You will need these values in the next step, in addition to the following **Discovery URI**:
```
https://accounts.google.com/.well-known/openid-configuration`
```
</TabItem>
<TabItem value="okta" label="Okta Identity">
### Step 1. Create and Register your App
#### 1. Create an application in Okta Developer Console
Log in to your Okta admin account and navigate to the developer console. From there:
1. Select **Applications**
2. Click **Add Application**
3. Click **Create New App**
4. Select **OpenID Connect** as the Sign On method
5. Choose **Web** as the Platform
6. Click **Create**
#### 2. Configure application settings
Under **General Settings**, provide a name for your application and configure the following URIs:
- Login Redirect URI: `https://your-datahub-domain.com/callback/oidc`
- Logout Redirect URI: `https://your-datahub-domain.com/login`
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/okta-setup-2.png"/>
</p>
#### 3. Configure Okta Tile (Optional)
If you plan to enable DataHub login as an Okta tile, configure the Initiate Login URI:
- For production: `https://your-datahub-domain.com/authenticate`
- For local testing: `http://localhost:9002`
### Step 2. Locate Client Credentials and Discovery URI
After registering your app, navigate to the **General** tab to find the following Client Credential values:
* **Client ID**: Public identifier for the client that is required for all OAuth flows.
* **Client Secret**: Secret used by the client to exchange an authorization code for a token.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/okta-setup-1.png"/>
</p>
You will need these values in the next step, in addition to the following **Discovery URI**:
```
https://your-okta-domain.com/.well-known/openid-configuration
```
</TabItem>
<TabItem value="azure" label="Azure AD">
### Step 1. Create and Register your App
#### 1. Create an application in Microsoft Azure portal
Using an account linked to your organization, navigate to the [Microsoft Azure Portal](https://portal.azure.com). From there:
1. Select **App Registrations**.
2. Click **New Registration** to register a new app.
3. Provide a Name for the application and choose the supported account types.
4. Under **Redirect URI**, choose **Web** and enter `https://your-datahub-domain.com/callback/oidc`. NOTE: You can add more later.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-app-registration.png"/>
</p>
5. Click **Register**.
#### 2. Configure Logout URL
Once registration is complete, you will need to configure the Logout URL, which is required for SSO to work correctly.
1. Navigate to **Authentication** from the left-side navigation menu.
2. Set **Front-channel logout URL** to `https://your-datahub-domain.com/login`.
3. Optionally add additional Redirect URIs, such as `http://localhost:9002/callback/oidc` for local testing.
4. Click **Save**.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-authentication.png"/>
</p>
### Step 2. Client Credentials and Discovery URI
#### 1. Generate a Client Secret
You are now ready to create and configure client credentials:
1. Click **Certificates & secrets** from the left-side navigation menu.
2. Select **Client secrets**, then **New client secret**.
3. Provide a Name for the secret and set an expiry.
4. Click **Add**.
5. Copy the secret **`Value`** to be used as the **Client Secret** in DataHub SSO configuration; **Azure will not display this again**.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-certificates-secrets.png"/>
</p>
#### 2. Configure API Permissions
Next, you will configure the appropriate API permissions to enable SSO with DataHub.
1. Click **API permissions** from the left-side navigation menu.
2. Click **Add a permission**.
3. Under the **Microsoft APIs** tab, select **Microsoft Graph**, then **Delegated permissions**.
4. Under the **OpenId permissions** category, select the following:
- `User.Read`
- `profile`
- `email`
- `openid`
5. Click **Add permissions**.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/sso/azure-setup-api-permissions.png"/>
</p>
#### 3. Locate Client Credentials and Discovery URI
Now that you have registered your app, generated a client secret, and configured the appropriate permissions, you are now ready to enable Azure AD SSO with DataHub.
You will need the following values in the next step:
- **Application (client) ID**: Find this on the **Overview** tab. This will map to **Client ID** in DataHub.
- **Client Secret**: Stored as `Value` in the Client secret you created, above. This will map to **Client Secret** in DataHub.
- **Directory (tenant) ID**: Located on the **Overview** tab. This will map to **Discovery URI** in DataHub. It will be formatted as `https://login.microsoftonline.com/{tenant ID}/v2.0/.well-known/openid-configuration`.
<p align="center">
<img width="80%" src="https://learn.microsoft.com/en-us/azure/active-directory-b2c/media/client-credentials-grant-flow/get-application-id.png"/>
</p>
</TabItem>
</Tabs>
### Next Steps
Once you have your **Client ID**, **Client Secret**, and **Discovery URI**, you may proceed with next steps.
### DataHub Cloud
If you're deployed with DataHub Cloud, you can enable OIDC SSO with a few clicks. [👉 See the guide here](../../../managed-datahub/integrations/oidc-sso-integration.md).
### Open Source
If you're self-deployed with DataHub Core, you'll need to configure your frontend server within your deployment environment. [👉 See the guide here](./configure-oidc-react.md).

56
docs/managed-datahub/integrations/oidc-sso-integration.md
View File

@ -6,44 +6,42 @@ description: >-
import FeatureAvailability from '@site/src/components/FeatureAvailability';
# OIDC SSO Integration
# Enable OIDC SSO
<FeatureAvailability saasOnly />
This guide will walk you through configuring OIDC Single Sign-On in DataHub Cloud.
_Note that we do not yet support LDAP or SAML authentication. Please let us know if either of these integrations would be useful for your organization._
### Step 1. Complete OIDC Prerequisites
If you'd like to do a deeper dive into OIDC configuration outside of the UI, please see our docs [here](/docs/authentication/guides/sso/configure-oidc-react.md)
You will need the following in order to enable OIDC SSO in DataHub Cloud:
### Getting Details From Your Identity Provider
- Gather the **Client ID**, **Client Secret**, and **Discovery URI** for your OIDC provider, as detailed in [this guide](../../authentication/guides/sso/initialize-oidc.md).
- Confirm you have the `Manage Platform Settings` privilege in DataHub.
To set up the OIDC integration, you will need the following pieces of information.
1. _Client ID_ - A unique identifier for your application with the identity provider
2. _Client Secret_ - A shared secret to use for exchange between you and your identity provider.
3. _Discovery URL_ - A URL where the OIDC API of your identity provider can be discovered. This should suffixed by `.well-known/openid-configuration`. Sometimes, identity providers will not explicitly include this URL in their setup guides, though this endpoint will exist as per the OIDC specification. For more info see [here](http://openid.net/specs/openid-connect-discovery-1_0.html).
The callback URL to register in your Identity Provider will be
```
https://<your-acryl-domain>.acryl.io/callback/oidc
```
### Configuring OIDC SSO
> In order to set up the OIDC SSO integration, the user must have the `Manage Platform Settings` privilege.
#### Enabling the OIDC Integration
To enable the OIDC integration, start by navigating to **Settings > Platform > SSO.**
1. Click **OIDC**
2. Enable the Integration
3. Enter the **Client ID, Client Secret, and Discovery URI** obtained in the previous steps
4. If there are any advanced settings you would like to configure, click on the **Advanced** button. These come with defaults, so only input settings here if there is something you need changed from the default configuration.
5. Click **Update** to save your settings.
### Step 2. Enable OIDC SSO
1. In DataHub Cloud, navigate to **Settings > Platform > SSO** and choose **OIDC**.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/saas/image-(10).png"/>
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/refs/heads/main/imgs/saas/configure-oidc.png"/>
</p>
2. Enter the **Client ID**, **Client Secret**, and **Discovery URI** from Step 1.
3. Confirm your preferred **User Provisioning Strategy**:
* **Just-in-Time (JIT) Provisioning** is enabled by default, automatically creating a DataHub User on login if one does not exist.
* **Pre-Provisioning DataHub Users** will only allow login for pre-provisioned DataHub Users. _Requires configuring SSO Ingestion._
4. Optionally enable **Extract Groups** to extract group memberships in the OIDC profile by default. _Requires JIT Provisioning._
5. Click **Connect**.
6. Log out and log back in through SSO to confirm connection succeeded.
<p align="center">
<img width="80%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/saas/image-(10).png"/>
</p>
:::note
We do not yet support LDAP or SAML authentication. Please let us know if either of these integrations would be useful for your organization.
:::