Configuring contacts when requesting certificates¶

In TLS Protect Datacenter, certificates have a Contacts field. By default, this field is set using the policy folder’s contacts. If you need to configure the contacts from within Kubernetes rather than from TLS Protect Datacenter, you can do so by configuring the VenafiIssuer or VenafiClusterIssuer, or by using an annotation on the certificate resource.

Important

Being added to the Contacts field of a TLS Protect Datacenter certificate doesn’t mean that you can see that certificate in TLS Protect Datacenter. This means links in the notifications may not be accessible.
It is considered best practice to use a group identity rather than a user identity.
This feature only works if TLS Protect Datacenter is connected to an LDAP or Active Directory.

In Venafi Enhanced Issuer 0.13.0 or later, you can annotate the certificate resources in Kubernetes with your team’s mailing list email so that TLS Protect Datacenter warns you when the certificate fails to be renewed, or is about to expire.

Determining the identity¶

To set the contacts, you must determine an identity string that allows TLS Protect Datacenter to find the group or user. This string depends on what attributes are being searched for by your Active Directory or LDAP connector. Using the attributes userPrincipalName or mail is recommended.

To find the look up attributes:

Go to the Policy Tree.
Click the Identity tab, and then your Active Directory or LDAP provider.
Click the Provider tab in the main window, and then the Search Expressions tab

The relevant search attributes are userPrincipalName and ANR.

Note

The attribute ANR means you can input an RDN, givenName, sn, or displayName as the identity string.

To test an identity string:

Go to the Policy Tree.
Click the Identity tab, and then your Active Directory or LDAP provider.
Click Users & Groups, and enter an identity string in the Search field.

If the identity string is valid, the user name and Active Directory or LDAP information is displayed in the main window. The identity string can, therefore, be used in contact.tppIdentities and in the annotation.

How to set the contacts¶

To set contacts at the issuer level, use the contact field:

kind: VenafiClusterIssuer
spec:
  contact:
    tppIdentities:
    - my-team@company.com
    - my-other-team@company.com

To set contacts on individual certificate resources, you must enable contact annotations:

kind: VenafiClusterIssuer
spec:
  contact:
    enableCertAnnotation: true

Then, annotate the Certificate resource as follows:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  annotations:
    venafi.com/contact-tpp-identities: "my-team@company.com"

Behavior

The annotation can only be used with enableCertAnnotation: true. If this field is false and an annotation is used, an error is reported
When both contact.tppIdentities and the annotation are added, both contacts are used.
Set multiple identities using the annotation by separating them with commas. Empty identities in the annotation are ignored. For example:

venafi.com/contact-tpp-identities: |
  my-team@company.com, my-other-team@company.com

Setting up TLS Protect Datacenter and Venafi Enhanced Issuer to use an email address when requesting certificates¶

To set this feature up, you need to do the following:

Configure the LDAP or Active Directory connector Search Resolution in the Venafi Configuration Console.
Configure the OAuth scope in the TLS Protect Datacenter UI.
Check that Venafi Enhanced Issuer runs with an LDAP or Active Directory user.

How to configure the LDAP or AD connector Search Resolution¶

This action requires TLS Protect Datacenter Operations Administrator privileges.

Active DirectoryLDAP

Log in to the Venafi Platform Windows server and launch Venafi Configuration Console.
Click Connectors, and select your Active Directory connector.
In your Active Directory connector identity properties window, click the User Search tab, select Use Custom Expression, and add the following:
```
(&(|(anr=$search$)(userPrincipalName=$search$))(objectClass=$userclass$))
```
Ensure the User class name field is set to user.
Next, click the Group Search tab, select Use Custom Expression, and add the following:
```
(&(|(anr=$search$)(userPrincipalName=$search$))(objectCategory=$groupclass$)(groupType:1.2.840.113556.1.4.803:=-2147483648))
```
Ensure the Group class name field is set to group.
Then, click the Distribution List Search tab, select Use Custom Expression, and add the following:
```
(&(|(ANR=$search$)(userPrincipalName=$search$))(objectCategory=$distributionclass$)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))
```
Ensure the Distribution List class name field is set to group.

Log in to the Venafi Platform Windows server and launch Venafi Configuration Console.
Click Connectors and select your LDAP connector.
In your connector identity properties window, click the Search Resolution tab.
Add the attribute userPrincipalName to the Login Name Attributes column:

How to check that Venafi Enhanced Issuer runs with an LDAP or Active Directory user¶

The Platform Administrator must ensure that the user used to run Venafi Enhanced Issuer belongs to the same identity connector as the users you want to reference identities from. For example, if the users for which identities are meant to be referenced are in an LDAP or Active Directory, then Venafi Enhanced Issuer must authenticate using a user in that same LDAP or Active Directory.

If Venafi Enhanced Issuer authenticates using a local user, it can't list LDAP or Active Directory users. The annotation doesn’t work for local users as the query customization only operates for the LDAP or Active Directory connector.

How you check if Venafi Enhanced Issuer runs with an LDAP or AD user depends on how you authenticate to TLS Protect Datacenter:

TLS Protect Datacenter JWT Mapping AuthenticationUsername and Password (with HashiCorp Vault)Access Token (with Kubernetes Secret or HashiCorp Vault)

Log in to the Venafi Platform Windows server and launch Venafi Configuration Console.
Click Access Management,
Click JWT Mappings.

You can see the user that is being mapped. If the user starts with local:, you must switch to an LDAP or Active Directory user.

If you use HashiCorp Vault to store the username and password, refer to the username stored in Vault.

If the username starts with local:, you must change to an LDAP or Active Directory user.

If the username doesn't start with either local: or LDAP+something:, prepend local: to the username and try logging into TLS Protect Datacenter's UI with the prepended username. If it works, this user is a local user, and it will be necessary to switch to an LDAP or Active Directory user.

If you are relying on an access token stored in HashiCorp Vault or in a Kubernetes Secret, you need to know what vcert command was used to generate the access token. In particular, what is being passed to --username.

If the username starts with local:, you must change to an LDAP or Active Directory user.

If the username doesn't start with either local: or LDAP+something:, prepend local: to the username and try logging into TLS Protect Datacenter's UI with the prepended username. If that works, this user is a local user, and you must switch to an LDAP or Active Directory user.

How to configure the OAuth scope¶

This action requires TLS Protect Datacenter PKI Administrator privileges.

Note

The following steps are necessary only if you are using a TLS Protect Datacenter version older than 24.1, or a non-default client ID (the default is cert-manager.io) for your integration. In version 24.1 or later, the configuration scope is added to the default cert-manager application.

In TLS Protect Datacenter, go to API > Integrations, and click the cert-manager.io link in the Name column.
Click the Base access tab, and select configuration from the Choose scope drop-down list.
Click Save.

Adding the annotation to certificate resources¶

Once the three tasks outlined above are completed, application developers will be able to add the annotation to the Certificate resources.

Using Kyverno to enforce the annotation in every certificate resource

Optionally, you can apply the following YAML file to create a Kyverno rule to enforce the presence of the annotation on all certificate resources:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
    name: venafi-enhanced-issuer:enforce-contacts-annotation
spec:
  background: false
  rules:
  - name: venafi-enhanced-issuer:enforce-contacts-annotation
    match:
      resources:
        kinds:
        - Certificate
    validate:
      message: "Certificates must have the annotation venafi.cert-manager.io/contacts"
      pattern:
        metadata:
          annotations:
            venafi.cert-manager.io/contacts: '*'

Notes and best practices¶

Missing "configuration" scope

If you encounter an error message indicating that Venafi Enhanced Issuer lacks the necessary permissions to query TLS Protect Datacenter for users, ensure the application on TLS Protect Datacenter is configured to grant the "configuration" scope. For more information, see How to configure the OAuth scope above.
Unresolvable identity set on Certificate/Issuer

This error typically occurs when Venafi Enhanced Issuer doesn't use an Active Directory or LDAP identity for TLS Protect Datacenter authentication. Consequently, the user or group requested within the certificate cannot be found in Active Directory or LDAP. To mitigate this, verify that the Venafi Enhanced Issuer makes use of an Active Directory or LDAP identity for authentication with TLS Protect Datacenter. Additionally, confirm that the user or group specified in the certificate exists within their Active Directory or LDAP environment.
What happens in the case of an unknown contact identity?

When using the annotation or using the field contact.tppIdentities, if the identity is incorrect or no longer present in the LDAP or Active Directory, the certificate issuance will fail.
Changes made to the Contacts annotation are only applied during a renewal

The identities in the annotation and in the field contact.tppIdentities are only registered while requesting the certificate; once the certificate has been issued, changes to the annotation won’t be propagated to TLS Protect Datacenter.
Always use a group or distribution list

It is best practice to use a group or distribution list rather than a user. If an employee leaves the company, their entry is removed from the Active Directory. A certificate that was successfully issued may fail while renewing in that case.