Crear una plantilla de certificado
En esta página, se describen los atributos de una plantilla de certificado y se explica cómo puedes crearla.
Descripción general de las plantillas de certificado
Certificate Authority Service proporciona plantillas reutilizables y parametrizadas que puedes usar en situaciones comunes de emisión de certificados. Una plantilla de certificado representa un esquema de emisión de certificados relativamente estático y bien definido dentro de una organización. El recurso CertificateTemplate
incluye lo siguiente:
- Una expresión de Common Expression Language (CEL) que se evalúa con el asunto solicitado y los SAN en todas las solicitudes de certificado que usan la plantilla. Para obtener más información sobre el uso de CEL, consulta Usa CEL.
- Una lista de entidades permitidas que especifica si se puede copiar al sujeto o su nombre alternativo de la solicitud del usuario final en el certificado emitido.
- Una lista de entidades permitidas opcional que especifica qué extensiones X.509, si las hay, se pueden copiar de la solicitud del usuario final al certificado emitido.
- Un conjunto opcional de valores de extensión X.509 que se agregan a todos los certificados emitidos que usan la plantilla.
En esencia, una plantilla de certificado puede convertirse en un marco de trabajo vertical de emisión de certificados completo. Para obtener más detalles, consulta la definición completa del mensaje CertificateTemplate.
Valores predefinidos en una plantilla de certificado
Los valores predefinidos en una plantilla de certificado se agregan a todos los certificados que la usan. Permiten crear situaciones comunes de emisión de certificados, como mTLS o firma de código. Los valores incluyen lo siguiente:
- Usos de claves: Especifica el uso de clave base para un certificado de acuerdo con la sección 4.2.1.12 de RFC 5280.
- Usos extendidos de claves: Especifica el uso extendido de la clave para un certificado según la sección 4.2.1.3 de RFC 5280.
- Si el certificado es una AC: Especifica si el certificado puede emitir certificados adicionales o si es un certificado de entidad final.
- Longitud máxima de la ruta de la entidad emisora: En el caso de una AC, especifica la cantidad máxima de AC que pueden encadenarse hasta este certificado de AC. Si la longitud máxima de la ruta de acceso del emisor se establece en 0, la AC solo podrá emitir certificados de entidad final. Si se establece en 1, la cadena debajo de este certificado de CA puede incluir solo una CA subordinada. Si no se declara un valor, la cantidad de CA subordinadas en la cadena debajo de esta CA no está delimitada.
- Servidores OCSP de AIA: Hace referencia a los servidores OCSP de la extensión de acceso a la información de autoridad (AIA) de un certificado, como se describe en la sección 4.2.2.1 de RFC 5280.
- Extensiones adicionales de X.509: Describe las extensiones personalizadas de X.509.
En la siguiente muestra de código, se mencionan todos los campos predefinidos en una plantilla de certificado:
keyUsage:
baseKeyUsage:
digitalSignature: true
keyEncipherment: true
contentCommitment: false
dataEncipherment: false
keyAgreement: false
certSign: false
crlSign: false
encipherOnly: false
decipherOnly: false
extendedKeyUsage:
serverAuth: true
clientAuth: false
codeSigning: false
emailProtection: false
timeStamping: false
ocspSigning: false
caOptions:
isCa: true
maxIssuerPathLength: 1
policyIds:
- objectIdPath:
- 1
- 2
- 3
additionalExtensions:
- objectId:
objectIdPath:
- 1
- 2
- 3
critical: false
value: "base64 encoded extension value"
Los valores no especificados en el YAML se omiten o se establecen de forma predeterminada como false
.
Si no se especifica un valor, se omiten las siguientes extensiones:
keyUsage
policyIds
additionalExtensions
- Campo
maxIssuerPathLength
en la extensióncaOptions
Si no se especifica un valor, las siguientes extensiones se establecen de forma predeterminada como false
:
- Campo
isCa
en la extensióncaOptions
Crear una plantilla de certificado
Para crear una plantilla de certificado, usa el siguiente comando gcloud
:
gcloud
gcloud privateca templates create TEMPLATE_ID \
--copy-subject \
--copy-sans \
--identity-cel-expression <expr> \
--predefined-values-file FILE_PATH \
--copy-all-requested-extensions \
--copy-extensions-by-oid <1.2.3.4,5.6.7.8> \
--copy-known-extensions <ext1,ext2>
Reemplaza lo siguiente:
- TEMPLATE_ID: Es el identificador único de la plantilla de certificado.
- FILE_PATH: Es el archivo YAML que describe los valores de X.509 que establece la plantilla de certificado.
La marca --copy-sans
permite que la extensión de nombre alternativo del sujeto (SAN) de la solicitud de certificado se copie en el certificado firmado. Como alternativa, puedes especificar --no-copy-sans
para descartar cualquier SAN especificado del emisor de la solicitud de certificado.
La marca --copy-subject
permite que el sujeto de la solicitud de certificado se copie en el certificado firmado. Como alternativa, puedes especificar --no-copy-subject
para descartar los sujetos especificados por el emisor de la solicitud de certificado.
La marca --identity-cel-expression
toma una expresión CEL que se evalúa con el asunto y el nombre alternativo del asunto del certificado antes de su emisión y muestra un valor booleano que indica si se debe permitir la solicitud. Si quieres obtener información sobre el uso de una expresión de Common Expression Language (CEL) para una plantilla de certificado, consulta Usa CEL para plantillas de certificados.
La marca --predefined-values-file
especifica la ruta a un archivo YAML que describe cualquier valor X.509 predefinido que establezca esta plantilla. Las extensiones proporcionadas se copian en cualquier solicitud de certificado que use esta plantilla y tienen prioridad sobre cualquier extensión permitida en la solicitud de certificado. Si actualizas cualquier parte de los valores predefinidos de X.509, la actualización reemplazará todo el conjunto de valores predefinidos de X.509.
Si se configura la marca --copy-all-requested-extensions
, todas las extensiones especificadas en la solicitud de certificado se copiarán en el certificado firmado. Como alternativa, se puede usar la marca --copy-extensions-by-oid
para copiar OID específicos de la solicitud de certificado en el certificado firmado, y la marca --copy-known-extensions
se puede usar para copiar extensiones de la solicitud de certificado en el certificado firmado. Debe ser uno de los siguientes: base-key-usage
, extended-key-usage
, ca-options
, policy-ids
o aia-ocsp-servers
.
Quita la marca --copy-all-requested-extensions
para ignorar todas las extensiones X.509 en la solicitud de certificado, pero mantén los valores predefinidos definidos en esta plantilla.
Crea una plantilla de certificado para situaciones comunes
En esta sección, se proporcionan comandos de gcloud
a fin de crear una plantilla de certificado para casos de uso comunes.
Certificados TLS del servidor DNS para cualquier dominio
Si quieres crear una plantilla de certificado para emitir certificados TLS del servidor que permitan cualquier dominio, usa las siguientes instrucciones:
Crea un archivo con el nombre
leaf_server_tls_values.yaml
y agrégale la siguiente configuración de TLS del servidor de entidad final:leaf_server_tls_values.yaml
keyUsage: baseKeyUsage: digitalSignature: true keyEncipherment: true extendedKeyUsage: serverAuth: true caOptions: isCa: false
Para permitir solo certificados con SAN de tipo
DNS
, ejecuta el siguiente comandogcloud
:gcloud
gcloud privateca templates create server-tls \ --predefined-values-file leaf_server_tls_values.yaml \ --copy-sans --no-copy-subject \ --identity-cel-expression "subject_alt_names.all(san, san.type == DNS)"
Para obtener más información sobre el comando
gcloud privateca templates create
, consulta gcloud privateca templates create.
Certificados TLS del servidor DNS solo con dominios de prueba
Si quieres crear una plantilla de certificado para emitir certificados TLS del servidor con SAN de DNS limitados a dominios de prueba, usa el siguiente comando gcloud
:
gcloud
gcloud privateca templates create server-tls \
--predefined-values-file leaf_server_tls_values.yaml \
--copy-sans --no-copy-subject \
--identity-cel-expression "subject_alt_names.all(san, san.type == DNS && san.value.endsWith('.test.example.com'))"
El contenido del archivo leaf_server_tls_values.yaml
debe ser el mismo que el del ejemplo anterior.
Si quieres obtener más información sobre el uso de expresiones en CEL para garantizar que los nombres de DNS comiencen o terminen con una string en particular, consulta las expresiones de ejemplo de CEL.
Certificados de identidad de cargas de trabajo
Si quieres crear una plantilla de certificado para emitir certificados TLS mutuos (mTLS), usa las siguientes instrucciones:
Crea un archivo con el nombre
leaf_mtls_values.yaml
y agrégale la siguiente configuración de TLS mutua de entidad final.leaf_mtls_values.yaml
keyUsage: baseKeyUsage: digitalSignature: true keyEncipherment: true extendedKeyUsage: serverAuth: true clientAuth: true caOptions: isCa: false
Para permitir solo certificados con SAN URI de SPIFFE, usa el siguiente comando de
gcloud
:gcloud
gcloud privateca templates create workload-spiffe \ --predefined-values-file leaf_mtls_values.yaml \ --copy-sans --no-copy-subject \ --identity-cel-expression "subject_alt_names.all(san, san.type == URI && san.value.startsWith('spiffe://'))"
Para obtener más información sobre el comando
gcloud privateca templates create
, consulta gcloud privateca templates create.
Si quieres obtener más información sobre el uso de expresiones en CEL para garantizar que los nombres de DNS comiencen o terminen con una string en particular, consulta las expresiones de ejemplo de CEL.
Otorga acceso a la plantilla de certificado
Puedes usar una plantilla de certificado si tienes el rol Usuario de plantilla de certificado del Servicio de CA (roles/privateca.templateUser
). Recomendamos que los autores de una plantilla de certificado otorguen el rol Usuario de plantilla de certificado de servicio de CA a los miembros de la organización que podrían usar esa plantilla de certificado.
Para otorgar la función Usuario de plantilla de certificado del servicio de CA (roles/privateca.templateUser
) a todos en el dominio example.com
, usa el siguiente comando gcloud
:
gcloud
gcloud privateca templates add-iam-policy-binding TEMPLATE_ID \
--member "domain:example.com" \
--role "roles/privateca.templateUser"
Reemplaza lo siguiente:
- TEMPLATE_ID: Es el identificador único de la plantilla de certificado.
Para obtener más información sobre el comando gcloud privateca templates add-iam-policy-binding
, consulta gcloud privateca templates add-iam-policy-binding.
Si quieres obtener más información sobre las funciones de IAM para el servicio de CA y sus permisos asociados, consulta Control de acceso con IAM.
¿Qué sigue?
- Obtén más información sobre Common Expression Language.
- Obtén información para usar Common Expression Language.
- Obtén más información sobre los perfiles de certificación.