Database node authentication

Database node authentication within the YDB cluster ensures that service connections between cluster nodes are assigned the correct security identifiers, or SIDs. The process of database node authentication applies to connections that use the gRPC protocol and provide functions for registering nodes in the cluster, as well as for accessing configuration information. SIDs assigned to connections are considered when checking the authorization rules that apply to the corresponding gRPC service calls.

Node authentication settings are configured within the static configuration of the cluster.

client_certificate_authorization – node authentication settings

This section specifies the authentication settings for database node connections by defining the requirements for the content of the "Subject" and "Subject Alternative Name" fields in node certificates, as well as the list of SID values assigned to the connections.

The "Subject" field of the node certificate may contain multiple components (such as O – organization, OU – organizational unit, C – country, CN – common name), and checks can be configured against one or more of these components.

The "Subject Alternative Name" field of the node certificate is a list of the node's network names or IP addresses. Checks can be configured to match the names specified in the certificate against the expected values.

Syntax

client_certificate_authorization:
  request_client_certificate: Bool
  default_group: <default SID>
  client_certificate_definitions:
    - member_groups: <SID array>
      require_same_issuer: Bool
      subject_dns:
      - suffixes: <array of allowed suffixes>
        values: <array of allowed values>
      subject_terms:
      - short_name: <Subject Name component>
        suffixes: <array of allowed suffixes>
        values: <array of allowed values>
    - member_groups: <SID array>
    ...
Key Description
request_client_certificate Request a valid client certificate for node connections.
Allowed values:
  • false — A certificate is not required (used by default if the parameter is omitted).
  • true — A certificate is required for all node connections.
default_group SID assigned to all connections providing a trusted client certificate when no explicit settings are provided in the client_certificate_definitions section.
client_certificate_definitions Section defining the requirements for database node certificates.
member_groups SIDs assigned to connections that conform to the requirements of the current configuration block.
require_same_issuer Require that the value of the "Issuer" field (typically containing the Certification Authority name) is the same for both client (database node) and server (storage node) certificates.
Allowed values:
  • true — The values must be the same (used by default if the parameter is omitted).
  • false — The values can be different (allowing client and server certificates to be issued by different Certification Authorities).
subject_dns Allowed values for the "Subject Alternative Name" field, specified as either full values (using the values sub-key) or suffixes (using the suffixes sub-key). The check is successful if the actual value matches any full name or any suffix specified.
subject_terms Requirements for the "Subject" field value. Contains the component name (in the short_name sub-key) and a list of full values (using the values sub-key) or suffixes (using the suffixes sub-key). The check is successful if the actual value of each component matches either an allowed full value or an allowed suffix.

Examples

The following configuration fragment enables node authentication and requires the "Subject" field to include the component O=YDB. Upon successful authentication, the connection is assigned the registerNode@cert SID.

client_certificate_authorization:
  request_client_certificate: true
  client_certificate_definitions:
    - member_groups: ["registerNode@cert"]
      subject_terms:
      - short_name: "O"
        values: ["YDB"]

The next configuration fragment enables node authentication, and requires "Subject" field to include both OU=cluster1 and O=YDB components. In addition "Subject Alternative Name" field should contain the network name ending with the .cluster1.ydb.company.net suffix. Upon successful authentication, the connection will be assigned the registerNode@cert SID.

client_certificate_authorization:
  request_client_certificate: true
  client_certificate_definitions:
    - member_groups: ["registerNode@cert"]
      subject_dns:
      - suffixes: [".cluster1.ydb.company.net"]
      subject_terms:
      - short_name: "OU"
        values: ["cluster1"]
      - short_name: "O"
        values: ["YDB"]
Previous
TLS
Next
Observability