Getting Started

Integrate in two steps:

  1. Connect to the VGS Platform
  2. Create Filters on Routes to Operate on Data

Preparation for Integration

There are a few minor requirements/things to know before integrating.

  1. We will only accept connections of TLSv1.2 or higher (so if you’re running http:// you won’t be able to connect). We recommend LetsEncrypt. It’s a great open-source, free, Certificate Authority.
  2. When you use our outbound connection we have three static IPs that your requests will come from. If your current connections require your API or third party service to white-list your IP, you’ll want to add the following IP Addresses: 52.7.148.215 52.72.130.32 52.6.216.177
  3. We also can integrate you into our service so you can try it out. Just reach out to us on the site chat or support@verygoodsecurity.com. If you send inbound and outbound curls, we can configure them for you in 30 minutes and show you how to configure your server settings to use our outbound connection.

Creating your Organization and Vault

After you’ve signed up for an account and verified it, we automatically create an organization and sandbox vault. org-creation-progress

Name your organization after your company, you can edit this in the Organization Settings page (navigate to this page through the header dropdown on the top right of your dashboard). Your first Vault will be called Test. You can use it to integrate VGS and protect your test site. Also, your first credentials will automatically be created for you.

Securing your Inbound Connection

Once we’ve created your organization and vault, you will land on your vault overview page to start your integration. secure-connection-starting

To begin, we will connect our inbound traffic. To connect add your host name to the text field. Once you’ve entered it click ‘Establish Connection’. secure-connection-inbound-successful

You’ve just routed your inbound traffic through VGS so now we can introspect on traffic and secure your data.

Now you post data to that URL and you’ll be provided with a log of the payload. access-logger

Click on the log entry and a modal will pop up showing you the contents of the payload (headers and body). Click ‘Secure This Payload’ to begin creating your Filter and Operations. access-logger-introspection

Even though the data here is just foo let’s redact it! Click “Secure Payload”. access-logger-modal Here we only have one JSON item, but nested JSON or JSON lists will also populate, select as many items of the payload as you need to secure and safely store.

Before moving on, let’s review the dropdowns on this modal.

The first dropdown is the operation redact or reveal. This operation can be performed on request OR response. For this guide, we’re just doing requests but we could also redact and reveal responses just as easily. redact-reveal-dropdown

The second dropdown is Storage. We have two options for “Storage” Persistent and Volatile. CVVs and PINs must be stored volatilely (in memory) and have a Time To Live of 1 hr. All other data can be stored persistently. It’s important to note that your “Storage” type needs to match on reveal (we’ll see this on Outbound Connection). storage-dropdown

The third dropdown is the type of alias VGS will return to your server. Currently there are five different Formats. The first one is a proprietary alias. This is best used for non numeric data (in fact it must be used for non-numeric because the other formats are strictly for numbers). For more about these Aliases please check Alias Formats. alias-dropdown

Now that we’ve gone over all the options, let’s click Secure Payload to finalize our choices. secure-confirmation

You can secure more data if you choose, or close out and test what you’ve done. Go ahead and send a request and check it on the Access Logger. access-logger-raw-request

Wait a minute. It looks the same! That tab is the raw request, what VGS received. To see what your server will receive, click request_rewritten. access-logger-rewritten-request

There we go. You have now protected your server from receiving any sensitive information without changing any code.

Securing your Outbound Connection

Let’s click “Outbound” on the left nav under “Secure traffic”. We’ll be greeted with this screen. secure-connection-outbound

After clicking Secure Outbound Traffic, you’ll see the following screen listening for traffic. secure-connection-outbound-waiting

As you can see we have some environmental settings that you can set on your server to run your outbound routes through VGS. If you just want to test the functionality, there is a curl available. If you do decide to go ahead and set up an environmental variable in Python/Ruby or any language/framework of your choice, you’ll need to add our CA cert to your Trusted Certificates (this is self issued to establish a trusted secure connection between you and VGS, not third parties).

-----BEGIN CERTIFICATE-----
MIID2TCCAsGgAwIBAgIHAN4Gs/LGhzANBgkqhkiG9w0BAQ0FADB5MSQwIgYDVQQD
DBsqLnNhbmRib3gudmVyeWdvb2Rwcm94eS5jb20xITAfBgNVBAoMGFZlcnkgR29v
ZCBTZWN1cml0eSwgSW5jLjEuMCwGA1UECwwlVmVyeSBHb29kIFNlY3VyaXR5IC0g
RW5naW5lZXJpbmcgVGVhbTAgFw0xNjAyMDkyMzUzMzZaGA8yMTE3MDExNTIzNTMz
NloweTEkMCIGA1UEAwwbKi5zYW5kYm94LnZlcnlnb29kcHJveHkuY29tMSEwHwYD
VQQKDBhWZXJ5IEdvb2QgU2VjdXJpdHksIEluYy4xLjAsBgNVBAsMJVZlcnkgR29v
ZCBTZWN1cml0eSAtIEVuZ2luZWVyaW5nIFRlYW0wggEiMA0GCSqGSIb3DQEBAQUA
A4IBDwAwggEKAoIBAQDI3ukHpxIlDCvFjpqn4gAkrQVdWll/uI0Kv3wirwZ3Qrpg
BVeXjInJ+rV9r0ouBIoY8IgRLak5Hy/tSeV6nAVHv0t41B7VyoeTAsZYSWU11deR
DBSBXHWH9zKEvXkkPdy9tgHnvLIzui2H59OPljV7z3sCLguRIvIIw8djaV9z7FRm
KRsfmYHKOBlSO4TlpfXQg7jQ5ds65q8FFGvTB5qAgLXS8W8pvdk8jccmuzQXFUY+
ZtHgjThg7BHWWUn+7m6hQ6iHHCj34Qu69F8nLamd+KJ//14lukdyKs3AMrYsFaby
k+UGemM/s2q3B+39B6YKaHao0SRzSJC7qDwbWPy3AgMBAAGjZDBiMB0GA1UdDgQW
BBRWlIRrE2p2P018VTzTb6BaeOFhAzAPBgNVHRMBAf8EBTADAQH/MAsGA1UdDwQE
AwIBtjAjBgNVHSUEHDAaBggrBgEFBQcDAQYIKwYBBQUHAwIGBFUdJQAwDQYJKoZI
hvcNAQENBQADggEBAGWxLFlr0b9lWkOLcZtR9IDVxDL9z+UPFEk70D3NPaqXkoE/
TNNUkXgS6+VBA2G8nigq2Yj8qoIM+kTXPb8TzWv+lrcLm+i+4AShKVknpB15cC1C
/NJfyYGRW66s/w7HNS20RmrdN+bWS0PA4CVLXdGzUJn0PCsfsS+6Acn7RPAE+0A8
WB7JzXWi8x9mOJwiOhodp4j41mv+5eHM0reMh6ycuYbjquDNpiNnsLztk6MGsgAP
5C59drQWJU47738BcfbByuSTYFog6zNYCm7ACqbtiwvFTwjneNebOhsOlaEAHjup
d4QBqYVs7pzkhNNp9oUvv4wGf/KJcw5B9E6Tpfk=
-----END CERTIFICATE-----

Once traffic is detected you’ll be brought back to the logger, and you’ll notice the request you just made already populated. access-logger-outbound-request

Click on it like the Securing Inbound part and the modal will, once again, pop-up. secure-outbound-modal

Let’s secure this payload to reveal it (notice that the json keys are the same here, but that does not matter). You can add the alias to any payload and give it a different name - maybe one required by a third party api and it will work just the same. secure-outbound-reveal

Once you have selected your options (that match how you redacted it Storage and Format). Go ahead and click “Secure This Payload”

Confirmation will appear again: secure-outbound-reveal-confirmation

This time let’s send an actual alias through the outbound route we just created by replace the slug “ALIAS” with the alias returned in the securing inbound connection part of the guide to demonstrate the reveal process.

Once again we’ll see the raw request you sent: access-logger-outbound-raw-request

Now click on “Request_rewritten” and you’ll see what your third parties will receive. access-logger-outbound-rewritten-request

You now have taken sensitive information, swapped it for an alias on inbound, and swapped it back on outbound, keeping sensitive data off your system.

If you’d like to see some working apps integrated with third party APIs, check out our example integrations.

If you need any help contact us on site chat or by email support@verygoodsecurity.com.