Certificates

You can manage signed certificates for mutual TLS authentication for a tenant through the Administration application in the GTV billing platform. The benefits in using this feature include enhanced security with GTV-generated HTTP notification requests and self-service management of certificates within our platform.

You can easily manage one certificate for HTTP requests to your infrastructure or multiple certificates, one for each area of your infrastructure. For example, you may have HTTP requests that go to one site or requests for multiple sites within your company.

You can upload a signed certificate your company obtains, add an external application (host URL) within GTV's system to allow mutual authentication using the certificate, then add the external application to individual notifications. You can also edit, delete, reupload, or change the status of a certificate.

Some examples of GTV-related HTTP requests you can mutually authenticate include:

  • Sending notifications around payment actions.
  • Sending notifications around invoice generation and distribution.
  • Initiating customer communications based on usage thresholds.

Mutual TLS Authentication

Signed certificates in the system use mutual Transport Layer Security (TLS) authentication. This certificate-based authentication certifies that incoming HTTP requests from GTV (like notifications) to your infrastructure are from a trusted GTV application before any data or information is transmitted. Your infrastructure is also authenticated as being a trusted source back to GTV. The image below illustrates this authentication.

An example of mutual authentication between the client (tenant) and GTV is the following: when the GTV application wants to communicate with Acme’s server, they will both authenticate the other and verify that it is who they are expecting to communicate with before any data or messages are transmitted.

  1. GTV sends a message to Acme to show that GTV is a trusted user.
  2. Acme verifies the message. It’s valid.
  3. Acme sends GTV a message back to show that Acme is a trusted user.
  4. GTV verifies the message.
  5. Both parties are verified to be who they claim to be and safe for the other to communicate with.

Viewing Certificates

After you select the Administration application from the Gotransverse action menu , the Users page displays. Select Certificates in the left pane to be taken to the Certificates page. It displays a list of existing certificates and details like Name and Status. The columns are sortable by clicking the header column you want to sort by, such as Status.

On the Certificates page, you can also search by Name (starts with) to filter certificates. Once you enter an item in the Search bar, the Certificates list displays only those items related to the search criteria. Select a certificate from the list to view its detail page.

Viewing Certificate Details

Select a certificate from the Certificates list on the Certificates page to be taken to its detail page. The page includes certificate information such as the Key Algorithm and valid dates for the certificate. There is also a History tab that records actions on the certificate such as the Change Type that was made, like Insert, and the user name of the user that performed the action.

Use Case Example

You can use one certificate for HTTP requests to your infrastructure or multiple certificates, one for each area of your infrastructure. Below is an example where you would need multiple certificates to use for mutual authentication.

The company, Simple, has a website that’s organized by team, so different HTTP notifications need to go to different parts of the site. For example, there is a payment team where all notifications around payment actions need to be sent and there’s a customer support team where all invoice notifications need to be sent.

You upload two signed certificates into the GTV platform. To send the correct notifications to the correct teams, you configure an external application within the GTV platform for each separate host (URL), apply the correct certificate to each external application, then enable mutual authentication for each. Next, configure notifications so that individual notifications, such as associated invoice notifications, are linked to the external application for the team that needs them and the same for payment notifications for the other team. This allows for the correct notifications to be sent to the correct parts of the website and mutually authenticated so each team receives the notifications they need, securely.

See below for the general workflow for the process outlined above.

Certificate Requirements

Before you can upload and manage certificates in the GTV platform, you must generate a signed certificate from a known, trusted certificate provider. For the certificate to be uploaded into the GTV system, the certificate must be signed during generation and have the following:

  • Key Algorithm—RSA 2048 bit key is supported.
  • Certificate Chain—Usually a text file that lists the chains from intermediate to root provider.
  • Certificate Private Key—Created when generating a certificate.

You will need to add the information above for each certificate when you upload it into the GTV system.

Setup Overview

Certificate setup includes:

  1. Generate a signed certificate through a certificate provider.
  2. Upload the certificate into the GTV system.
  3. Create an external application (host URL), associate it with a certificate, and enable mutual authentication on the application.
  4. Add the external application to individual HTTP notifications you want to mutually authenticate with the specified host.
  5. You can also edit, delete, reupload, or change the status of a certificate.

Uploading a Certificate

After you have a signed certificate from a certificate provider, you can upload the certificate into the GTV system so you can use mutual authentication with HTTP action framework notifications.

Note: You will need to supply the Key Algorithm, Certificate Chain, and Certificate Private Key fields which you should have obtained when you generated the signed certificate outside of the GTV platform.

  1. Select Administration from the Gotransverse action menu , then select Certificates in the left pane.
  2. Click Upload Certificate.
  3. Complete the relevant fields in the Upload Certificate window.
    FieldDescription
    Name *Enter a name for the certificate.
    Status*Select a status for the certificate from the dropdown menu.
    • Active—The certificate is active and can be used.
    • Suspended—The certificate is not active and cannot be used. A suspended certificate can be reactivated. A certificate must be suspended before it can be deleted.

    Caution: If you change the certificate status, it may impact the application’s ability to successfully distribute notifications. Because of this, work with GTV support to change a status.

    DescriptionEnter a description for the certificate.
    Type *The generic External Application value populates the field. The external application is the host you want to communicate with during mutual authentication and HTTP requests.
    Key Algorithm *Select RSA 2048 from the dropdown menu. This key uses cryptographic algorithms to encrypt data and protect information being sent to servers.

    Note: You must select RSA 2048 as your key algorithm when you generate your certificate outside of the GTV platform.

    Certificate Chain *Enter the certificate chain information you received when you generated your certificate outside of the GTV platform. The certificate chain lists the chains from intermediate to root provider for your signed certificate.

    The certificate body must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----. The content can be up to 15000 characters.

    Certificate Private Key *Enter the private key you received when you generated your certificate outside of the GTV platform. The key gives you the power to authenticate your site to others, helps to enable encryption, and prevents others from impersonating you. The key can be up to 4000 characters.
  4. * Indicates required field.

  5. Select Upload. The certificate uploads into the GTV platform.

You are now ready to add an external application, enable mutual authentication for it, and associate a certificate with it.

Adding an External Application and Associating it with a Certificate

Once you upload a certificate into the system, update your HTTP configuration in UI 1.0 to:

  • Add an external application.
  • Enable mutual authentication on the external application.
  • Associate a certificate with the external application.

See the External Applications page in the UI 1.0 guide for instructions on how to complete the bulleted tasks above.

Next, you are ready to add the external application to individual HTTP notifications.

Note: If you already have an external application added and configured to work with specific HTTP notifications, you can simply edit the external application by enabling mutual authentication and associating a certificate with it. Since the existing external application is already associated with specific HTTP notifications, skip the Adding an External Application to an HTTP Notification section below unless you need to associate more notifications with the external application.

Adding an External Application to an HTTP Notification

After you add an external application, associate it with a certificate, and enable mutual authentication, you can add it to specific HTTP notifications. See the Configuring the HTTP Operation section in the UI 1.0 guide for instructions on how to complete this task.

Editing a Certificate

You can edit an uploaded certificate’s Name or Description.

  1. Select Administration from the Gotransverse action menu , then select Certificates in the left pane.
  2. Select the desired certificate from the Certificates list.
  3. Select Edit in the Certificate action menu.
  4. In the Edit Certificate Details window, modify the relevant fields.
  5. Select Edit.

    Note: You must reupload a certificate to be able to change any fields not displayed in the image above.

Changing the Status of a Certificate

You can either change the status of a certificate from Active to Suspended or Suspended to Active.

Caution: If you change status, it may impact the application’s ability to successfully distribute notifications. Because of this, work with GTV support to change a status.

Note: You must first suspend a certificate before you can delete it.

  1. Select Administration from the Gotransverse action menu , then select Certificates in the left pane.
  2. Select the desired certificate from the Certificates list.
  3. Select Suspend or Activate (depending on the current status of your certificate) in the Certificate action menu.
  4. In either the Suspend or Activate Certificate window, confirm by selecting Yes.

Deleting a Certificate

To delete a certificate, you must first suspend the certificate.

Caution: If you change status, it may impact the application’s ability to successfully distribute notifications. Because of this, work with GTV support to change a status.

  1. Select Administration from the Gotransverse action menu , then select Certificates in the left pane.
  2. Select a suspended certificate from the Certificates list.
  3. Select Delete in the Certificate action menu.
  4. In the Delete Certificate window, confirm by selecting Yes.

Reuploading a Certificate

You can reupload an existing certificate in the system to add new information like a certificate chain or private key.

  1. Select Administration from the Gotransverse action menu , then select Certificates in the left pane.
  2. Select the desired certificate from the Certificates list.
  3. Select Re-Upload in the Certificate action menu.
  4. In the Re-Upload Certificate window, modify the relevant fields.
  5. Select Re-Upload.

For details about managing certificates using API 2.0, visit our API reference documentation.