Criar um modelo de certificado
Nesta página, descrevemos os atributos de um modelo de certificado e explicamos como criar um.
Visão geral dos modelos de certificado
O Certificate Authority Service oferece modelos reutilizáveis e parametrizados que podem ser usados em cenários comuns de emissão de certificados. Um modelo de certificado representa um esquema de emissão de certificados relativamente estático e bem definido dentro de uma organização. O recurso CertificateTemplate
inclui o seguinte.
- Uma expressão Common Expression Language (CEL) que é avaliada em relação ao assunto solicitado e aos SANs em todas as solicitações de certificado que usam o modelo. Consulte Como usar a CEL para mais informações.
- Uma lista de permissões que especifica se o nome alternativo do assunto ou do assunto pode ser copiado da solicitação do usuário final para o certificado emitido.
- Uma lista de permissões opcional que especifica quais extensões X.509, se houver, podem ser copiadas da solicitação do usuário final para o certificado emitido.
- Um conjunto opcional de valores de extensão X.509 que são adicionados a todos os certificados emitidos que usam o modelo.
Um modelo de certificado pode se tornar um framework completo de emissão de certificados verticais. Veja mais detalhes na definição completa da mensagem CertificateTemplate.
Valores predefinidos em um modelo de certificado
Os valores predefinidos em um modelo de certificado são adicionados a todos os certificados que usam esse modelo. Eles permitem a criação de cenários comuns de emissão de certificados, como mTLS ou assinatura de código. Os valores incluem o seguinte:
- Usos de chave: especifica o uso de chave base para um certificado de acordo com a seção 4.2.1.12 do RFC 5280 (em inglês).
- Usos de chave estendidos: especifica o uso estendido de chaves para um certificado de acordo com a seção 4.2.1.3 do RFC 5280 (em inglês).
- Se o certificado for uma CA: especifica se o certificado pode emitir outros certificados ou se é um certificado de entidade final.
- Tamanho máximo do caminho do emissor: no caso de uma AC, ela especifica o número máximo de ACs que podem ser encadeadas a esse certificado de AC. Se o tamanho máximo do caminho do emissor estiver definido como 0, a CA só poderá emitir certificados de entidade final. Se ele for definido como "1", a cadeia abaixo desse certificado de CA poderá incluir apenas uma CA subordinada. Se um valor não for declarado, o número de CAs subordinadas na cadeia abaixo dessa CA será ilimitado.
- Servidores OCSP AIA: são os servidores OCSP na extensão Authority Information Access (AIA) de um certificado, conforme descrito na seção 4.2.2.1 do RFC 5280 (em inglês).
- Extensões X.509 adicionais: descreve extensões X.509 personalizadas.
O exemplo de código a seguir menciona todos os campos predefinidos em um modelo 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"
Os valores não especificados no YAML são omitidos ou padronizados como false
.
As extensões a seguir serão omitidas se um valor não for especificado:
keyUsage
policyIds
additionalExtensions
- Campo
maxIssuerPathLength
na extensãocaOptions
As extensões a seguir usarão false
como padrão se um valor não for especificado:
- Campo
isCa
na extensãocaOptions
Criar um modelo de certificado
Para criar um modelo de certificado, use o seguinte 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>
Substitua:
- TEMPLATE_ID: o identificador exclusivo do modelo de certificado.
- FILE_PATH: o arquivo YAML que descreve os valores X.509 definidos pelo modelo de certificado.
A flag --copy-sans
permite que a extensão de nome alternativo do assunto (SAN, na sigla em inglês) da solicitação de certificado seja copiada no certificado assinado. Também é possível especificar --no-copy-sans
para descartar qualquer SAN especificada pelo autor da chamada da solicitação de certificado.
A flag --copy-subject
permite que o assunto da solicitação de certificado seja copiado no certificado assinado. Também é possível especificar --no-copy-subject
para descartar qualquer assunto especificado do autor da chamada da solicitação de certificado.
A flag --identity-cel-expression
usa uma expressão CEL que é avaliada em relação ao assunto e ao nome alternativo do assunto do certificado antes de ser emitido e retorna um booleano indicando se a solicitação precisa ser permitida. Para informações sobre como usar uma expressão Common Expression Language (CEL) para um modelo de certificado, consulte Como usar a CEL para modelos de certificado.
A sinalização --predefined-values-file
especifica o caminho para um arquivo YAML que descreve os valores X.509 predefinidos definidos por esse modelo. As extensões fornecidas são copiadas para todas as solicitações de certificado que usam esse modelo, tendo precedência sobre quaisquer extensões permitidas na solicitação de certificado. Se você atualizar qualquer parte dos valores X.509 predefinidos, a atualização vai substituir todo o conjunto de valores X.509 predefinidos.
Se a sinalização --copy-all-requested-extensions
for definida, todas as extensões especificadas na solicitação de certificado serão copiadas no certificado assinado. Como alternativa, a sinalização --copy-extensions-by-oid
pode ser usada para copiar OIDs específicos da solicitação de certificado para o certificado assinado, e a sinalização --copy-known-extensions
pode ser usada para copiar extensões da solicitação de certificado para o certificado assinado. Precisa ser uma destas opções: base-key-usage
, extended-key-usage
, ca-options
, policy-ids
ou aia-ocsp-servers
.
Remova a sinalização --copy-all-requested-extensions
para ignorar todas as extensões X.509 na solicitação de certificado, mas ainda manter os valores predefinidos definidos nesse modelo.
Criar um modelo de certificado para situações comuns
Esta seção fornece comandos gcloud
para criar um modelo de certificado para casos de uso comuns.
Certificados TLS do servidor DNS para qualquer domínio
Para criar um modelo de certificado para emitir certificados TLS do servidor que permitam qualquer domínio, use as seguintes instruções:
Crie um arquivo com o nome
leaf_server_tls_values.yaml
e adicione a seguinte configuração de TLS do servidor de entidade final:leaf_server_tls_values.yaml
keyUsage: baseKeyUsage: digitalSignature: true keyEncipherment: true extendedKeyUsage: serverAuth: true caOptions: isCa: false
Para permitir apenas certificados com SANs do tipo
DNS
, execute o seguinte 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 mais informações sobre o comando
gcloud privateca templates create
, consulte gcloud privateca models create.
Certificados TLS do servidor DNS apenas com domínios de teste
Para criar um modelo de certificado a fim de emitir certificados TLS do servidor com SANs
DNS limitadas a domínios de teste, use o seguinte 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'))"
O conteúdo do arquivo leaf_server_tls_values.yaml
precisa ser o mesmo do exemplo anterior.
Para mais informações sobre como usar expressões CEL para garantir que os nomes DNS comecem ou terminem com uma string específica, consulte Exemplos de expressões CEL.
Certificados de identidade da carga de trabalho
Para criar um modelo de certificado para emitir certificados TLS mútuos (mTLS), siga estas instruções:
Crie um arquivo com o nome
leaf_mtls_values.yaml
e adicione a ele a seguinte configuração de TLS mútuo de entidade final.leaf_mtls_values.yaml
keyUsage: baseKeyUsage: digitalSignature: true keyEncipherment: true extendedKeyUsage: serverAuth: true clientAuth: true caOptions: isCa: false
Para permitir apenas certificados com SANs URI SPIFFE, use o seguinte comando
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 mais informações sobre o comando
gcloud privateca templates create
, consulte gcloud privateca models create.
Para mais informações sobre como usar expressões CEL para garantir que os nomes DNS comecem ou terminem com uma string específica, consulte Exemplos de expressões CEL.
Conceder acesso ao modelo de certificado
É possível usar um modelo de certificado se você tiver o papel roles/privateca.templateUser
(Usuário do modelo de certificado de serviço de CA). Recomendamos que os autores de um modelo de certificado concedam o papel de usuário do modelo de certificado de serviço de CA aos membros da organização que possam usar esse modelo.
Para conceder o papel de usuário do modelo de certificado de serviço de CA (roles/privateca.templateUser
) a todos no domínio example.com
, use o seguinte comando gcloud
:
gcloud
gcloud privateca templates add-iam-policy-binding TEMPLATE_ID \
--member "domain:example.com" \
--role "roles/privateca.templateUser"
Substitua:
- TEMPLATE_ID: o identificador exclusivo do modelo de certificado.
Para mais informações sobre o comando gcloud privateca templates add-iam-policy-binding
, consulte gcloud privateca Models add-iam-policy-binding.
Para mais informações sobre os papéis do IAM para o serviço de CA e as permissões associadas, consulte Controle de acesso com o IAM.
A seguir
- Saiba mais sobre o Common Expression Language.
- Saiba como usar a Common Expression Language.
- Saiba mais sobre perfis de certificado.