microsoft.ad.cs_template module – Manage AD Certificate Services certificate templates

Note

This module is part of the microsoft.ad collection (version 1.10.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install microsoft.ad.

To use it in a playbook, specify: microsoft.ad.cs_template.

New in microsoft.ad 1.11.0

Synopsis

• Create, modify, or remove Active Directory Certificate Services (AD CS) certificate templates.

• New templates are created by cloning an existing source template and overriding specific properties such as key size, extended key usages, or validity period.

• Templates can optionally be published to (or unpublished from) one or more Enterprise Certificate Authorities.

Parameters

Parameter	Comments
certificate_name_flag list / elements=string	List of certificate name flag values to set on the template. Each value can be a well-known name or a raw integer (decimal or hex). Multiple values are combined with bitwise OR. Maps to the msPKI-Certificate-Name-Flag LDAP attribute. Well-known names: enrollee_supplies_subject, enrollee_supplies_subject_alt_name, subject_alt_require_domain_dns, subject_alt_require_spn, subject_alt_require_directory_guid, subject_alt_require_upn, subject_alt_require_email, subject_alt_require_dns, subject_require_dns_as_cn, subject_require_email, subject_require_common_name, subject_require_directory_path.
display_name string	The human-readable display name of the template. Defaults to the value of name if not specified.
domain_server string	The FQDN of the domain controller to target for all AD operations. When not specified, the module will use the default domain controller discovery.
enrollment_flag list / elements=string	List of enrollment flag values to set on the template. Each value can be a well-known name or a raw integer (decimal or hex). Multiple values are combined with bitwise OR. Maps to the msPKI-Enrollment-Flag LDAP attribute. Well-known names: include_symmetric_algorithms, pend_all_requests, publish_to_kra_container, publish_to_ds, auto_enrollment_check_user_ds_certificate, auto_enrollment, previous_approval_validate_reenrollment.
extended_key_usages list / elements=string	List of Extended Key Usage (EKU) values. Each value can be a well-known name or a raw OID string. Maps to the pKIExtendedKeyUsage LDAP attribute. Well-known names: server_authentication, client_authentication, code_signing, secure_email, ip_security_end_system, ip_security_tunnel, ip_security_user, time_stamping, ocsp_signing, smart_card_logon, certificate_request_agent, encrypting_file_system, file_recovery, key_recovery, key_recovery_agent, document_signing, remote_desktop, kdc_authentication.
key_size integer	Minimum key size in bits for the certificate. Maps to the msPKI-Minimal-Key-Size LDAP attribute.
key_usage list / elements=string	List of key usage flags to set on the template. Maps to the pKIKeyUsage LDAP attribute. Valid values: digital_signature, non_repudiation, key_encipherment, data_encipherment, key_agreement, key_cert_sign, crl_sign, encipher_only, decipher_only.
name string / required	The CN (common name) of the certificate template. This is the unique short name used internally by AD CS (no spaces).
private_key_flag list / elements=string	List of private key flag values to set on the template. Each value can be a well-known name or a raw integer (decimal or hex). Multiple values are combined with bitwise OR. Maps to the msPKI-Private-Key-Flag LDAP attribute. Well-known names: require_private_key_archival, exportable_key, strong_key_protection_required, require_alternate_signature_algorithm, require_same_key_renewal, use_legacy_provider, ek_trust_on_use, ek_validate_cert, ek_validate_key, attest_preferred, attest_required, attestation_without_policy, hello_logon_key.
publish_to_ca list / elements=string	List of Enterprise CA short names to which the template should be published. When specified, the module ensures the template is published to exactly the listed CAs and unpublished from any others. An empty list [] will unpublish the template from all CAs. When omitted, publishing state is not managed.
renewal_period_days integer	Certificate renewal overlap period in days. Maps to the pKIOverlapPeriod LDAP attribute.
schema_version integer	Certificate template schema version. 2 requires Windows Server 2003+, 3 requires 2008+, 4 requires 2012+. Maps to the msPKI-Template-Schema-Version LDAP attribute. Choices: 2 3 4
source_template string	The display name of an existing template to clone when creating a new template (e.g. WebServer, User, Computer). Required when creating a template for the first time. Ignored when the template already exists (updates are applied in-place).
state string	Whether the template should be present or absent. When absent, the template is unpublished from all CAs, the template AD object is removed. Choices: "present" ← (default) "absent"
validity_period_days integer	Certificate validity period in days. Maps to the pKIExpirationPeriod LDAP attribute.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: windows	Target OS/families that can be operated against

Notes

Note

• This module must be run on a Windows target host with the ActiveDirectory PowerShell module available.

• Enterprise Administrator permissions are required to create or remove certificate templates in the Configuration partition.

• Certificate templates are stored in the AD Configuration partition and replicated forest-wide.

• Publishing a template requires that at least one Enterprise CA is installed in the forest, but the module does not need to run on the CA server itself.

See Also

See also

microsoft.ad.object_info

Gather information an Active Directory object.

Examples

- name: Create a certificate template cloned from WebServer with RSA 4096
  microsoft.ad.cs_template:
    name: Web4096Secure
    display_name: Web Server (RSA 4096)
    source_template: Web Server
    key_size: 4096
    extended_key_usages:
      - server_authentication
    key_usage:
      - digital_signature
      - key_encipherment
    private_key_flag:
      - exportable_key
    certificate_name_flag:
      - enrollee_supplies_subject
    validity_period_days: 365
    renewal_period_days: 42
    state: present

- name: Create a template with specific EKUs for server authentication
  microsoft.ad.cs_template:
    name: CustomAuth
    source_template: Web Server
    extended_key_usages:
      - server_authentication
      - "1.3.6.1.4.1.311.20.2.2"
    state: present

- name: Use raw integer flags alongside named flags
  microsoft.ad.cs_template:
    name: MixedFlags
    source_template: Web Server
    enrollment_flag:
      - auto_enrollment
      - publish_to_ds
    private_key_flag:
      - exportable_key
      - 0x00000100
    state: present

- name: Update key size on an existing template
  microsoft.ad.cs_template:
    name: Web4096Secure
    key_size: 8192
    state: present

- name: Publish a template to a specific CA
  microsoft.ad.cs_template:
    name: Web4096Secure
    publish_to_ca:
      - contoso-DC01-CA
    state: present

- name: Unpublish a template from all CAs
  microsoft.ad.cs_template:
    name: Web4096Secure
    publish_to_ca: []
    state: present

- name: Remove a certificate template
  microsoft.ad.cs_template:
    name: Web4096Secure
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
distinguished_name string	The distinguished name of the certificate template object. Returned: always Sample: "CN=Web4096Secure,CN=Certificate Templates,CN=Public Key Services,CN=Services,CN=Configuration,DC=contoso,DC=com"
template_oid string	The OID of the certificate template. Returned: always Sample: "1.3.6.1.4.1.311.21.8.11489019.14294623.5588661.594850.12204198.151.6616009.14891906"

Authors

• Ron Gershburg (@rgershbu)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication