From a53189ef97cae79bfae5ce999280db99f2d3e031 Mon Sep 17 00:00:00 2001 From: aishwarya24 Date: Mon, 15 Jul 2024 16:11:57 -0400 Subject: [PATCH 01/10] Jumpcloud YBA --- .../oidc-authentication.md | 3 + .../authentication/oidc-authentication-aad.md | 17 +++- .../oidc-authentication-jumpcloud.md | 99 +++++++++++++++++++ 3 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md diff --git a/docs/content/preview/yugabyte-platform/administer-yugabyte-platform/oidc-authentication.md b/docs/content/preview/yugabyte-platform/administer-yugabyte-platform/oidc-authentication.md index f30d09ba4f3f..d0ec7a564600 100644 --- a/docs/content/preview/yugabyte-platform/administer-yugabyte-platform/oidc-authentication.md +++ b/docs/content/preview/yugabyte-platform/administer-yugabyte-platform/oidc-authentication.md @@ -41,6 +41,9 @@ To configure YugabyteDB Anywhere for OIDC, you need to be signed in as a Super A **Learn more** - For information on configuring a YugabyteDB Anywhere universe to use OIDC-based authentication using Azure AD as the IdP, refer to [OIDC authentication with Azure AD](../../security/authentication/oidc-authentication-aad/). + +- For information on configuring a YugabyteDB Anywhere universe to use OIDC-based authentication using JumpCloud as the IdP, refer to [OIDC authentication with JumpCloud](../../security/authentication/oidc-authentication-jumpcloud/). + - For information on how to add users, see [Create, modify, and delete users](../anywhere-rbac/#create-modify-and-delete-users). The email ID that you enter in the **Add User** dialog must be registered with the identity provider, and the role must reflect the user's role on YugabyteDB Anywhere. ## Use OIDC groups with YugabyteDB Anywhere roles diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md index 01ff490591f6..2c8428034b25 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md @@ -1,7 +1,7 @@ --- title: OIDC authentication using Azure AD in YugabyteDB Anywhere headerTitle: OIDC authentication with Azure AD -linkTitle: OIDC with Azure AD +linkTitle: OIDC authentication description: Configuring YugabyteDB Anywhere universe to use OIDC with Microsoft Entra. headcontent: Use Azure AD to authenticate accounts for database access badges: ea @@ -13,6 +13,21 @@ menu: type: docs --- + + This section describes how to configure a YugabyteDB Anywhere (YBA) universe to use OIDC-based authentication for YugabyteDB YSQL database access using Azure AD (also known as [Microsoft Entra ID](https://www.microsoft.com/en-ca/security/business/identity-access/microsoft-entra-id)) as the Identity Provider (IdP). After OIDC is set up, users can sign in to the YugabyteDB universe database using their JSON Web Token (JWT) as their password. diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md new file mode 100644 index 000000000000..516f6bac8c72 --- /dev/null +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md @@ -0,0 +1,99 @@ +--- +title: OIDC authentication using JumpCloud in YugabyteDB Anywhere +headerTitle: OIDC authentication with JumpCloud +linkTitle: OIDC authentication +description: Configuring YugabyteDB Anywhere universe to use OIDC with JumpCloud. +headcontent: Use JumpCloud to authenticate accounts for database access +badges: ea +menu: + preview_yugabyte-platform: + identifier: oidc-authentication-jumpcloud + parent: authentication + weight: 20 +type: docs +--- + + + +This section describes how to configure a YugabyteDB Anywhere (YBA) universe to use OIDC-based authentication for YugabyteDB YSQL database access using JumpCloud as the Identity Provider (IdP). + +After OIDC is set up, users can sign in to the YugabyteDB universe database using their JSON Web Token (JWT) as their password. + +Note that the yugabyte privileged user will continue to exist as a local database user even after OIDC-based authentication is enabled for a universe. + +**Learn more** + +- [Enable YugabyteDB Anywhere authentication via OIDC](../../../administer-yugabyte-platform/oidc-authentication/) +- [YFTT: OIDC Authentication in YSQL](https://www.youtube.com/watch?v=KJ0XV6OnAnU&list=PL8Z3vt4qJTkLTIqB9eTLuqOdpzghX8H40&index=1) + +## Create an application in JumpCloud + +To use JumpCloud for your IdP, do the following: + +1. Sign in to JumpCloud using an administrator account. + +1. Create an application. + + - Under **SSO Applications**, click **Add New Application**. + - Select **Custom Application**, and make sure the integration supports "SSO with OIDC" on the next page. + - Under **Manage Single Sign-On (SSO)**, select **Configure SSO with OIDC**, and click **Next**. + - Under **Enter General Info**, add the application name (for **Display Label**), **Description**, and logo (for **User Portal Image**), and select **Show this application in User Portal**. + + This information is displayed as a tile when users sign in to YugabyteDB Aeon. + + - Click **Configure Application**. + +1. Configure your application. + + Under **SSO > Endpoint Configuration**, configure the following: + + - **Redirect URIs** - enter `https:///api/v1/callback?client_name=OidcClient`. + - **Client Authentication Type** - select **Client Secret Post**. + - **Login URL** - enter `https:///login`. + + Under **Attribute Mapping**, for **Standard Scopes**, select **Email** and **Profile**. + + Click **Activate** when you are done. + + You will be prompted in a pop up to save the **Client ID** and **Client Secret**. Save these in a secure location, you will need to provide these credentials in YugabyteDB Anywhere. + +1. Configure Attributes and Identity Management as required. + +1. Integrate the user in JumpCloud. + + - Navigate to **User Groups**, select the user groups you want to access YugabyteDB Aeon, and click **Save** when you are done. + +To configure JumpCloud federated authentication in YugabyteDB Aeon, you need the following application properties: + +- **Client ID** and **Client Secret** of the application you created. These are the credentials you saved when you activated your application. The **Client ID** is also displayed on the **SSO** tab. + +For more information, refer to the [JumpCloud](https://jumpcloud.com/support/sso-with-oidc) documentation. + +## Configure authentication + +To configure User authentication in YugabyteDB Anywhere, do the following: + +1. Navigate to **Admin > User Management > User Authentication** and select **ODIC configuration**. +1. Under **OIDC configuration**, configure the following: + + - **Client ID** and **Client Secret** - enter the client ID and secret of the JumpCloud application you created. + - **Discovery URL** - enter `https://oauth.id.jumpcloud.com/.well-known/openid-configuration`. + - **Scope** - enter `openid email`. + - **Email attribute** - enter your registered email. + +1. Click **Save**. + +You are redirected to sign in to your IdP to test the connection. After the test connection is successful, federated authentication is enabled. From db67098faed60a1c0aaab57942b5a78dcf3a538d Mon Sep 17 00:00:00 2001 From: aishwarya24 Date: Wed, 24 Jul 2024 11:57:17 -0400 Subject: [PATCH 02/10] updated steps --- .../authentication/oidc-authentication-aad.md | 2 +- .../oidc-authentication-jumpcloud.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md index 2c8428034b25..3a8e4d3e8558 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md @@ -22,7 +22,7 @@ type: docs
  • - + JumpCloud
  • diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md index 516f6bac8c72..4321950afabe 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md @@ -9,7 +9,7 @@ menu: preview_yugabyte-platform: identifier: oidc-authentication-jumpcloud parent: authentication - weight: 20 + weight: 30 type: docs --- @@ -22,7 +22,7 @@ type: docs
  • - + JumpCloud
  • @@ -60,9 +60,9 @@ To use JumpCloud for your IdP, do the following: Under **SSO > Endpoint Configuration**, configure the following: - - **Redirect URIs** - enter `https:///api/v1/callback?client_name=OidcClient`. + - **Redirect URIs** - enter `https:///api/v1/callback?client_name=OidcClient`. - **Client Authentication Type** - select **Client Secret Post**. - - **Login URL** - enter `https:///login`. + - **Login URL** - enter `https:///login`. Under **Attribute Mapping**, for **Standard Scopes**, select **Email** and **Profile**. @@ -82,11 +82,11 @@ To configure JumpCloud federated authentication in YugabyteDB Aeon, you need the For more information, refer to the [JumpCloud](https://jumpcloud.com/support/sso-with-oidc) documentation. -## Configure authentication +## Configure OIDC authentication To configure User authentication in YugabyteDB Anywhere, do the following: -1. Navigate to **Admin > User Management > User Authentication** and select **ODIC configuration**. +1. Navigate to **Admin > Access Management > User Authentication** and select **ODIC configuration**. 1. Under **OIDC configuration**, configure the following: - **Client ID** and **Client Secret** - enter the client ID and secret of the JumpCloud application you created. @@ -96,4 +96,4 @@ To configure User authentication in YugabyteDB Anywhere, do the following: 1. Click **Save**. -You are redirected to sign in to your IdP to test the connection. After the test connection is successful, federated authentication is enabled. +You are redirected to sign in to your IdP to test the connection. After the test connection is successful, OIDC authentication is enabled. From e1e058637063ffa790ae5d5f2f82e2a481306668 Mon Sep 17 00:00:00 2001 From: aishwarya24 Date: Fri, 26 Jul 2024 15:25:01 -0400 Subject: [PATCH 03/10] added configure a universe --- .../oidc-authentication-jumpcloud.md | 97 ++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md index 4321950afabe..5f97199998f4 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md @@ -82,7 +82,9 @@ To configure JumpCloud federated authentication in YugabyteDB Aeon, you need the For more information, refer to the [JumpCloud](https://jumpcloud.com/support/sso-with-oidc) documentation. -## Configure OIDC authentication +### Configure YugabyteDB Anywhere + +#### Enable OIDC authentication To configure User authentication in YugabyteDB Anywhere, do the following: @@ -97,3 +99,96 @@ To configure User authentication in YugabyteDB Anywhere, do the following: 1. Click **Save**. You are redirected to sign in to your IdP to test the connection. After the test connection is successful, OIDC authentication is enabled. + +### Configure a universe + +To access a universe via OIDC, you need to set the following flags on the universe: + +- ysql_hba_conf_csv +- ysql_ident_conf_csv + +When the flags are set, YugabyteDB configures the `ysql_hba.conf` and `yb_ident.conf` files on the database nodes and creates the files that hold the JWKS keys for token validation. + +For information on configuring flags in YugabyteDB Anywhere, refer to [Edit configuration flags](../../../manage-deployments/edit-config-flags/). + +#### ysql_hba_conf_csv + +The `ysql_hba_conf_csv` flag must be set to support using JWTs for authentication. The parameters to include in the configuration file record are as follows: + +- `jwt_map` - the user-name map used to translate claim values to database roles. Optional if you aren't using the default Subject claim values. +- `jwt_issuers` - the first part of the discovery URL (`login.microsoftonline.com//v2.0`) +- `jwt_audiences` - the audience or target app for the token, which in this case is the client ID of the application you registered. +- `jwt_matching_claim_key` - the email attribute you set (for example, `preferred_username`). Optional if you aren't using the default Subject claim values. +- `jwt_jwks_path` - The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JWT. These can be uploaded as entries in a single file. When configuring the flag in YugabyteDB Anywhere, click **Add JSON web key set (JWKS)** to upload the JWKS. + +The following illustration shows an example of setting the `ysql_hba_conf_csv` flag in YugabyteDB Anywhere: + +![Configuring ysql_hba_conf_csv flag for OIDC](/images/yp/security/oidc-azure-hbaconf.png) + +The following shows an example `ysql_hba_conf_csv` flag configuration for OIDC: + +```sh +host all all 0.0.0.0/0 jwt_map=map1 jwt_audiences="""" jwt_issuers=""https://login.microsoftonline.com//v2.0"" jwt_matching_claim_key=""preferred_username"" +``` + +For more information on host authentication in YugabyteDB using `ysql_hba_conf_csv`, refer to [Host-based authentication](../../../../secure/authentication/host-based-authentication/). + +#### ysql_ident_conf_csv + +This flag is used to add translation regex rules that map token claim values to PostgreSQL roles. The flag settings are used as records in the `yb_ident.conf` file as user-name maps. This file is used identically to `pg_ident.conf` to map external identities to database users. For more information, refer to [User name maps](https://www.postgresql.org/docs/11/auth-username-maps.html) in the PostgreSQL documentation. + +The following illustration shows an example flag configuration: + +![Configuring ysql_ident_conf_csv flag for OIDC](/images/yp/security/oidc-azure-identconf.png) + +The following are examples of possible rules: + +- Map a single user + + ```sh + map1 user@yugabyte.com user + ``` + +- Map multiple users + + ```sh + map2 /^(.*)@devadmincloudyugabyte\.onmicrosoft\.com$ \1 + ``` + +- Map Roles <-> Users + + ```sh + map1 OIDC.Test.Read read_only_user + ``` + +#### yb.security.oidc_feature_enhancements + +This flag must be enabled to expose the OIDC functionality in Yugabyte Anywhere. Use the following API to set values for this flag. + +```sh +curl -k --location --request PUT '/api/v1/customers//runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.oidc_feature_enhancements' \ +--header 'Content-Type: text/plain' \ +--header 'Accept: application/json' \ +--header 'X-AUTH-YW-API-TOKEN: ' \ +--data 'true' +``` + +## Manage users and roles + +After OIDC-based authentication is configured, an administrator can manage users as follows: + +- In the universe, add database users or roles. + + You need to add the users and roles that will be used to authenticate to the database. The role must be assigned the appropriate permissions in advance. Users will use their database user/role as their username credential along with their JWT as the password when connecting to the universe. + + For information on managing users and roles in YugabyteDB, see [Manage users and roles](../../../../secure/authorization/create-roles/). + +- In YugabyteDB Anywhere, create YBA users. + + Create a user in YugabyteDB Anywhere for each user who wishes to sign in to YBA to obtain their JWT. + + To view their JWT, YBA users can sign in to YugabyteDB Anywhere, click the **User** icon at the top right, select **User Profile**, and click **Fetch OIDC Token**. + + This is not required if you enabled the **Display JWT token on login** option in the YBA OIDC configuration, as any database user can copy the JWT from the YBA landing page without signing in to YBA. + + For information on how to add YBA users, see [Create, modify, and delete users](../../../administer-yugabyte-platform/anywhere-rbac/#create-modify-and-delete-users). From d7a12447f99fccd44600f93291025c596e3192a9 Mon Sep 17 00:00:00 2001 From: aishwarya24 Date: Tue, 30 Jul 2024 13:58:43 -0400 Subject: [PATCH 04/10] replaced URL --- .../security/authentication/oidc-authentication-jumpcloud.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md index 5f97199998f4..6356575a1b71 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md @@ -116,7 +116,7 @@ For information on configuring flags in YugabyteDB Anywhere, refer to [Edit conf The `ysql_hba_conf_csv` flag must be set to support using JWTs for authentication. The parameters to include in the configuration file record are as follows: - `jwt_map` - the user-name map used to translate claim values to database roles. Optional if you aren't using the default Subject claim values. -- `jwt_issuers` - the first part of the discovery URL (`login.microsoftonline.com//v2.0`) +- `jwt_issuers` - the first part of the discovery URL (`https://oauth.id.jumpcloud.com/.well-known/openid-configuration`) - `jwt_audiences` - the audience or target app for the token, which in this case is the client ID of the application you registered. - `jwt_matching_claim_key` - the email attribute you set (for example, `preferred_username`). Optional if you aren't using the default Subject claim values. - `jwt_jwks_path` - The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JWT. These can be uploaded as entries in a single file. When configuring the flag in YugabyteDB Anywhere, click **Add JSON web key set (JWKS)** to upload the JWKS. @@ -128,7 +128,7 @@ The following illustration shows an example of setting the `ysql_hba_conf_csv` f The following shows an example `ysql_hba_conf_csv` flag configuration for OIDC: ```sh -host all all 0.0.0.0/0 jwt_map=map1 jwt_audiences="""" jwt_issuers=""https://login.microsoftonline.com//v2.0"" jwt_matching_claim_key=""preferred_username"" +host all all 0.0.0.0/0 jwt_map=map1 jwt_audiences="""" jwt_issuers=""https://oauth.id.jumpcloud.com/.well-known/openid-configuration"" jwt_matching_claim_key=""preferred_username"" ``` For more information on host authentication in YugabyteDB using `ysql_hba_conf_csv`, refer to [Host-based authentication](../../../../secure/authentication/host-based-authentication/). From c2403892dc024634117bbdaafe4a07e6eb0619b5 Mon Sep 17 00:00:00 2001 From: aishwarya24 Date: Tue, 30 Jul 2024 15:20:50 -0400 Subject: [PATCH 05/10] added screenshots --- .../security/authentication/_index.md | 4 ++-- .../authentication/oidc-authentication-aad.md | 4 +--- .../oidc-authentication-jumpcloud.md | 10 ++++------ .../yp/security/oidc-jumpcloud-hbaconf.png | Bin 0 -> 168254 bytes .../yp/security/oidc-jumpcloud-identconf.png | Bin 0 -> 144301 bytes 5 files changed, 7 insertions(+), 11 deletions(-) create mode 100644 docs/static/images/yp/security/oidc-jumpcloud-hbaconf.png create mode 100644 docs/static/images/yp/security/oidc-jumpcloud-identconf.png diff --git a/docs/content/preview/yugabyte-platform/security/authentication/_index.md b/docs/content/preview/yugabyte-platform/security/authentication/_index.md index fef566f21bed..5cf9bc534c2d 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/_index.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/_index.md @@ -31,8 +31,8 @@ YugabyteDB supports LDAP and OIDC for database authentication. icon="/images/section_icons/secure/authentication.png">}} {{}} diff --git a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md index 830fdc4bb866..ddf6d9586c4e 100644 --- a/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md +++ b/docs/content/preview/yugabyte-platform/security/authentication/oidc-authentication-aad.md @@ -16,13 +16,11 @@ type: docs