From c1fb876f672d4fd83dadd6499c18093bc7dbedd3 Mon Sep 17 00:00:00 2001 From: Jay <159848059+jayacryl@users.noreply.github.com> Date: Tue, 12 Nov 2024 12:38:08 -0500 Subject: [PATCH] feat(docs) better oidc setup docs (#11793) Co-authored-by: Maggie Hays --- docs-website/sidebars.js | 38 +-- .../guides/sso/configure-oidc-react.md | 199 +-------------- .../guides/sso/initialize-oidc.md | 238 ++++++++++++++++++ .../integrations/oidc-sso-integration.md | 48 ++-- 4 files changed, 292 insertions(+), 231 deletions(-) create mode 100644 docs/authentication/guides/sso/initialize-oidc.md diff --git a/docs-website/sidebars.js b/docs-website/sidebars.js index d98473c8ad7a5..e55ce64040160 100644 --- a/docs-website/sidebars.js +++ b/docs-website/sidebars.js @@ -250,35 +250,30 @@ module.exports = { items: [ "docs/managed-datahub/welcome-acryl", { - type: "doc", - id: "docs/managed-datahub/approval-workflows", - className: "saasOnly", - }, - { - "DataHub API": [ + "Configure Single Sign-On": [ { type: "doc", - id: "docs/managed-datahub/datahub-api/entity-events-api", + id: "docs/authentication/guides/sso/initialize-oidc", className: "saasOnly", }, { - "GraphQL API": [ - "docs/managed-datahub/datahub-api/graphql-api/getting-started", - ], + type: "doc", + id: "docs/managed-datahub/integrations/oidc-sso-integration", + className: "saasOnly", }, ], }, { - Integrations: [ + "DataHub API": [ { type: "doc", - id: "docs/managed-datahub/integrations/aws-privatelink", + id: "docs/managed-datahub/datahub-api/entity-events-api", className: "saasOnly", }, { - type: "doc", - id: "docs/managed-datahub/integrations/oidc-sso-integration", - className: "saasOnly", + "GraphQL API": [ + "docs/managed-datahub/datahub-api/graphql-api/getting-started", + ], }, ], }, @@ -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", ], diff --git a/docs/authentication/guides/sso/configure-oidc-react.md b/docs/authentication/guides/sso/configure-oidc-react.md index 4dd882cb9a864..0f2c2f5d013bf 100644 --- a/docs/authentication/guides/sso/configure-oidc-react.md +++ b/docs/authentication/guides/sso/configure-oidc-react.md @@ -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 - - +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**. - -

- -

- -#### Configure the scopes - -Next, click **Add or Remove Scopes**. Select the following scope and click **Save & Continue**. - -- .../auth/userinfo.email -- .../auth/userinfo.profile -- openid - - - - -#### 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` - -

- -

- -:::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`. -::: - - - - -#### 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**. - -

- -

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

- -

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

- -

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

- -

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

- -

- - - - -**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 -``` - - - - -## 3. Configure DataHub Frontend Server +## 2. Configure DataHub Frontend Server ### Docker @@ -314,7 +133,7 @@ AUTH_OIDC_GROUPS_CLAIM= | 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. diff --git a/docs/authentication/guides/sso/initialize-oidc.md b/docs/authentication/guides/sso/initialize-oidc.md new file mode 100644 index 0000000000000..1c385c096d841 --- /dev/null +++ b/docs/authentication/guides/sso/initialize-oidc.md @@ -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: + + + + + +### 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. + +

+ +

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

+ +

+ +_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**. + +#### 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` + +

+ +

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

+ +

+ +This will generate a **Client ID** and **Client Secret**: + +

+ +

+ +You will need these values in the next step, in addition to the following **Discovery URI**: + +``` +https://accounts.google.com/.well-known/openid-configuration` +``` + + + + + + +### 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` + +

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+ + + + +### 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). + diff --git a/docs/managed-datahub/integrations/oidc-sso-integration.md b/docs/managed-datahub/integrations/oidc-sso-integration.md index ec4ca311a0de5..834eb55f6daf5 100644 --- a/docs/managed-datahub/integrations/oidc-sso-integration.md +++ b/docs/managed-datahub/integrations/oidc-sso-integration.md @@ -6,44 +6,42 @@ description: >- import FeatureAvailability from '@site/src/components/FeatureAvailability'; -# OIDC SSO Integration +# Enable OIDC SSO +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). +### Step 2. Enable OIDC SSO -The callback URL to register in your Identity Provider will be +1. In DataHub Cloud, navigate to **Settings > Platform > SSO** and choose **OIDC**. -``` -https://.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.** +2. Enter the **Client ID**, **Client Secret**, and **Discovery URI** from Step 1. +3. Confirm your preferred **User Provisioning Strategy**: -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. + * **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.

- +

+ +:::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. +::: \ No newline at end of file