Introduction
Appery.io Proxy – is a service that can be used for testing in desktop browsers to avoid cross-domain security problems. When using the proxy, the request is first sent to the proxy server, and then from the server, the request is made to the service. Because the request is sent from the server and not from the page, cross-domain security is not triggered.
Read about more cross-domain service calls.
Appery.io provides two kinds of proxies – default and secure proxy.
The Secure Proxy
feature additionally allows you to keep your secret keys, credentials, or other data safe from being accessed by app users.
Secure Proxy
works in this way:
- You store your secret data in a database under key names.
- Then you create a secure proxy for replacing the key names with secret data.
- In the app, you use key names and define the proxy that should be used.
- The app invokes a REST Service that contains key names, and on the server side key names are replaced with its appropriate values.
Using the app, you can find the key and proxy names, but you have no access to the secured data.
Creating Appery.io default proxy
1. Switch to the Secure Proxy
tab:
2. To create a new proxy, click “Create new proxy.” Enter the proxy name:
3. The created proxy opens with default settings:
4. The Proxy ID
and Proxy name
are unique values. Proxy name
is used to define the proxy channel in the app:
5. Now this proxy can be chosen from the Appery.io builder:
If you set
Response Data Type
–JSONP
, the Appery.io proxy cannot be used.
After that, using the proxy will be automatically turned on for this REST service.
Create proxy from the Appery.io builder
Proxies can also be created from inside the Appery.io builder:
1.Click “New Channel” on the Settings
tab of any REST Service.
2. Enter name for new proxy and click “Create”.
Once the new proxy is created, using the proxy for this service will be automatically enabled with it:
Only the default proxy can be created from the builder.
Using the Secure Proxy
As mentioned above, by using Secure Proxy
you can secure sensitive data by keeping it only in the database. In this case only the keys (not their values) will be used inside the app.
Storing private data in the database
1. Open the Appery.io Databases
tab.
2. Create a new database or use an existing one.
3. Create a new collection, and enter any name (for example, secretKeys
):
4. Add two columns: keyName
and secretValue
. Use any names, but note that these names should be easily identifiable.
5. Enter your data. Key names are used in the app. You can use letters, numbers and spaces in key names:
You can create a unique collection for each app, or you can create one database collection that stores private data for all your apps.
Configuring the Secure Proxy
1. To use Secure Proxy
, switch to the Secure Proxy > Proxy
tab, open created proxy and check “Use proxy + store sensitive (private) data in database”.
2. In the opened drop-down menus, select the needed parameters:
3. Click “Save”.
If you edit column names in the database, you should define new names for the proxy channel.
One database can be used in different proxy, just as one proxy can be used for different apps, and in one app, you can use several proxies.
Using Secure Proxy in the App
1. Open your Appery.io app and open the REST Service that should use Secure Proxy
features.
2. On the Settings
tab of that service select created Secure Proxy
from the list:
3. In Request
view, set the key name from the database in braces {KeyName}
as the default value for the corresponding input parameters:
4. Test the app in the browser and invoke the needed REST Service. No actual data will be sent from the app:
5. When testing the service on the Test
tab of the REST Service, enter the actual data instead of the key names; otherwise the test will fail:
All other actions with services are described here.
Restricting URLs access
Using Secure Proxy
also allows creating a list of allowed URLs. This way you can restrict all URLs except of needed ones and be sure that your requests will not be redirected for hacking purposes.
You can’t use the
Allowed URLs
feature without specifyingDatabase
,Collection
,Key column
andValue column
.
1. Go to the Secure Proxy
tab and open your proxy.
2. Find the Allowed URLs
title and add URLs by typing them into text field to the right and clicking “Add”. Here is how you can allow access only to the appery.io and api.worldweatheronline.com:
All other URLs will not be accessible through the REST Service that uses this proxy and the following error will be returned:
1 |
{"code":"PTCT036","description":"Specified URL is not allowed"} |
You can use the *
symbol as mask to replace any number of characters in URL. For example:
1 |
https://*.worldweatheronline.com |
The *
symbol is also automatically added to the end of every URL.
Applying changes for allowed URLs takes 1 minute.
Using old proxy implementation
Proxy implementation was updated and all of your proxies were automatically switched to the new version. The new implementation is faster, and it’s strongly recommended that you use it. The old proxy implementation will be deprecated after a while.
However, if you’re facing any problems with the new proxy implementation, you can switch back to the old version by checking “Use old proxy implementation (slower)” on the proxy page:
The under-the-hood library in the old proxy implementation supports providing ‘username:password’ directly in the URL, e.g.:
1 |
http://user:pass@some.service.com |
In case you experience problems with the new proxy, please contact Appery.io support.
The section “Share with support” is placed at the bottom of the page. When a user enables sharing (turns the toggle
“on”), the specified resource appears in the admin section. This feature can be used by the support team for viewing and accessing all resources (apps, databases, server scripts, etc) shared.
HTTP basic authentication
Some REST API services use HTTP basic authentication to authenticate users. One such service is the Twilio API. You would provide the username and password in the URL. For example:
1 |
http://username:password@host.com/ |
This approach is being phased out by most modern browsers. You can find more information on it for each browser: Chrome, Firefox, IE.
The under-the-hood library that we use for the new Appery.io Proxy also doesn’t support this authentication method (it’s not a bug, the creators of the library decided not to support this). There are two solutions to this problem: switch to Basic header-based authentication, or use the old proxy implementation.
Basic header-based authentication
Switching to Basic header-based authentication is very simple. You need to complete the following steps (from MDN):
- Username and password are combined into a string “username:password”
- The resulting string literal is then encoded using Base64
- The authorization method and a space, i.e. “Basic ” is then put before the encoded string
- A header is added to a service in the following form: Authorization Basic <encoded string>
For example, if the username is: my_user
and the password is: my big secret
, then the header and the encoded string would look like this:
1 |
Authorization: Basic bXlfdXNlcjpteSBiaWcgc2VjcmV0 |
To encode a string into Base64 string can be easily done with the browser’s built-in function window.btoa(string). For example, you can run this from browser’s console:
1 |
window.btoa("my_user:my big secret"); |
Which will result in:
1 |
bXlfdXNlcjpteSBiaWcgc2VjcmV0 |
When you test a service in Appery.io, you can set the entire string as Authentication header default value:
1 |
Basic bXlfdXNlcjpteSBiaWcgc2VjcmV0 |
Alternatively, you can run a JavaScript function during mapping:
1 |
return "Basic " + window.btoa(username+":"+password); |
This approach will allow you to use the new proxy (or the old proxy).
To make secure proxy work, you need to write into the database already encoded content of Authorization header and in the service value field specify something like:
'Basic {auth_data}'
Please read about storing private data in the database on the link.
Permissions Tab
On the Permissions
tab, you can specify the access permissions (View
, Edit
or Delete
) you give the users of your team.
Only your team users may access your resources. Information on how to enable or change the permission options for them can be found here.
The user the proxy was shared with will see it under the Secure Proxy
tab.
The user the proxy was shared with can open it to view or edit, delete or clone it (if granted such rights).
Editing the proxy will cause the original proxy to change. To edit the shared secure proxy without affecting its original, use
Clone
to make a unique copy of it.