marc
/
CiviProxy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs confirming with style guide

This commit is contained in:
Erik Hommel 2017-07-20 12:37:18 +02:00
parent 19d57e52e5
commit 802843c743
7 changed files with 69 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/configuration.md
View File

@ -2,26 +2,28 @@
!!! caution
We assume you have a very basic understanding of PHP and editing PHP files. If you do not, it is probably a good idea to get some support from a CiviCRM expert. You can find one on [Find an Expert](https://civicrm.org/partners-contributors).
## Configuration of the CiviCRM extension
You can use CiviProxy to ensure that:
You can use CiviProxy to do a couple of things related to mails and mailing for you.
* you can still see all the stuff on the CiviMailing report like the click-throughs and bounces and such;
* you do not want the links in your bulk mailing or individual mails to immediately feed back to your CiviCRM installation but pass through CiviProxy
* you want your subscribe/unsubscribe links to pass through CiviProxy rather than go directly to your CiviCRM installation
* You can still see all the stuff on the CiviMailing report like the click-throughs and bounces and such.
* You do not want the links in your bulk mailing or individual mails to immediately feed back to your CiviCRM installation but pass through CiviProxy.
* You want your subscribe/unsubscribe links to pass through CiviProxy rather than go directly to your CiviCRM installation.
If you want to do any of these things, you will need to install and configure the CiviCRM extension **de.systopia.civiproxy** in your CiviCRM installation.
If you have not installed the extension already, check [Installing CiviCRM](installation.md) for instructions how to.
!!! note
If you do not install the **de.systopia.civiproxy** extension you can still use CiviProxy to whitelist your API requests.
Once you have installed the CiviCRM extension (check the [Installing CiviProxy](installation.md) section of this guide for instructions) you will need to configure the CiviProxy settings. To do this, go to Administer/Administration Console. You will see the CiviProxy Settings in the System Settings section of the menu as you can see below.
Once you have installed the CiviCRM extension you will need to configure the CiviProxy settings. To do this, go to **Administer>Administration Console**. You will see the CiviProxy Settings in the System Settings section of the menu as you can see below.
![Administration Console - System Settings](img/administration_console.png)
If you click on the CiviProxy Settings you will get a page with a few settings for CiviProxy. If you access the page for the first time these will be empty. The settings you can enter are:
1. A checkbox to enable or disable the CiviProxy functionality with your CiviCRM mailing links.
1. A text field where you can add the URL of your CiviProxy server. This link will be validated and the version of the CiviProxy will be shown. If the URL does not meet the validation (does not contain a valid CiviProxy installation), there will be an error message.
1. A text field for a path to the unsubscribe page that will be used. There is a basic unsubscribe page on your CiviProxy server, the path to this page will be the default. If the default unsubscribe page is not what you would like, then you can either update the page in the CiviProxy installation on your server or create your own page and set the URL here.
1. A checkbox CiviProxy Enabled to enable or disable the CiviProxy functionality with your CiviCRM mailing links.
1. A text field Proxy URL where you can add the URL of your CiviProxy server. This link will be validated and the version of the CiviProxy will be shown. If the URL does not meet the validation (does not contain a valid CiviProxy installation), there will be an error message.
1. A text field Custom Subscribe/Unsubscribe Pages for a path to the unsubscribe page that will be used. There is a basic unsubscribe page on your CiviProxy server, the path to this page will be the default. If the default unsubscribe page is not what you would like, then you can either update the page in the CiviProxy installation on your server or create your own page and set the URL here.
!!! note
If you do create your own subscription page make sure the parameters and returns and such are the same as in the default unsubscribe page!
@ -38,14 +40,16 @@ The configuration of CiviProxy is mainly controlled with one PHP file called `co
![List of files on your CiviProxy server](img/file%20list%20proxy.png)
### Configuring the URL of your CiviProxy server
First thing you need to configure is the base URL of your CiviProxy server using the `$proxy_base` variable in the `config.php` file:
First thing you need to configure is the base URL of your CiviProxy server using the `$proxy_base` variable in the `config.php` file. As I have used a local test installation I have used `http://localhost/proxy`:
```php
// this should point to the base address of the CiviProxy installation
$proxy_base = 'http://localhost/proxy';
```
### Configuring the link to the secure target CiviCRM
Next thing you want to configure is what your target CiviCRM is. This is the CiviCRM installation which you want CiviProxy to police, so the one where the actual data resides and is collected from or sent to. The assumption is that this CiviCRM resides in some kind of VPN and will accept traffic only from the CiviProxy IP address (and probably a few trusted others like home workers or support people).
You can set the URL of the target CiviCRM using the variable `$target_civirm` in the `config.php` file:
Next thing you want to configure is what your target CiviCRM is. This is the CiviCRM installation which you want CiviProxy to police, so the one where the actual data resides and is collected from or sent to.
The assumption is that this CiviCRM resides in some kind of VPN and will accept traffic only from the CiviProxy IP address (and probably a few trusted others like home workers or support people).
You can set the URL of the target CiviCRM using the variable `$target_civirm` in the `config.php` file. Again, I have used a local test installation:
```php
// this should point to the target CiviCRM system
$target_civicrm = 'http://localhost/ehdev';

BIN
docs/img/network.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 185 KiB

BIN
docs/img/network.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 531 KiB

41
docs/index.md
View File

@ -4,20 +4,21 @@
In the CiviCRM world it is a fairly typical requirement to want your public facing website and CiviCRM to communicate with each other.
You would probably want to do stuff like:
* allow website visitors to sign a petition, make a donation or register for an event
* allow registered website visitors to view and perhaps update their own data
* get website visitors to sign up (or unsubscribe) for newsletters.
* Allow website visitors to sign a petition, make a donation or register for an event.
* Allow registered website visitors to view and perhaps update their own data.
* Get website visitors to sign up (or unsubscribe) for newsletters.
However, for security and maintainability purposes it is recommended that you separate your CiviCRM installation and your public facing website. Factors that might influence this:
- your biggest security risk is probably your public facing website where you want the whole world to be able to check, browse and do stuff, even without identifying themselves.
- the data you want to protect the most is quite likely to be part of CiviCRM (data on your donors, peope who sign petitions, emailaddresses etc.).
- you will need to install security upgrades on your website regularly as this is exposed to the public. However, you do not want to test all your business processes with each upgrade (which you will need to do if you have both website and CiviCRM on the same server to be sure they continue to work together).
* Your biggest security risk is probably your public facing website where you want the whole world to be able to check, browse and do stuff, even without identifying themselves.
* The data you want to protect the most is quite likely to be part of CiviCRM (data on your donors, peope who sign petitions, email addresses etc.).
* You will need to install security upgrades on your website regularly as this is exposed to the public. However, you do not want to test all your business processes with each upgrade (which you will need to do if you have both website and CiviCRM on the same server to be sure they continue to work together).
So we think it is a sound practise to separate CiviCRM and your public facing website, and mainly use the CiviCRM API to send data to or get data from CiviCRM.
However, we do not want every authorized user to be able to use all the API possibilities. And we also do not want to allow any user access to the CiviCRM API.
And that is where **CiviProxy** comes in!
## How does it work?
The basic idea is to first put your CiviCRM (with probably a dummy CMS which you could use for your intranet) server into a VPN. This makes the server virtually inaccessible from the internet, and your users or your whole office will access it via a secure connection.
@ -25,29 +26,25 @@ But what about your public web pages, donation pages, data exchange with other s
In an example picture:
![a picture of an example network architecture](img/network.jpg)
![a picture of an example network architecture](img/network.png)
The advantages in a nutshell :thumbsup:
* CiviProxy is CiviCRM specific, so it kind of understands how CiviCRM works. It is **designed** to work with CiviCRM in a fairly simple way.
* CiviProxy uses **whitelisting**. This means it starts with the principle _nothing is allowed_ and then lets you configure what is allowed, rather than the other way around.
* CiviProxy uses **parameter sanitation**, meaning that only named parameters are allowed, and then only with the allowed content type (string, integer etc.)
* CiviProxy uses **parameter sanitation**, meaning that only named parameters are allowed, and then only with the allowed content type (string, integer etc.).
## What can it do?
Currently CiviProxy can expose/relay the following CiviCRM functions
1. Serve resources for newsletters and mailings
1. Cache those resources, taking load off your CiviCRM server
1. Pass-through of tracking data on opening and click-through rates
1. Sign-on and off of your newsletter (Webpage templates)
1. Relay of whitelisted REST API calls for data exchange with other systems
1. Perform input sanitation and parameter whitelisting for the REST API calls
1. Serve resources for newsletters and mailings.
1. Cache those resources, taking load off your CiviCRM server.
1. Pass-through of tracking data on opening and click-through rates.
1. Sign-on and off of your newsletter (Webpage templates).
1. Relay of whitelisted REST API calls for data exchange with other systems.
1. Perform input sanitation and parameter whitelisting for the REST API calls.
!!! attention
This software has not (yet) been audited for security.
## Why not an application firewall?
The traditional approach to this problem would be an application firewall / reverse proxy setup. However, CiviCRM can have very complex interactions with other systems (e.g. via the API), and a malicious request can sometimes only be detected by understanding the meaning of the individual parameters.
@ -63,3 +60,9 @@ In this guide you will find pages on:
* [how to configure CiviProxy](configuration.md)
* [what to do if an outside application wants to communicate with CiviProxy](outside.md)
* [future enhancements for CiviProxy](enhancements.md)
!!! note
This documentation is based on release 0.4 of CiviProxy.
!!! note
In the guide we assume Drupal is the CMS of your target CiviCRM. Most of the stuff is CMS agnostic but you might have to change some of the URL's in the examples.

30
docs/installation.md
View File

@ -1,42 +1,47 @@
# Installation
CiviProxy has to run on its own server (with its own IP address) for maximum effect.
The best option for a server on which you can install CiviProxy is a simple managed webspace, that you can rent cheaply from the hoster of your choice. It should have its own IP address, but other than that there are virtually no restrictions. This approach comes with a lot of advantages:
* Since there are a multitude of clients like you on such a server, the level of security can be expected to be very high, and it should be managed and monitored by professionals 24/7.
* For the same reason, the bandwith and connectivity of such a server should be very high as well.
* The price should not have to be huge
* The price should not have to be huge.
!!! note
Obviously there is nothing stopping you from installing CiviProxy on a server you manage yourself, but that then automatically means you have to ensure you maintain a high level of security and update the stuff regularly!
Installing CiviProxy should be pretty straightforward:
* Download the GitHub repository from [https://github.com/systopia/CiviProxy]()
* Download the GitHub repository from [https://github.com/systopia/CiviProxy]().
* In your repository are actually two relevant parts:
* a CiviCRM extension called **de.systopia.civiproxy** that you can use to send mailings (newsletters) from CiviCRM. This should be installed on your target CiviCRM installation.
* a **proxy** folder with the scripts that you need to install on your CiviProxy server.
* A CiviCRM extension called **de.systopia.civiproxy** that you can use to send mailings (newsletters) from CiviCRM. This should be installed on your target CiviCRM installation.
* A **proxy** folder with the scripts that you need to install on your CiviProxy server.
* On top of that there will also be a **docs** folder containing this guide and a few necessary files (which are needed but you can ignore):
* LIBRARIES.md
* LICENSE
* README.md
* mkdocs.yml
## Installing the CiviCRM extension on your target CiviCRM
* copy the folder **de.systopia.civiproxy** that you downloaded in the previous step into your CiviCRM extensions folder. You should be able to find your civicrm extensions folder in Administer/System Settings/Directories. If you have never touched or changed this it will look like screen print below. In that case your folder is probably `<your civicrm folder>sites/default/files/civicrm/ext/`
* copy the folder **de.systopia.civiproxy** that you downloaded in the previous step into your CiviCRM extensions folder. You should be able to find your civicrm extensions folder in **Administer>System Settings>Directories**. If you have never touched or changed this it will look like screen print below. In that case your folder is probably `<your civicrm folder>/sites/default/files/civicrm/ext/`
!!! seealso
![Screen print of the Administer/System Settings/Directories form](img/civicrm_directories.png)
![Screen print of the Administer>System Settings>Directories form](img/civicrm_directories.png)
* go to Administer/System Settings/Extensions to see a page with all the installed extensions on your CiviCRM installations. You will have to click the **Refresh** button to see the **de.systopia.civiproxy** extension. Click the **install** action listed behind the extension information. Upon successfull installation you should see a list like the one below (although you will probably see a larger list as you will have more extensions installed).
* go to **Administer>System Settings>Extensions** to see a page with all the installed extensions on your CiviCRM installation. You will have to click the **Refresh** button to see the **de.systopia.civiproxy** extension. Click the **Install** action listed behind the extension information. Upon successfull installation you should see a list like the one below (although you will probably see a larger list as you will have more extensions installed).
!!! seealso
![Screen print of the extensions page after successfull installation](img/extensions_list.png)
* type the URL (if you have enabled CleanUrls or `<your website>?q=civicrm/clearcache`) if you do not to clear the caches and rebuild the menu. This is necessary to add the CiviProxy settings page to CiviCRM.
* you should now be able to access the CiviProxy Settings page with Administer/Administration Console (in the menu section System Settings) or with the URL `<your civicrm website>/civicrm/admin/setting/civiproxy` (if you have CleanURLS enabled or if you do not `<your civicrm website>/?q=civicrm/admin/setting/civiproxy`).
* type the URL`http://example.org/civicrm/clearcache` to clear the caches and rebuild the menu. This is necessary to add the CiviProxy settings page to CiviCRM.
!!! note
use the URL `http://example.org/?q=civicrm/clearcache` if CleanUrls are not enabled
* you should now be able to access the CiviProxy Settings page with **Administer>Administration Console** (in the menu section System Settings) or with the URL `http://example.org/civicrm/admin/setting/civiproxy`.
!!! note
use the URL `http://example.org/?q=civicrm/admin/setting/civiproxy` if CleanUrls are not enabled
!!! note
If you want to you can add the CiviProxy Settings page to your Administration menu with Administer/Customize Data and Screens/Navigation Menu.
@ -44,3 +49,6 @@ Installing CiviProxy should be pretty straightforward:
* check the [Configuring CiviProxy](configuration.md) page to see how to configure the CiviProxy extension.
## Installing the Proxy scripts your your CiviProxy server
All you need to do is copy the **proxy** folder on the webspace you want to use for CiviProxy.
As described in [Configuring CiviProxy](configuration.md), you will need to make changes to the `config.php` file. You can either do those changes locally first and then move all the files to your webspace, or move all the files to your webspace first and then changes the `config.php` file there.

10
docs/outside.md
View File

@ -1,4 +1,12 @@
# What to do if an outside application wants to communicate with CiviProxy
In most cases when an outside application (for example the public website, or maybe even a center webservice) wants to access CiviProxy to be able to retreive data from CiviCRM or send data to CiviCRM they will want to use the API.
In that case you should provide them with the Site key and an API key they can use. They will have to use your CiviProxy URL in their REST request, and you will need to provide them with that URL.
In that case you should provide them with the Site key and an API key they can use. We recommend you do NOT use the CiviCRM Site Key and API Key.
!!! tip
If you do not know how to do this check [Configuring CiviProxy](configuration.md).
They will have to use your CiviProxy URL in their REST request, and you will need to provide them with that URL. In my local example the call to the CiviProxy server would be:
```
http://localhost/proxy/rest.php?entity=Contact&action=getsingle&key=erikhtestkey&version=3&json=1&api_key=testerikhapikey&email=pipotest@example.org
```

2
docs/requirements.md
View File

@ -3,7 +3,7 @@
There shouldn't be any requirements that any web hoster wouldn't comply with, but here they are:
1. PHP 5.3+
2. PHP PEAR (to install on Debian/Ubunto, run `apt-get install php-pear`).
2. PHP PEAR (to install on Debian/Ubunto, run `apt-get install php-pear`)
3. Read/write permissions on your webspace
4. Reasonable amount of protection, i.e. only authorised users (you) can upload/download the files
5. Ideally with it's own IP address (makes configuring the VPN easier)