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: Live -
188.8.131.52, Sandbox -
- 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 general information on the request. You may get more insights on the contents of the payload by clicking through the “General”/”Headers”/”Body” tabs and their “Request”/”Response” buttons.
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 this 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 almost the same! That’s the general information on logged request. To see what your server will receive, click on the Body tab.
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 look at the “Body” tab - here’s the payload we’re about to reveal. Click on “Secure this payload” button.
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 details and some general information on request:
Now switch to “Body” tab and you’ll see the raw request you sent compared to 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.
Sandbox vs Live¶
VGS offers two environments to work in — the Sandbox environment, a virtual sandbox where you can play around with your routes without having to worry about messing up your real-life data, and the Live environment — where you can configure your live vault and start securely sending and receiving sensitive data.
How to Switch Environment¶
When you first log in to your new account you will be in the Sandbox Environment using sandbox Test Vault. After activating organization, you can switch between the Live and Sandbox environments, simply hovering your cursor over your Vault list and clicking on “Live Vault” that has green Live environment label. Note: if you haven’t created a Live Vault yet, just click Add Vault and choose Live.
The Live Environment¶
The Live environment is for functional and working data security solution. However, proceed with caution: all of the changes you make here are real. After completing the steps outlined below, you will be able to securely send and accept real data.
In order for you to start sending and accepting sensitive data, you will (at a minimum) need to do the following things in the Live Environment:
- Create Live Vault
- Create Route in your Live Vault (set up inbound and/or outbound connection)
- Proceed to the next section or click here to read the full guide on how to get started in Live
Verify that all your routes configuration settings have been set up correctly.
The Sandbox Environment¶
Want to test out VGS solution without fear that you’ll break everything? A Sandbox is a good place for you. It’s a playground for testing VGS routes configurations. Sensitive data cannot be used in the Sandbox environment. Therefore, it’s a risk-free and stress-free environment to test out VGS. You can easily modify your settings or even wipe the whole vault if you’d like.
It’s a great environment for developers because you can test without any consequences. You can simulate real-life situations. It allows you to test all possible scenarios without risks.
How to Tell What Environment You’re In¶
Not only is there a message that lets you know when you’re in the sandbox:
However, you’ll also notice labels next to the vault name in the list of vaults designating sanbox and live environments.
Learn how to promote your Sandbox integration from test mode to live. In order to process live data, you will need to make sure you go through the “going live” process.
Use the following steps to start processing live data:
Activate your Organization¶
- Create a Vault in a live environment
- If there is none, create a Live Vault by hovering your cursor over your Vault list and clicking on “Add Vault”, then choosing “Live”
- Test your routes in a sandbox environment
- Create/promote (using YAML) route/s to Live environment
- Invite other team members to collaborate (if needed)
Advanced Preferences you might want to set up:¶
IP whitelisting to restrict IPs and IP ranges that requests originated from. IP address the request is made from will be matched against comma-separated list of IPs or CIDRs. For example: 184.108.40.206/32, 192.168.0.15/24
CNAMEs allows you to use your own domain as an alias to verygoodproxy.com Thus, your users may seamlessly transition between VGS and you without recognizing that the content exists on two separate domains.
Two-way SSL allows upload of certificates to establish a trusted connection with the third party services (that demand two-way ssl type of connection) like Visa and MasterCard.
After going live: Use the dashboard to monitor your requests. Keeping an eye on your dashboard analytics (requests and upstream latency) can let you know what might need to be changed.
If you have any questions or need assistance with integrating VGS, please contact us. You can email us at firstname.lastname@example.org, or reach out to us via intercome live chat.