Automatic Certificate Management Environment (ACME) with NetScaler using Ansible
Building on our previous guide, “Prep for 47-Day TLS Certificate,” this post dives deeper into empowering your NetScaler automation with Ansible and the ACME protocol. The goal: transform certificate management from a manual headache into a seamless, resilient process.
Why ACME for Certificate Automation?
The Automatic Certificate Management Environment (ACME) protocol is designed to eliminate manual drudgery in obtaining browser-trusted certificates, enabling fully automated, hands-off workflows. Originally developed by the Internet Security Research Group as the backbone of Let’s Encrypt, ACME is now a widely adopted industry standard, trusted by leading certificate authorities.
Securing a certificate with ACME requires proving domain ownership through one of two challenge types:
- HTTP-01 challenge: Fulfill the challenge by serving a unique token over HTTP (port 80) at a specific path on the domain.
- DNS-01 challenge: Publish a verification key as a DNS TXT record to satisfy the challenge request.
Automating NetScaler with Ansible
Ansible’s NetScaler collection equips teams to configure, manage, and orchestrate NetScaler ADC appliances efficiently and repeatably. This is achieved through purpose-built modules harnessing the NITRO API for streamlined automation.
- Collection: Ansible Galaxy - netscaler.adc
Elevate Your Workflow with AWX
Ansible AWX delivers a robust, open-source interface and REST API layered atop Ansible, offering advanced features for secure collaboration. Leverage role-based access control, inventory management, job tracking, and scheduled automation to tighten governance and accelerate your team’s NetScaler initiatives.
Implementation:
AWX
In AWX create an inventory containing the groups and hosts, the Ansible playbook will run on all hosts. This is the location where variables are defined, example:
nsip: 192.0.2.10
nitro_user: service_account
acme_challenge_type: "http-01"
acme_version: 2
acme_email: support@example.com
letsencrypt_dir: "/mnt/teamdata/acme/"
certificates:
- domain_name: website1.example.com
active: true
vserver: CS_VS_ACME_HTTP80
certauthority: letsencryptproduction
- domain_name: website2.example.com
active: true
vserver: CS_VS_ACME_HTTP80
certauthority: letsencryptproduction
Next steps:
- Create a project that, this is the link between the GIT location and AWX
- Create a template linking the inventory, project and the playbook itself
- Create a schedule to execute the playbook on a daily base
Ansible
From the main playbook include the acme task while looping the “certificates” list:
- name: MAIN - certificate_creation
include_tasks: acme.yaml
loop: "{{certificates}}"
loop_control:
loop_var: var_main
when:
- var_main.active
Using openssl the prerequisites to start a ACME challenge can be created:
- Generate account key
- name: Generate account key
vars:
accountkey: "{{ letsencrypt_dir }}account.key"
delegate_to: localhost
shell: "if [ ! -f {{ accountkey }} ]; then openssl genrsa 4096 | tee {{ accountkey }}; fi"
args:
executable: /bin/bash
- Generate private key
- name: Generate private key
delegate_to: localhost
shell: "openssl genrsa 4096 | tee {{letsencrypt_dir}}{{ var_main.domain_name }}.key"
args:
executable: /bin/bash
when: new_cert or renew_cert
- Generate CSR
- name: Generate CSR
delegate_to: localhost
shell: "openssl req -new -sha256 -key {{letsencrypt_dir}}{{ var_main.domain_name }}.key -subj \"/CN={{ var_main.domain_name }}\" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf \"\n[SAN]\nsubjectAltName=DNS:{{ var_main.domain_name }}\")) | tee {{letsencrypt_dir}}{{ var_main.domain_name }}.csr"
args:
executable: /bin/bash
when: new_cert or renew_cert
Begin ACME challenge
- name: Begin ACME challenge
delegate_to: localhost
acme_certificate:
acme_directory: "{{ acme_directory }}"
acme_version: "{{ acme_version }}"
account_key_src: "{{ letsencrypt_dir }}account.key"
account_email: "{{ acme_email }}"
terms_agreed: 1
challenge: "{{ acme_challenge_type }}"
csr: "{{letsencrypt_dir}}{{ var_main.domain_name }}.csr"
dest: "{{letsencrypt_dir}}{{ var_main.domain_name }}.crt"
fullchain_dest: "{{letsencrypt_dir}}/fullchain_{{ var_main.domain_name }}.crt"
remaining_days: 30
modify_account: false
register: acme_challenge_your_domain
when: new_cert or renew_cert
The token to complete the challenge is now registered into the acme_challenge_your_domain variable. This variable will be used to create a responder on the NetScaler and link it to the CS virtual server.
- name : netscaler_challenge - create responder action
delegate_to: localhost
vars:
challenge: "{{ acme_challenge_your_domain['challenge_data'][item]['http-01']['resource_value'] }}"
target_html: >
"HTTP/1.0 200 OK\r\n\r\n{{challenge}}"
netscaler.adc.responderaction:
state: present
name: RP_AC_ACME
type: respondwith
target: "{{target_html}}"
with_items:
- "{{ var_main.domain_name }}"
- name: netscaler_challenge - create responder policy
delegate_to: localhost
netscaler.adc.responderpolicy:
state: present
name: RP_PL_ACME
rule: HTTP.REQ.URL.STARTSWITH("/.well-known/acme-challenge")
action: RP_AC_ACME
- name: netscaler_challenge - bind responder policy
delegate_to: localhost
netscaler.adc.csvserver_responderpolicy_binding:
state: present
bindpoint: REQUEST
name: "{{var_main.vserver}}"
policyname: RP_PL_ACME
priority: 1
Note:
- It can be useful to create a user-defined audit message to get some logging in syslog
Complete ACME challenge to issue the certificate:
- name: 2_1_cert - ACME - Complete challenges
delegate_to: localhost
acme_certificate:
acme_directory: "{{ acme_directory }}"
acme_version: "{{ acme_version }}"
account_key_src: "{{ letsencrypt_dir }}account.key"
account_email: "{{ acme_email }}"
challenge: "{{ acme_challenge_type }}"
csr: "{{ letsencrypt_dir }}/{{ var_main.domain_name }}.csr"
dest: "{{ letsencrypt_dir }}/{{ var_main.domain_name }}.crt"
chain_dest: "{{ letsencrypt_dir }}/chain_{{ var_main.domain_name }}.crt"
fullchain_dest: "{{ letsencrypt_dir }}/fullchain_{{ var_main.domain_name }}"
data: "{{ acme_challenge_your_domain }}"
remaining_days: 30
when: new_cert or renew_cert
Note:
- It’s important to unbind and remove the responder after the challenge has been validated
The server certificate is now available and can be installed on the NetScalers.
- name: upload certfiles to netscaler
delegate_to: localhost
netscaler.adc.systemfile:
state: present
filecontent: "{{ lookup('file', '{{ letsencrypt_dir }}{{ item.filename }}') | b64encode }}"
filelocation: /nsconfig/ssl
filename: "{{ item.filename }}"
loop:
- { filename: "{{ var_main.domain_name }}{{cert_nr_active}}.key" }
- { filename: "{{ var_main.domain_name }}{{cert_nr_active}}.crt" }
- name: install sslcertkey on netscaler
delegate_to: localhost
netscaler.adc.sslcertkey:
state: present
certkey: "CERT_ACME_{{ var_main.domain_name }}"
cert: "{{ var_main.domain_name }}.crt"
key: "{{ var_main.domain_name }}.key"
passplain: "{{ certpassword }}"
password: true
Note:
- The private key is not password protect by default, a task should be implemented to password protect the private key
- The ACME protocol will fetch a full chain certificate for you containing the CA-certificates. This can be used to install the CA’s on the NetScaler and make the links.
The Let’s Encrypt certificates are only valid for 90 days, the certificates can be automatically renewed before expiring.
Updating server certificate is not possible with the Ansible collection, a Nitro call was used to work around this:
- name: update sslcertkey
delegate_to: localhost
uri:
url: "https://{{ nsip }}/nitro/v1/config/sslcertkey?action=update"
method: POST
status_code: 200
headers:
X-NITRO-USER: "{{ nitro_user }}"
X-NITRO-PASS: "{{ nitro_pass }}"
validate_certs: "{{ validate_certs }}"
body_format: json
body:
sslcertkey:
certkey: "CERT_ACME_{{ var_main.domain_name }}"
cert: "{{ var_main.domain_name }}.crt"
key: "{{ var_main.domain_name }}.key"
passplain: "{{ certpassword }}"
Unlock Effortless Certificate Management
Ready to say goodbye to manual certificate renewals and streamline your security operations? By integrating Ansible, AWX, and ACME with NetScaler, it’s easier than ever to maintain airtight, up-to-date protection for your digital assets.
Have questions, or want to see how this approach fits your environment? Contact one of our experts directly for more information and advice.
