Project: YugabyteDB (App Definition and Development / Database)
File: oidc-authentication-aad.md

title: OIDC authentication using Azure AD in YugabyteDB Anywhere headerTitle: OIDC authentication with Azure AD linkTitle: OIDC with Azure AD description: Configuring YugabyteDB Anywhere universe to use OIDC with Microsoft Entra. headcontent: Use Azure AD to authenticate accounts for database access earlyAccess: /preview/releases/versioning/#feature-availability menu: stable_yugabyte-platform: identifier: oidc-authentication-platform parent: authentication weight: 20 type: docs This section describes how to configure a YugabyteDB Anywhere universe to use OIDC-based authentication for YugabyteDB YSQL database access using Azure AD (also known as ) 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 By default, the Subject claim is used as the value to determine the role to assign to users for database access. In addition to the standard claims for token expiration, subject, and issuer, you have the option to use a non-standard claim (other than Subject) to determine role assignment. That is, the values of this claim will map the user to the database roles. This claim is denoted as `jwtmatchingclaim_key`. YugabyteDB expects the token created by the IdP to contain the following standard claims as well as the optional `jwtmatchingclaim_key` to identify the end user and grant them the right access inside databases: Issuer Subject `jwtmatchingclaim_key`, claim key, and values - these could be groups, roles, email, and so forth. Optionally, the subject claim can be used as the claim key. The claims included in the token and chosen for user authorization will vary depending on your requirements. For example, to use group memberships as the determining factor for access and role assignment, you would include the groups claim in the initial token sent to the database. Note that the Subject claim can also be used to map the user to the PostgreSQL role. These token claims are configured in the Azure AD application registration. The following illustration shows an example of Azure token configuration to ensure the right groups or roles claims are included in the token. Note that these options are available in higher Azure AD tiers. The following is an example of a decoded JWT with groups claims (the Group GUID is used in Azure AD OIDC tokens): ```json.output "awd": "e12c03b1-7463-8e23-94d2-8d71f17ab99b", "iss": "https://login.microsoftonline.com/733dee2h-cb2e-41ab-91f2-29e2af034ffe/v2.0", "iat": 1669657223, "nbf": 1669657223, "exp": 1669651124, "groups": [ "a12d04b1-7463-8e23-94d2-8d71f17ab99b", "c22b03b1-2746-8d34-54b1-6d32f17ba36b", ], "oid": "b12a45b2-7463-5e76-32d3-9d31f15ab77b", "sub": "C12a45bGc463_ADLN632d39d31f15ab77b", "tid": "a42a45c3-4728-4f98-25d3-6d63f15ab36c", "ver": "2.0", "wids" [ "b12d04b1-7463-8e23-94d2-8d71f17ab99b", "f22a03c1-2746-8d34-54b1-6d32f17ba36b", ] ``` Note that GUIDs are not supported for YSQL usernames. Use regex rules in user name maps in the `yb_ident.conf` file to convert group GUIDs to roles. See . The following illustration shows an example of Azure app roles configuration. The following shows an example of a decoded JWT with app roles claims: ```json.output "awd": "e12c03b1-7463-8e23-94d2-8d71f17ab99b", "iss": "https://login.microsoftonline.com/733dee2h-cb2e-41ab-91f2-29e2af034ffe/v2.0", "iat": 1669657223, "nbf": 1669657223, "exp": 1669651124, "name": "Fred Summers", "preferred_username": "fsummers@example.com", "oid": "b12a45b2-7463-5e76-32d3-9d31f15ab77b", "roles": [ "a12d04b1-7463-8e23-94d2-8d71f17ab99b", "c22b03b1-2746-8d34-54b1-6d32f17ba36b", ], "sub": "C12a45bGc463_ADLN632d39d31f15ab77b", "tid": "a42a45c3-4728-4f98-25d3-6d63f15ab36c", "ver": "2.0", "wids" [ "b12d04b1-7463-8e23-94d2-8d71f17ab99b", "f22a03c1-2746-8d34-54b1-6d32f17ba36b", ] ``` For more information on configuring group claims and app roles, refer to in the Azure

To enable OIDC authentication with Azure AD, you need to do the following: Create an app registration in Azure AD - The Azure AD IdP configuration includes application registration (registering YugabyteDB Anywhere in the Azure AD tenant) and configuring Azure AD to send (redirect) tokens with the required claims to YugabyteDB Anywhere. Configure OIDC in YugabyteDB Anywhere - The OIDC configuration uses the application you registered. You can also configure YBA to display the user's JSON Web Token (JWT) on the sign in screen. Configure the universe to use OIDC - You enable OIDC for universes by setting authentication rules for database access using flags. The database is implicitly configured and picks up the authentication rules you set. The database uses well-known PostgreSQL constructs to translate these authentication rules into database roles for access. Mapping Azure AD attributes, such as group memberships, roles, and email addresses to database roles, is accomplished using the PostgreSQL `ybhba.conf` and `ybident.conf` files. You register your YugabyteDB Anywhere instance as an application in Azure. You will use the application's tenant ID, client ID, and client secret to configure OIDC in YugabyteDB Anywhere. To register an application, do the following: In the Azure console, navigate to App registrations and click New registration. Enter a name for the application. Select the tenant for the application. Set the redirect URI. This is where the IdP redirects after authentication. Click Register. After the application is registered, you can obtain the tenant ID and client ID. Click Add a certificate or secret. Select Client secrets and click New client secret. Enter a description and set the expiry for the secret, and then click Add. Copy the secret value and keep it in a secure location. For more information, refer to in the Azure documentation. 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.oidcfeatureenhancements` 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 YugabyteDB Anywhere for OIDC, you need to be signed in as a Super Admin. You need your Azure application client ID, client secret, and tenant ID. To enable OIDC authentication in YugabyteDB Anywhere, do the following: Navigate to Admin > Access Management > User Authentication > OIDC Configuration. Enter the client ID and client secret for the application you registered. Enter the discovery URL. This is in the following form: ```sh login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration ``` Set the scope to `openid email profile`. Set the email attribute to a name for the property to be used in the mapping file, such as `preferred_username`. Select the Display JWT token on login 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.oidcfeatureenhancements` configuration flag.) Click Save. To access a universe via OIDC, you need to set the following flags on the universe: ysqlhbaconf_csv ysqlidentconf_csv When the flags are set, YugabyteDB configures the `ysqlhba.conf` and `ybident.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 . The `ysqlhbaconf_csv` flag must be set to support using JWTs for

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. `jwtissuers` - the first part of the discovery URL (`login.microsoftonline.com/<tenantid>/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. `jwtmatchingclaimkey` - the email attribute you set (for example, `preferredusername`). Optional if you aren't using the default Subject claim values. `jwtjwkspath` - 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 `ysqlhbaconf_csv` flag in YugabyteDB Anywhere: The following shows an example `ysqlhbaconf_csv` flag configuration for OIDC: ```sh host all all 0.0.0.0/0 jwtmap=map1 jwtaudiences=""<clientid>"" jwtissuers=""https://login.microsoftonline.com/<tenantid>/v2.0"" jwtmatchingclaimkey=""preferred_username"" ``` For more information on host authentication in YugabyteDB using `ysqlhbaconf_csv`, refer to . 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 `ybident.conf` file as user-name maps. This file is used identically to `pgident.conf` to map external identities to database users. For more information, refer to in the PostgreSQL documentation. The following illustration shows an example flag configuration: 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 readonlyuser ``` <!-- [Tech Preview] Use the following API to set values for this flag: ```sh curl -k --location --request PUT '<server-address>/api/v1/customers/<customerUUID>/runtimeconfig/00000000-0000-0000-0000-000000000000/key/yb.runtimeconfui.tagfilter' \ --header 'Content-Type: text/plain' \ --header 'Accept: application/json' \ --header 'X-AUTH-YW-API-TOKEN: <api-token>' \ --data '["PUBLIC", "BETA"]' ``` --> 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 . 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 . 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.