docs/content/stable/yugabyte-platform/security/authentication/oidc-authentication-jumpcloud.md
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
To enable OIDC authentication with JumpCloud, you need to do the following:
yb_hba.conf and yb_ident.conf files.To use JumpCloud for your IdP, do the following:
Sign in to JumpCloud using an administrator account.
Create an application.
Configure your application.
Under SSO > Endpoint Configuration, configure the following:
https://<your-YugabyteDB-Anywhere-IP-address>/api/v1/callback?client_name=OidcClient.https://<your-YugabyteDB-Anywhere-IP-address>/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.
Configure Attributes and Identity Management as required.
Integrate the user in JumpCloud.
To configure JumpCloud federated authentication in YugabyteDB Anywhere, you need the following application properties:
For more information, refer to the JumpCloud documentation.
To configure YugabyteDB Anywhere for OIDC, you need to be signed in as a Super Admin. You need your JumpCloud application client ID and client secret.
To allow users to access their JWT from the YugabyteDB sign in page, you must enable the OIDC feature via a configuration flag before you configure OIDC.
To enable some features of the OIDC functionality in Yugabyte Anywhere, you need to set the yb.security.oidc_feature_enhancements configuration flag to true as follows:
Navigate to Admin > Advanced > Global Configuration.
Search on OIDC to display the configuration setting and set it to true.
To configure User authentication in YugabyteDB Anywhere, do the following:
Navigate to Admin > Access Management > User Authentication and select ODIC configuration.
Under OIDC configuration, configure the following:
https://oauth.id.jumpcloud.com/.well-known/openid-configuration.openid email. If you are using the Refresh Token feature to allow the Jumpcloud server to return the refresh token (which can be used by YBA to refresh the login), enter openid offline_access profile email instead.yb.security.oidc_feature_enhancements configuration flag.)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.
To access a universe via OIDC, you need to set the following flags on the universe:
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.
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 (https://oauth.id.jumpcloud.com/)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:
The following shows an example ysql_hba_conf_csv flag configuration for OIDC:
host all all 0.0.0.0/0 jwt_map=map1 jwt_audiences=""<client_id>"" jwt_issuers=""https://oauth.id.jumpcloud.com/"" jwt_matching_claim_key=""preferred_username""
For more information on host authentication in YugabyteDB using ysql_hba_conf_csv, refer to Host-based authentication.
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 in the PostgreSQL documentation.
The following illustration shows an example flag configuration:
The following are examples of possible rules:
Map a single user
map1 [email protected] user
Map multiple users
map2 /^(.*)@devyugabyte\.com$ \1
Map Roles <-> Users
map1 OIDC.Test.Read read_only_user
This flag must be enabled to expose the OIDC functionality in Yugabyte Anywhere. Use the following API to set values for this flag.
curl -k --location --request PUT '<server-address>/api/v1/customers/<customerUUID>/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: <api-token>' \
--data 'true'
{{< readfile "/stable/yugabyte-platform/security/authentication/oidc-manage-users-include.md" >}}