v2.25 Preview Preview release - not for production v2024.2 LTS Stable release with long-term support v2024.1 STS Stable release with standard-term support v2.20 LTS Stable release with long-term support v2.18 STS Stable release with standard-term support v2.14 LTS Stable release with long-term support Unsupported versions

Configure authentication for YugabyteDB Anywhere

Manage YugabyteDB Anywhere users using OIDC

You can configure YugabyteDB Anywhere to use OpenID Connect (OIDC) for single sign-on (SSO) authentication to access to your YugabyteDB Anywhere instance.

OIDC is an authentication protocol that allows client applications to confirm the user's identity via authentication by an authorization server.

When OIDC is enabled, users are presented with the following options when signing in to YugabyteDB Anywhere:

  • Login with SSO redirects the user to the appropriate identity provider's sign in mechanism.
  • Super Admin Login allows the user to sign in to YugabyteDB Anywhere as a local super admin.

To configure YugabyteDB Anywhere for OIDC, you need to be signed in as a Super Admin.

Learn more

  • For information on configuring a YugabyteDB Anywhere universe to use OIDC-based authentication, refer to OIDC authentication.

  • For information on how to add users, see 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

If your OIDC provider is configured with user groups, you can map the groups to YugabyteDB Anywhere roles. Users who are members of these groups can then sign in to YugabyteDB Anywhere without needing to be added to YugabyteDB Anywhere first. Users who are members of multiple groups are assigned the most privileged role.

Note that, if you use group mapping, you must manage users via your OIDC server. You can't add or change user roles in YugabyteDB Anywhere. In addition, group mapping overrides any previously assigned roles.

Prerequisites

To use OIDC groups, ensure the following on your IdP:

  • Create user groups and add users to this group. This is possible on most IdPs.
  • Configure the IdP so that groups are present in the ID token. As groups is not one of the Standard Claims, you will need to add the groups claim in the ID token by configuring your IdP provider settings. Refer to your IdP documentation.
  • For Azure AD/Microsoft Entra ID, Azure doesn't allow obtaining group names in ID tokens. You need to use the Azure API to get a list of the user's group memberships. Note that to fetch the group membership via Azure API, the IdP administrator will need to assign the GroupMember.Read.All API permission to the registered application on Azure.

Enable OIDC for YugabyteDB Anywhere

YugabyteDB Anywhere accepts OIDC configuration either using a discovery URL that points to the OpenID Provider Configuration Document for your provider, or by uploading the document directly. The configuration document contains key-value pairs with details about the OIDC provider's configuration, including uniform resource identifiers of the authorization, token, revocation, user information, and public-keys endpoints. YugabyteDB Anywhere uses the metadata to discover the URLs to use for authentication and the authentication service's public signing keys.

For air-gapped installations, where YugabyteDB Anywhere does not have access to the discovery URL, you need to explicitly provide the configuration document.

EA You can map groups to fine-grained YugabyteDB Anywhere roles. To enable the feature in YugabyteDB Anywhere, set the Enable RBAC for Groups Global Runtime Configuration option (config key yb.security.group_mapping_rbac_support) to true. Refer to Manage runtime configuration settings. Note that only a Super Admin user can modify Global configuration settings.

You configure OIDC as follows:

  1. Navigate to Admin > Access Management > User Authentication > OIDC Configuration.

  2. Select OIDC Enabled to turn on OIDC.

  3. Complete the OIDC Configuration settings.

    OIDC authentication

    • In the Client ID field, enter the unique identifier that you provided when you manually created the client application in the identity provider.

    • In the Client Secret field, enter the password or secret for authenticating your Yugabyte client application with your identity provider.

    • Use the Discovery URL field to provide a URL for the discovery document that contains OIDC configuration for the identity provider. The discovery document is a JSON file stored in a well-known location.

      Google OIDC discovery endpoint is an example of such file. For most identity providers, /.well-known/openid-configuration is appended to the issuer to generate the metadata URL for OIDC specifications.

      If you have an airgapped installation, where YugabyteDB Anywhere cannot access the Discovery URL, provide the OIDC configuration for the identity provider directly.

      To do this, click Add OIDC Provider Configuration and paste the OIDC configuration document from your identity provider (in JSON format) into the field.

    • In the Scope field, enter your identity provider OIDC scope that is allowed to be requested. This field accepts a space-separated list of values. If left blank, all scopes will be considered.

    • In the Email Attribute field, enter the OIDC scope containing the user email identifier. This field accepts a case-sensitive custom configuration. Typically, this field is left blank.

    • If you have configured OIDC to use refresh tokens, in the Refresh Token URL field, enter the URL of the refresh token endpoint.

    • If you have configured OIDC enhancements, you can select the Display JWT token on login option to allow users to access their JWT from the YugabyteDB Anywhere sign in page. See Set up OIDC with Azure AD on YugabyteDB Anywhere.

  4. To map OIDC groups to YugabyteDB Anywhere roles, select the Use OIDC groups for authentication and authorization option.

  5. You can assign the default role for OIDC users to be Read Only or Connect Only.

  6. Optionally, if you are using a groups claim, enter the name of the groups claim; this is the claim that lists the groups that users are a member of in the ID token.

  7. Click Save.

Map groups to roles

To map groups to roles, on the Groups tab, do the following:

  1. Click Add Group and select OIDC.

  2. Enter the Group DN name.

  3. Select the YugabyteDB Anywhere role (built-in or custom) that you want to map the group to.

    • To assign a built-in role, on the Built-in Role tab, select a role. You can't assign the SuperAdmin role to a group.

    • To assign a custom role (only available if you have enabled RBAC for groups), on the Custom Role tab, select a role and scope.

  4. Click Save.