OIDC authentication with JumpCloud

• Azure AD
• JumpCloud

This section describes how to configure a YugabyteDB Anywhere (YBA) universe to use OIDC-based authentication for YugabyteDB YSQL and YCQL database access using JumpCloud as the example Identity Provider (IdP), the integration works with any OIDC-compliant provider.

In normal operation, after OIDC is configured in YBA, database users authenticate with JumpCloud, which issues a JSON Web Token (JWT). The JWT is a short-lived, signed token that proves the user's identity. Database users must then obtain the JWT (in one of two ways) and use it to log in to the database. One way is to obtain the JWT directly from YBA; this requires JumpCloud to be configured to send the JWT to YBA, and YBA to be configured to display it to users on their login screen. Alternatively, users can use a custom tool to obtain the JWT directly from JumpCloud. In either case, database users then supply this JWT as their database password when connecting directly to YugabyteDB.

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.

To set up OIDC authentication, complete the following steps:

1. Configure your JumpCloud Identity provider: register YugabyteDB Anywhere as a client application in JumpCloud and configure the token claims.
2. Configure OIDC in YugabyteDB Anywhere (Optional): if you want YBA to surface the JWT on the sign-in page, enable OIDC in YBA. Otherwise, you can fetch the JWT directly from JumpCloud using a tool of your choice.
3. Configure a universe to use OIDC: set the authentication flags on your YugabyteDB universe for YSQL or YCQL access.
4. Manage users and roles: create database roles that map to the claims in the JWT.

Configure your JumpCloud Identity provider

The JumpCloud IdP configuration includes application configuration (registering YugabyteDB Anywhere in the JumpCloud tenant) and configuring JumpCloud to send (redirect) tokens with the required claims to YugabyteDB Anywhere.

Before configuring, note the YugabyteDB Anywhere callback URI; you'll need to provide it as the redirect URI when registering your application in JumpCloud.

Configure an application in JumpCloud

To use JumpCloud for your IdP, do the following:

1. Sign in to JumpCloud using an administrator account.

2. 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.
   • Click Configure Application.

3. Configure your application.

   Under SSO > Endpoint Configuration, configure the following:

   • Redirect URIs. Enter the OIDC callback URI. This is where the IdP redirects after authentication.
   • Client Authentication Type. Select Client Secret Post.
   • Login URL. Enter 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.

4. Configure Attributes and Identity Management as required.

5. Integrate the user in JumpCloud.

   • Navigate to User Groups, select the user groups you want to access YugabyteDB Anywhere, and click Save when you are done.

To configure JumpCloud federated authentication in YugabyteDB Anywhere, 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 documentation.

Configure OIDC in YugabyteDB Anywhere (Optional)

You have two options to obtain your JWT from the IdP to connect to the database:

• Via a tool of your choice: You can fetch the JWT directly from JumpCloud using any OAuth2-capable tool such as the JumpCloud CLI, curl, or Postman, and supply it as the password when connecting to the database. No additional YBA configuration is required for this path.

• Via YugabyteDB Anywhere: YBA can display your JWT on the sign-in page after you authenticate with JumpCloud. To enable OIDC authentication in YugabyteDB Anywhere, do the following. You need to be signed in as a Super Admin and have your JumpCloud application client ID and client secret available.

Enable OIDC enhancements

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:

1. Navigate to Admin > Advanced > Global Configuration.

2. Search on OIDC to display the configuration setting and set it to true.

   

Enable OIDC authentication

To configure User authentication in YugabyteDB Anywhere, do the following:

1. Navigate to Admin > Access Management > User Authentication and select ODIC configuration.

2. 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. 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.
   • Email attribute - enter your registered email.
   • Refresh Token URL - if you have configured OIDC to use refresh tokens, in the Refresh Token URL field, enter the URL of the refresh token endpoint.
   • Display JWT token on login - select this option to allow users to access their JWT from the YugabyteDB Anywhere sign in page. This allows a user to view and copy their JWT without signing in to YBA. (This option is only available if you enabled the yb.security.oidc_feature_enhancements configuration flag.)

3. 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 use OIDC

You enable OIDC for universes by setting authentication flags for YSQL or YCQL database access. For YSQL, the database uses PostgreSQL yb_hba.conf and yb_ident.conf files to translate authentication rules into database roles. For YCQL, you set YB-TServer flags such as ycql_jwt_conf and optional ycql_ident_conf_csv identity mapping rules.

To access a universe via OIDC, set the flags described in the following tabs for YSQL or YCQL.

For information on configuring flags in YugabyteDB Anywhere, refer to Edit configuration flags.

• YSQL
• YCQL

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""

use_cassandra_authentication=true
ycql_use_jwt_auth=true
ycql_jwt_conf={jwt_jwks_url=https://oauth.id.jumpcloud.com/jwks jwt_audiences=<client_id> jwt_issuers=https://oauth.id.jumpcloud.com/ jwt_matching_claim_key=preferred_username}
ycql_jwt_users_to_skip_csv=cassandra

use_cassandra_authentication=true
ycql_use_jwt_auth=true
ycql_jwt_conf={jwt_jwks_url=https://oauth.id.jumpcloud.com/jwks jwt_audiences=<client_id> jwt_issuers=https://oauth.id.jumpcloud.com/ jwt_matching_claim_key=roles}
ycql_jwt_users_to_skip_csv=cassandra
ycql_ident_conf_csv={/^(.*)@devyugabyte\.com$ \1}

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.

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'

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.

• 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 Manage YugabyteDB Anywhere users.

Using your JWT

If the administrator has enabled the Display JWT token on login setting, you can obtain your token from the YugabyteDB Anywhere landing page. Click Fetch JSON Web Token; you are redirected to the IdP to enter your credentials as required. You are then redirected back to YugabyteDB Anywhere, where your token is displayed, along with the expiration time of the token.

Use the token as your password to access the database. Your username will match the database username/role that was assigned to you by your administrator.

Learn more

• Enable YugabyteDB Anywhere authentication via OIDC
• YFTT: OIDC Authentication in YSQL