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.
- .png)
+
+
+:::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