Skip to content

Commit

Permalink
feat(docs) better oidc setup docs (#11793)
Browse files Browse the repository at this point in the history 
Co-authored-by: Maggie Hays <[email protected]>
  • Loading branch information
@jayacryl @maggiehays
jayacryl and maggiehays authored Nov 12, 2024
1 parent a908573 commit c1fb876
Show file tree
Hide file tree
Showing 4 changed files with 292 additions and 231 deletions.
38 changes: 22 additions & 16 deletions docs-website/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
],
},
],
},
Expand All @@ -302,7 +297,7 @@ module.exports = {
],
},
{
"Operator Guide": [
"Operator Guides": [
{
type: "doc",
id: "docs/managed-datahub/operator-guide/setting-up-remote-ingestion-executor",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
],
Expand Down
199 changes: 9 additions & 190 deletions docs/authentication/guides/sso/configure-oidc-react.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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.

Expand Down
Loading

0 comments on commit c1fb876

Please sign in to comment.