From 0eb575ca97a5c678d22018a96aafe0b0d4d7dcc9 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Mon, 15 Jun 2026 15:12:51 -0500 Subject: [PATCH 1/2] DOC-6746 RS: Added certificate_subject_line format requirements and fixed examples --- .../certificate-based-authentication.md | 16 ++++++++-- .../certificate-based-authentication.md | 16 ++++++++-- .../certificate-based-authentication.md | 30 +++++++++++++++++-- 3 files changed, 55 insertions(+), 7 deletions(-) diff --git a/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md b/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md index 67ee0d7cb2..16ad0acb33 100644 --- a/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md @@ -96,18 +96,30 @@ Before you can connect to a database using certificate-based authentication, you ### Create certificate auth_method users {#create-cert-users} -When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body : +When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body: ```sh POST /v1/users { "auth_method": "certificate", - "certificate_subject_line": "CN=, OU=, O=, L=, ST=, C=" + "certificate_subject_line": "CN=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. +{{}} +The `certificate_subject_line` must: + +- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format. + +- List the attributes in reverse order, starting with the Common Name (`CN`). + +- Not contain spaces after the commas that separate attributes. + +- Exactly match the certificate's RFC 2253 subject. +{{}} + ## Authenticate REST API requests To use the REST API with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key. diff --git a/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md b/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md index 2710fb0ddc..ee182b7ea3 100644 --- a/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md @@ -80,18 +80,30 @@ Before you can connect to a database using certificate-based authentication, you ### Create certificate auth_method users {#create-cert-users} -When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body : +When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body: ```sh POST /v1/users { "auth_method": "certificate", - "certificate_subject_line": "CN=, OU=, O=, L=, ST=, C=" + "certificate_subject_line": "CN=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. +{{}} +The `certificate_subject_line` must: + +- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format. + +- List the attributes in reverse order, starting with the Common Name (`CN`). + +- Not contain spaces after the commas that separate attributes. + +- Exactly match the certificate's RFC 2253 subject. +{{}} + ## Authenticate REST API requests To use the REST API with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key. diff --git a/content/operate/rs/security/certificates/certificate-based-authentication.md b/content/operate/rs/security/certificates/certificate-based-authentication.md index ba6aa7b27b..bbc33ece9a 100644 --- a/content/operate/rs/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/security/certificates/certificate-based-authentication.md @@ -162,12 +162,24 @@ PUT /v1/cluster POST /v1/users { "auth_method": "certificate", - "certificate_subject_line": "CN=, OU=, O=, L=, ST=, C=" + "certificate_subject_line": "CN=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. + {{}} +The `certificate_subject_line` must: + +- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format. + +- List the attributes in reverse order, starting with the Common Name (`CN`). + +- Not contain spaces after the commas that separate attributes. + +- Exactly match the certificate's RFC 2253 subject. + {{}} + ### Authenticate REST API requests To use the REST API with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key. @@ -186,18 +198,30 @@ To set up certificate-based authentication for databases: 1. Enable mutual TLS for the relevant databases. See [Enable TLS]({{}}) for detailed instructions. -1. When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body : +1. When you [create new users]({{}}), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body: ```sh POST /v1/users { "auth_method": "certificate", - "certificate_subject_line": "CN=, OU=, O=, L=, ST=, C=" + "certificate_subject_line": "CN=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. + {{}} +The `certificate_subject_line` must: + +- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format. + +- List the attributes in reverse order, starting with the Common Name (`CN`). + +- Not contain spaces after the commas that separate attributes. + +- Exactly match the certificate's RFC 2253 subject. + {{}} + ### Authenticate database connections To connect to a database with certificate-based authentication, you must provide a client certificate, signed by a trusted CA, and a private key. The client certificate must either be one you previously added to the database to [enable mutual TLS]({{}}) (`authentication_ssl_client_certs` in the REST API), or be signed by one of these certificates. From 7f770ee5badff79d8fd25fb2b935ff00e7665966 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Mon, 15 Jun 2026 15:40:25 -0500 Subject: [PATCH 2/2] DOC-6697 Added a note to specify a single OU for certificate_subject_line in cert-based auth --- .../security/certificates/certificate-based-authentication.md | 2 ++ .../security/certificates/certificate-based-authentication.md | 2 ++ .../security/certificates/certificate-based-authentication.md | 4 ++++ 3 files changed, 8 insertions(+) diff --git a/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md b/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md index 16ad0acb33..2439a86599 100644 --- a/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/7.22/security/certificates/certificate-based-authentication.md @@ -118,6 +118,8 @@ The `certificate_subject_line` must: - Not contain spaces after the commas that separate attributes. - Exactly match the certificate's RFC 2253 subject. + +- Contain only one Organizational Unit (`OU`) value. {{}} ## Authenticate REST API requests diff --git a/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md b/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md index ee182b7ea3..b52e9b901c 100644 --- a/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/7.8/security/certificates/certificate-based-authentication.md @@ -102,6 +102,8 @@ The `certificate_subject_line` must: - Not contain spaces after the commas that separate attributes. - Exactly match the certificate's RFC 2253 subject. + +- Contain only one Organizational Unit (`OU`) value. {{}} ## Authenticate REST API requests diff --git a/content/operate/rs/security/certificates/certificate-based-authentication.md b/content/operate/rs/security/certificates/certificate-based-authentication.md index bbc33ece9a..931e310ef0 100644 --- a/content/operate/rs/security/certificates/certificate-based-authentication.md +++ b/content/operate/rs/security/certificates/certificate-based-authentication.md @@ -178,6 +178,8 @@ The `certificate_subject_line` must: - Not contain spaces after the commas that separate attributes. - Exactly match the certificate's RFC 2253 subject. + +- Contain only one Organizational Unit (`OU`) value. {{}} ### Authenticate REST API requests @@ -220,6 +222,8 @@ The `certificate_subject_line` must: - Not contain spaces after the commas that separate attributes. - Exactly match the certificate's RFC 2253 subject. + +- Contain only one Organizational Unit (`OU`) value. {{}} ### Authenticate database connections