/

Outbound Connection

Our outbound connection uses an outbound/forward proxy.

What does it allow you to do?

  • Like the inbound connection, the outbound/forward proxy allows you to rewrite requests and responses on the fly.
  • Lets you operate on data outside of the scope of your backend systems.
  • Set/Change/Strip Headers - perform any operation on the payload.
  • Modify the payload, even if it's not a strict redaction/replacement.
  • Perform Edge Computing, as needed for computing outside of the scope of your system (enterprise plans)
  • Adds an additional layer of security requiring proxy-authorization credentials and a root certificate to be set.
  • Is used to integrate into third party services and allows for configurations that are processor specific as mentioned in the integrations page.
  • Our forward/outbound proxy also allows for IP Anonymization as an additional upgrade.

How does it work?

The forward/outbound proxy directs traffic between your server (outbound) traffic, the VGS vault (where sensitive data is stored), and your third party integration

Example:

  • BEFORE: server.foo.com → api.worldpay.com
  • AFTER: server.foo.com → tenantid.SANDBOX.verygoodproxy.com → api.worldpay.com

To achieve that you should set your server to send traffic through our outbound/forward proxy and create routes, filters and operations for your different API endpoints.

Try it out

Run this sample code snippet in your terminal to see an example of data revealing. Please note, this is a sample test vault and access credentials.

curl __VGS_SAMPLE_ECHO_SERVER__/post -k \
  -x __ACCESS_CREDENTIALS__@__VAULT_HOST__:__PORT__ \
  -H "Content-type: application/json" \
  -d '{"account_number": "__ALIAS__"}'
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format
Check out data redaction code snippet for inbound connection.

Example Use Case You need to send a customer’s Social Security number (SSN) to the Acme Background Check Service. You:

  • have previously collected the social security number
  • exchanged it for a VGS token to store in your database.

Now you should:

  1. Create an outbound route in your VGS dashboard
  2. Set Acme’s endpoint as the upstream host
  3. Add a reveal filter in the request phase to replace the tokenized SSN with the real value
  4. Add the route to your network as a forward proxy

The forward/outbound proxy directs traffic between your server (outbound) traffic, the VGS vault (where sensitive data is stored), and your third party integrations as illustrated by the below image.

forward-proxy-outbound

Use this command for testing the setup to simulate your back end (using cURL)

curl https://api.acme.com -k -X POST \
    -x $HTTPS_PROXY_USERNAME:$HTTPS_PROXY_PASSWORD@$VAULT_ID.sandbox.verygoodproxy.com:8080 \
    -X POST \
    -H "Content-type: application/json" \
    -d '{"ssn": "$VGS_TOKEN"}'
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

How to implement?

We have several examples of API Call specific forward implementations here.

import os
USERNAME = os.environ.get('USERNAME')
PASSWORD = os.environ.get('PASSWORD')
TENANT_ID = os.environ.get('TENANT_ID')
HTTPS_PROXY = "%s:%s@%s.SANDBOX.verygoodproxy.com:8080".format(USERNAME, PASSWORD, TENANT_ID)
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

For many languages, setting the proxy as an environmental variable enables the forward proxy to be used at a framework or library level.

TLS Certificates

The forward proxy requires a TLS certificate. We have a different server certificate for each environment, SANDBOX and LIVE (as you can see from the Python example above). You can find these certificates within the dashboard.

HTTP Basic Authentication

This enables a password of your VGS vault, so that only your application can reveal and access sensitive data. You must provide the username and password via the following URL format. https://username:password@tenant-id.SANDBOX.verygoodproxy.com:8080

Note: Some backend languages require you to access this url by passing auth in a different manner.

VGS forward proxy reveal operations require HTTP Basic Authentication using the username and password provided in the VGS dashboard.

It is up to you to protect these credentials, treat them like an API key. Please refer Basic Authentication for more information.

Tips on storing HTTP Basic Authentication Secrets Securely

  • Do not embed secrets directly in code.
  • Do not store secrets in files inside your application, including the application’s source tree.
  • If you do accidentally commit secrets to version control, revoke it immediately and generate a new one.
  • Ensure secrets not appear in URLs or anywhere they can be captured in web server logs.
  • Review your code carefully and ensure it doesn’t contain secrets or any other private information before publicly releasing it.
  • Put the configuration file containing the secrets in the revision control ignore. This prevents committing them by mistake in the future.
  • Limit the usage of secrets
  • Restrict your secrets to be used by only the IP addresses, referrer URLs, and mobile apps that need them. Don't share your secrets with different applications. If more than one application uses the same API, register each application so you get a new set of secrets and update the secrets.
  • Delete unneeded secrets.
  • Update (Regenerate) your secrets periodically.

References:

Encrypted Communication

VGS supports encryption to protect communications between VGS and your web application. VGS supports the TLS cryptographic protocol. Support for anything less than TLS1.2 is officially deprecated.

For more information regarding TLS:

Alternative Using Reverse Proxy

If your server making outbound requests is already behind a proxy, it can be cumbersome to add a second, chained proxy. You can instead set up a VGS reverse proxy between your server and external services. This is simpler to implement, and suitable for testing, development, and building proof of concepts.

To implement, follow these steps:

  1. If you already have an inbound route configured (which you likely do in order to securely collect PII), create a custom hostname for this route. For this example, suppose your custom hostname is backgroundcheck.yourcompany.com
  2. Create an inbound route in your VGS dashboard
  3. Set Acme’s endpoint as the upstream host
  4. Set the route to allow requests to your custom hostname
  5. Add a reveal filter in the request phase to replace the tokenized SSN with the real value
  6. Modify your back end code to send the background check request to the custom hostname.

The data flow now looks like this.

reverse-proxy-outbound

To test the setup using cURL to simulate your back end, run this cURL command.

curl https://backgroundcheck.yourcompany.com/post -k \
  -x $YOUR_PROXY \
  -X POST \
  -H "Content-type: application/json"  \
  -d '{"ssn": "$VGS_TOKEN"}'
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

If you need any help setting up outbound connections, please contact us on site chat or at support@verygoodsecurity.com.