datahub/docs/how/configure-oidc-react.md

# OIDC Authentication in React

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.

When configured, OIDC auth will be enabled between clients of the DataHub UI & `datahub-frontend` server. Beyond this point is considered 
to be a secure environment and as such authentication is validated & enforced only at the "front door" inside datahub-frontend.

## Provider-Specific Guides

1. [Configuring OIDC using Google](./sso/configure-oidc-react-google.md)
2. [Configuring OIDC using Okta](./sso/configure-oidc-react-okta.md)

## Configuring OIDC in React 

### 1. Register an app with your Identity Provider

To configure OIDC in React, you will most often need to register yourself as a client with your identity provider (Google, Okta, etc). Each provider may
have their own instructions. Provided below are links to examples for Okta, Google, Azure AD, & Keycloak.

- [Registering an App in Okta](https://developer.okta.com/docs/guides/add-an-external-idp/apple/register-app-in-okta/)
- [OpenID Connect in Google Identity](https://developers.google.com/identity/protocols/oauth2/openid-connect)
- [OpenID Connect authentication with Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oidc)
- [Keycloak - Securing Applications and Services Guide](https://www.keycloak.org/docs/latest/securing_apps/)

During the registration process, you'll need to provide a login redirect URI to the identity provider. This tells the identity provider
where to redirect to once they've authenticated the end user. 

By default, the URL will be constructed as follows: 

> "http://your-datahub-domain.com/callback/oidc"

For example, if you're hosted DataHub at `datahub.myorg.com`, this
value would be `http://datahub.myorg.com/callback/oidc`. For testing purposes you can also specify localhost as the domain name
directly: `http://localhost:9002/callback/oidc`

The goal of this step should be to obtain the following values, which will need to be configured before deploying DataHub:

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 http://openid.net/specs/openid-connect-discovery-1_0.html. 
   

### 2. Configure DataHub Frontend Server

The second step to enabling OIDC involves configuring `datahub-frontend` to enable OIDC authentication with your Identity Provider.

To do so, you must update the `datahub-frontend` [docker.env](../../docker/datahub-frontend/env/docker.env) file with the
values received from your identity provider:

```
# Required Configuration Values:
AUTH_OIDC_ENABLED=true
AUTH_OIDC_CLIENT_ID=your-client-id
AUTH_OIDC_CLIENT_SECRET=your-client-secret
AUTH_OIDC_DISCOVERY_URI=your-provider-discovery-url
AUTH_OIDC_BASE_URL=your-datahub-url
```

- `AUTH_OIDC_ENABLED`: Enable delegating authentication to OIDC identity provider
- `AUTH_OIDC_CLIENT_ID`: Unique client id received from identity provider
- `AUTH_OIDC_CLIENT_SECRET`: Unique client secret received from identity provider
- `AUTH_OIDC_DISCOVERY_URI`: Location of the identity provider OIDC discovery API. Suffixed with `.well-known/openid-configuration`
- `AUTH_OIDC_BASE_URL`: The base URL of your DataHub deployment, e.g. https://yourorgdatahub.com (prod) or http://localhost:9002 (testing)

Providing these configs will cause DataHub to delegate authentication to your identity
provider, requesting the "oidc email profile" scopes and parsing the "preferred_username" claim from 
the authenticated profile as the DataHub CorpUser identity.

> By default, the login callback endpoint exposed by DataHub will be located at `${baseUrl}/callback/oidc`. This must **exactly** match the login redirect URL you've registered with your identity provider in step 1.

#### Advanced

You can optionally customize the flow further using advanced configurations. These allow 
you to specify the OIDC scopes requested & how the DataHub username is parsed from the claims returned by the identity provider. 

```
# Optional Configuration Values:
AUTH_OIDC_USER_NAME_CLAIM=your-custom-claim
AUTH_OIDC_USER_NAME_CLAIM_REGEX=your-custom-regex
AUTH_OIDC_SCOPE=your-custom-scope
```

- `AUTH_OIDC_USER_NAME_CLAIM`: The attribute that will contain the username used on the DataHub platform. By default, this is "preferred_username" provided
as part of the standard `profile` scope.
- `AUTH_OIDC_USER_NAME_CLAIM_REGEX`: A regex string used for extracting the username from the userNameClaim attribute. For example, if 
the userNameClaim field will contain an email address, and we want to omit the domain name suffix of the email, we can specify a custom
regex to do so. (e.g. `([^@]+)`)
- `AUTH_OIDC_SCOPE`: a string representing the scopes to be requested from the identity provider, granted by the end user. For more info,
  see [OpenID Connect Scopes](https://auth0.com/docs/scopes/openid-connect-scopes).
  
Once configuration has been updated, `datahub-frontend` will need to be rebuilt (either by rebuilding the `datahub-frontend-react` container or via `./gradlew :datahub-frontend:build -PenableReact=true` for testing)


>Note that by default, enabling OIDC will *not* disable the dummy JAAS authentication path, which can be reached at the `/login`
route of the React app. To disable this authentication path, additionally specify the following config: 
> `auth.jaas.enabled = false`

### Summary

Once configured, deploying `datahub-frontend` to serve React will enable an indirect authentication flow in which DataHub delegates
authentication to the specified identity provider.

Once a user is authenticated by the identity provider, DataHub will extract a username from the provided claims
and grant DataHub access to the user by setting a pair of session cookies.

A brief summary of the steps that occur when the user navigates to the React app are as follows: 

1. A `GET` to the `/authenticate` endpoint in `datahub-frontend` server is initiated
2. The `/authenticate` attempts to authenticate the request via session cookies
3. If auth fails, the server issues a redirect to the Identity Provider's login experience
4. The user logs in with the Identity Provider
5. The Identity Provider authenticates the user and redirects back to DataHub's registered login redirect URL, providing an authorization code which 
   can be used to retrieve information on behalf of the authenticated user
6. DataHub fetches the authenticated user's profile and extracts a username to identify the user on DataHub (eg. urn:li:corpuser:username)
7. DataHub sets session cookies for the newly authenticated user 
8. DataHub redirects the user to the homepage ("/")