Integrate in two steps:
- Connect to the VGS Platform
- Create Filters on Routes to Operate on Data
Preparation for Integration¶
There are a few minor requirements/things to know before integrating.
- 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.
- 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:
- We also can integrate you into our service so you can try it out. Just reach out to us on the site chat or email@example.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.
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.
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’.
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.
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.
Even though the data here is just
foo let’s redact it! Click “Secure Payload”.
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
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.
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).
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.
Now that we’ve gone over all the options, let’s click Secure Payload to finalize our choices.
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.
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.
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.
After clicking Secure Outbound Traffic, you’ll see the following screen listening for traffic.
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.
Click on it like the Securing Inbound part and the modal will, once again, pop-up.
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.
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:
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:
Now click on “Request_rewritten” and you’ll see what your third parties will receive.
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 firstname.lastname@example.org.