Project: Athenz (Provisioning / Key Management)
File: zts-setup.md

<a id="markdown-setup-zts-in-production-env" name="setup-zts-in-production-env"></a> <!-- TOC --> - - - - - - - - - - <!-- /TOC --> <a id="markdown-prerequisites" name="prerequisites"></a> Env. setup done. () Bootstrap setup done. () ZMS is running. () All the setup commands below are expected to run inside container. ```bash docker run --rm -it \ --network="${DOCKER_NETWORK}" \ -v "${BASE_DIR}:/athenz" \ --user "$(id -u):$(id -g)" \ athenz-setup-env \ sh BASE_DIR="$(git rev-parse --show-toplevel)" . "${BASE_DIR}/docker/env.sh" ``` <a id="markdown-target" name="target"></a> <a id="markdown-steps" name="steps"></a> <a id="markdown-1-update-your-passwords" name="1-update-your-passwords"></a> ```bash export ZTSDBROOTPASS=<yourpassword> export ZTSDBADMINPASS=<yourpassword> export ZTSKEYSTOREPASS=<your_password> export ZTSTRUSTSTOREPASS=<your_password> export ZTSSIGNERKEYSTOREPASS=<yourpassword> export ZTSSIGNERTRUSTSTOREPASS=<yourpassword> export ZMSCLIENTKEYSTOREPASS=<yourpassword> export ZMSCLIENTTRUSTSTOREPASS=<yourpassword> ``` <a id="markdown-2-get-a-server-certificate-for-zts" name="2-get-a-server-certificate-for-zts"></a> Create your CSR and private key for ZTS Ask your Athenz CA to sign the CSR and get the server certificate for ZTS ```bash echo ${ZTSCERTKEY_PATH} echo ${ZTSCERTPATH} ``` <a id="markdown-3-create-zts-key-pairs-for-signing-athenz-token" name="3-create-zts-key-pairs-for-signing-athenz-token"></a> ```bash openssl genrsa -out "${ZTSPRIVATEKEY_PATH}" 4096 openssl rsa -pubout -in "${ZTSPRIVATEKEYPATH}" -out "${ZTSPUBLICKEYPATH}" ``` <a id="markdown-4-create-trust-store-containing-all-the-trusted-cas" name="4-create-trust-store-containing-all-the-trusted-cas"></a> Verify CA file paths ```bash ls -l "${ATHENZCAPATH}" ls -l "${USERCAPATH}" ls -l "${SERVICECAPATH}" ``` Create the ZTS trust store ```bash rm -f "${ZTSTRUSTSTOREPATH}" CERTALIAS='athenzca' openssl x509 -outform pem -in "${ATHENZCAPATH}" | keytool -importcert -noprompt \ -keystore "${ZTSTRUSTSTOREPATH}" -storepass "${ZTSTRUSTSTOREPASS}" \ -storetype JKS -alias "${CERT_ALIAS}" CERTALIAS='userca' openssl x509 -outform pem -in "${USERCAPATH}" | keytool -importcert -noprompt \ -keystore "${ZTSTRUSTSTOREPATH}" -storepass "${ZTSTRUSTSTOREPASS}" \ -storetype JKS -alias "${CERT_ALIAS}" CERTALIAS='serviceca' openssl x509 -outform pem -in "${SERVICECAPATH}" | keytool -importcert -noprompt \ -keystore "${ZTSTRUSTSTOREPATH}" -storepass "${ZTSTRUSTSTOREPASS}" \ -storetype JKS -alias "${CERT_ALIAS}" ``` <a id="markdown-5-create-key-store-containing-the-zts-server-certificate" name="5-create-key-store-containing-the-zts-server-certificate"></a> ```bash openssl pkcs12 -export -noiter -nomaciter \ -out "${ZTSKEYSTOREPATH}" -passout "pass:${ZTSKEYSTOREPASS}" \ -in "${ZTSCERTPATH}" -inkey "${ZTSCERTKEY_PATH}" ``` <a id="markdown-6-set-up-for-certificate-signing" name="6-set-up-for-certificate-signing"></a> <a id="markdown-httpcertsigner" name="httpcertsigner"></a> For production environment, we suggest to use the , so that you do not need to manage the signer CA's private key in Athenz server. For details, please refer to . <a id="markdown-keystorecertsigner" name="keystorecertsigner"></a> However, to simplify the setup, we will create an intermediate CA signed by the Service CA (1), and then use that intermediate CA to sign the service certificates issued by Athenz

Create an intermediate CA certificate Create your CSR and private key for the intermediate CA Ask your Service CA to sign the CSR and get the intermediate CA certificate ```bash echo "${ZTSSIGNERCERTKEYPATH}" echo "${ZTSSIGNERCERT_PATH}" ``` Create the key store and trust store for the certificate signer ```bash openssl pkcs12 -export -noiter -nomaciter \ -out "${ZTSSIGNERKEYSTOREPATH}" -passout "pass:${ZTSSIGNERKEYSTOREPASS}" \ -in "${ZTSSIGNERCERTPATH}" -inkey "${ZTSSIGNERCERTKEY_PATH}" rm -f "${ZTSSIGNERTRUSTSTORE_PATH}" CERTALIAS='athenzca' openssl x509 -outform pem -in "${ATHENZCAPATH}" | keytool -importcert -noprompt \ -keystore "${ZTSSIGNERTRUSTSTOREPATH}" -storepass "${ZTSSIGNERTRUSTSTOREPASS}" \ -storetype JKS -alias "${CERT_ALIAS}" ``` <a id="markdown-7-set-up-for-zms-connection" name="7-set-up-for-zms-connection"></a> Create ZTS client certificate Create your CSR and private key for the ZTS client certificate Ask your Service CA to sign the CSR and get the ZTS client certificate ```bash echo "${ZMSCLIENTCERTKEYPATH}" echo "${ZMSCLIENTCERT_PATH}" ``` Create key store and trust store for ZMS connection ```bash openssl pkcs12 -export -noiter -nomaciter \ -out "${ZMSCLIENTKEYSTOREPATH}" -passout "pass:${ZMSCLIENTKEYSTOREPASS}" \ -in "${ZMSCLIENTCERTPATH}" -inkey "${ZMSCLIENTCERTKEY_PATH}" rm -f "${ZMSCLIENTTRUSTSTORE_PATH}" CERTALIAS='athenzca' openssl x509 -outform pem -in "${ATHENZCAPATH}" | keytool -importcert -noprompt \ -keystore "${ZMSCLIENTTRUSTSTOREPATH}" -storepass "${ZMSCLIENTTRUSTSTOREPASS}" \ -storetype JKS -alias "${CERT_ALIAS}" ``` <a id="markdown-note" name="note"></a> You will need to bundle the intermediate CA if your ZTS client certificate is not signed by the Service CA directly. Currently, ZTS cannot rotate its client certificate automatically. Please rotate the keystore file with the new client certificate manually. <a id="markdown-8-summary" name="8-summary"></a> ```log $ tree "${CA_DIR}" prod/CAs athenz_ca.pem service_ca.pem user_ca.pem $ tree "${PRODZTSDIR}" prod/zts zmsclientcert.pem zmsclientcsr.pem zmsclientkey.pem zts_cert.pem zts_csr.pem zts_key.pem ztssignercert.pem ztssignercsr.pem ztssignerkey.pem $ tree "${ZTS_DIR}" zts Dockerfile conf athenz.properties logback.xml zts.properties var certs zmsclientkeystore.pkcs12 zmsclienttruststore.jks zts_keystore.pkcs12 ztssignerkeystore.pkcs12 ztssignertruststore.jks zts_truststore.jks keys zts_private.pem zts_public.pem ``` <a id="markdown-9-register-zts-service-to-athenz" name="9-register-zts-service-to-athenz"></a> Verify Athenz domain admin certificate file paths (created in ) ```bash ls -l "${DOMAINADMINCERTKEYPATH}" ls -l "${DOMAINADMINCERT_PATH}" ``` Add ZTS service using ZMS API ```bash ENCODEDZTSPUBLICKEY="$(base64 -w 0 "${ZTSPUBLICKEYPATH}" | tr '\+\=\/' '\.\-\_')" DATA='{"name": "sys.auth.zts","publicKeys": [{"id": "0","key": "'"${ENCODEDZTSPUBLIC_KEY}"'"}]}' ZMSURL="https://${ZMSHOST}:${ZMS_PORT}" curl --silent --fail --show-error --request PUT \ --cacert "${ATHENZCAPATH}" \ --key "${DOMAINADMINCERTKEYPATH}" \ --cert "${DOMAINADMINCERT_PATH}" \ --url "${ZMS_URL}/zms/v1/domain/sys.auth/service/zts" \ --header 'content-type: application/json' \ --data "${DATA}" curl --silent --fail --show-error --request GET \ --cacert "${ATHENZCAPATH}" \ --key "${DOMAINADMINCERTKEYPATH}" \ --cert "${DOMAINADMINCERT_PATH}" \ --url "${ZMS_URL}/zms/v1/domain/sys.auth/service/zts"; echo ''; ``` <a id="markdown-10-create-athenzconf" name="10-create-athenzconf"></a> Download the public keys of ZMS, so that ZTS can verify contents (e.g. policy, token, etc.) signed by ZMS. ```bash athenz-conf \ -svc-key-file "${DOMAINADMINCERTKEYPATH}" \ -svc-cert-file "${DOMAINADMINCERT_PATH}" \ -c "${ATHENZCAPATH}" \ -z "https://${ZMSHOST}:${ZMSPORT}" \ -t "https://${ZTSHOST}:${ZTSPORT}" \ -o "${ZTSCONFDIR}/athenz.conf" ``` <a id="markdown-deploy-zts" name="deploy-zts"></a> ```bash sh "${DOCKER_DIR}/deploy-scripts/zts-deploy.sh" ``` <a id="markdown-debug-zts" name="debug-zts"></a> ```bash BASE_DIR="$(git rev-parse --show-toplevel)" . "${BASE_DIR}/docker/env.sh" docker run --rm -t \ --network="${DOCKER_NETWORK}" \ -v "${BASE_DIR}:/athenz" \ --user "$(id -u):$(id -g)" \ athenz-setup-env \ sh /athenz/docker/deploy-scripts/zts-debug.sh ``` <a id="markdown-appendix" name="appendix"></a> <a id="markdown-httpcertsigner-details" name="httpcertsigner-details"></a> Update the following properties in `zts.properties`. ```properties athenz.zts.certsignerfactory_class=com.yahoo.athenz.zts.cert.impl.HttpCertSignerFactory athenz.zts.sslkeystore=/opt/athenz/zts/var/certs/ztssignerkeystore.pkcs12 athenz.zts.sslkeystore_type=PKCS12 athenz.zts.ssltruststore=/opt/athenz/zts/var/certs/ztssignertruststore.jks athenz.zts.ssltruststore_type=JKS javax.net.ssl.trustStore=/opt/athenz/zts/var/certs/ztssignertruststore.jks javax.net.ssl.trustStoreType=JKS ```