venafi-oauth-helper

Configure Venafi TPP

This step may need to be performed by a Venafi TPP Administrator.

• In the API Integrations page (Configuration -> API Application Integration), create a new API Integration.
• Set the name to anything to like (e.g jetstack-cert-manager-app)
• For the permissions, select read, manage, revoke certificates
• IMPORTANT - Set the application id to cert-manager.io
• In the Access Limits, select Configure and set the Grant Expiration to number of days you want the refresh token to be valid (For e.g 730 days)
• Select the Token Refresh to enabled
• Set the Token expiration to a shorter period to number of days you want (for e.g. 1 day).
• After Saving, authorize the Venafi TPP user(s) who will have access to the cert-manager.io application by clicking Edit Access and adding the user.

The above step ensures that the user who is authorized to access cert-manager.io application has the ability to request an access token. This is a one time step that needs to be completed by the Venafi Administrator.

Configure venafi-oauth-helper

Create a Bootstrap Secret

venafi-oauth-helper can be bootstrapped using refresh-token, username-password, or client-certificate credentials.

For an Issuer the bootstrap Secret must be in the same namespace as the Issuer.

For a ClusterIssuer the bootstrap Secret must be in the --cluster-resource-namespace. By default this is the same namespace as the venafi-oauth-helper Pod (cert-manager) but it may be different if you have installed venafi-oauth-helper in a different namespace, of if you have changed the --cluster-resource-namespace command line option.

...using a refresh-token

This is the most secure bootstrap method because you will not have to store the username-password or client-certificate in a Secret in the Kubernetes cluster. These sensitive credentials can be stored outside the cluster and need only be accessed when deploying the venafi-oauth-helper.

The disadvantage of this configuration is that if the refresh-token reaches its time limit, or if a new refresh-token is not successfully saved after rotation, or if the refresh-token is revoked, then the venafi-oauth-helper will cease to function until a new refresh-token is generated and saved to the Kubernetes Secret by an administrator.

Create the refresh-token

If you do not have credentials to the Venafi Platform, your Venafi administrator will need to run this command :

vcert getcred --username REPLACE_WITH_VENAFI_TPP_USER \
              --password REPLACE_WITH_VENAFI_TPP_PASSWORD \
              -u https://REPLACE_WITH_VENAFI_TPP_HOSTNAME/vedsdk \
              --client-id cert-manager.io \
              --scope "certificate:manage,revoke" \
              --format json > /tmp/token

Save the refresh-token to a Kubernetes Secret

In this step, we will create a bootstrap secret using the refresh-token that we retrieved in the previous step.

kubectl apply -f- <<EOF
apiVersion: v1
kind: Secret
metadata:
    name: issuer-1-credentials-voh-bootstrap
    namespace: ISSUER_NAMESPACE #  ⚠ or CLUSTER_RESOURCE_NAMESPACE when using a ClusterIssuer
stringData:
    refresh-token: $(jq -r .refresh_token < /tmp/token)
    refresh-token-expires: $(jq -r ".refresh_until|todate" < /tmp/token)
EOF

...using a username-password

Alternatively you can create a bootstrap secret containing a username-password, and the advantage of this is that venafi-oauth-helper can always request a new refresh-token, even if the last live refresh-token becomes invalid.

This is less secure because your username-password, which has greater privileges than a refresh-token, are now stored in the Kubernetes Cluster and therefore more exposed to accidental leakage and malicious use.

Update the username-password and apply the YAML:

kubectl apply -f- <<EOF
apiVersion: v1
kind: Secret
metadata:
    name: issuer-1-credentials-voh-bootstrap
    namespace: ISSUER_NAMESPACE #  ⚠ or CLUSTER_RESOURCE_NAMESPACE when using a ClusterIssuer
stringData:
    username: REPLACE_WITH_VENAFI_TPP_USER
    password: REPLACE_WITH_VENAFI_TPP_PASSWORD
EOF

...using a client-certificate

In this configuration, you store a client-certificate in the bootstrap credentials Secret.

This is less secure, because your client-certificate, which may have greater privileges than a refresh-token, is now stored in the Kubernetes Cluster and therefore more exposed to accidental leakage and malicious use.

kubectl create secret generic \
    issuer-1-credentials-voh-bootstrap \
    --namespace=ISSUER_NAMESPACE \ #  ⚠ or CLUSTER_RESOURCE_NAMESPACE when using a ClusterIssuer
    --from-file=p12-archive='/path/to/pfx/file.pfx' \
    --from-literal=p12-password='PFX_DECRYPTION_PASSWORD'

Annotate the Bootstrap Secret

Annotate the Secret so that venafi-oauth-helper can match the bootstrap Secret to your Issuer:

kubectl annotate secret issuer-1-credentials-voh-bootstrap \
    voh.jetstack.io/issuer=issuer-1 \
    --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE>

venafi-oauth-helper will immediately use this bootstrap credential to get an access-token and a new live refresh-token and these will be stored to separate Secret resources. Thereafter, the live refresh-token will be used to renew the access-token. If the live refresh-token fails, then venafi-oauth-helper will automatically try using the bootstrap credential again to generate a new refresh-token, but this will only work if you use a username-password or a client-certificate for the bootstrap credential.

Configure cert-manager

Create a cert-manager Issuer (or ClusterIssuer), referencing a Secret, but do not create the Secret.

kubectl apply -f- <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: issuer-1
spec:
  venafi:
    zone: "REPLACE_WITH_YOUR_VENAFI_POLICY_FOLDER"
    tpp:
      url: https://REPLACE_WITH_VENAFI_TPP_HOST/vedsdk
      caBundle: REPLACE_WITH_BASE64_ENCODED_CERT_CHAIN_TO_ACCESS_VENAFI
      credentialsRef:
        name: issuer-1-credentials
EOF

Check to see the status of the issuer. It should be ready.

kubectl get issuer issuer-1

kubectl describe issuer issuer-1

Verify the configuration

Request a certificate

kubectl apply -f- <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: test-certificate
spec:
  secretName: test-certificate
  privateKey:
    rotationPolicy: Always
  dnsNames:
    - test.example.com
  commonName: test.example.com
  issuerRef:
    name: issuer-1
    kind: Issuer
EOF

A certificate should be issued successfully.