Skip to content
This repository has been archived by the owner on Apr 26, 2023. It is now read-only.

Commit

Permalink
Merge pull request #293 from Esri/patch-49
Browse files Browse the repository at this point in the history 
unduplicate proxy.config doc and samples
  • Loading branch information
@jgravois
jgravois committed Oct 13, 2015
2 parents cb4cda8 + ee1d26e commit c576d9a
Show file tree
Hide file tree
Showing 4 changed files with 75 additions and 161 deletions.
58 changes: 9 additions & 49 deletions DotNet/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ A .NET proxy that handles support for
* Enabling logging
* Both resource and referer based rate limiting

##Instructions
## Instructions

* Download and unzip the .zip file or clone the repository. You can download [a released version](https://github.com/Esri/resource-proxy/releases) (recommended) or the [most recent daily build](https://github.com/Esri/resource-proxy/archive/master.zip).
* Install the contents of the DotNet folder as a .NET Web Application, specifying a .NET 4.0 application pool or later. For example using the following steps:
Expand All @@ -25,7 +25,7 @@ http://[yourmachine]/DotNet/proxy.ashx?ping
http://[yourmachine]/DotNet/proxy.ashx?http://services.arcgisonline.com/ArcGIS/rest/services/?f=pjson
```
* Troubleshooting: If you get an error message 404.3, it's possible that ASP.NET have not been set up. On Windows 8, go to "Turn Windows features on or off" -> "Internet Information Services" -> "World Wide Web Services" -> "Application Development Features" -> "ASP.NET 4.5".
* Edit the proxy.config file in a text editor to set up your proxy configuration settings.
* Edit the proxy.config file in a text editor to set up your [proxy configuration settings](../README.md#proxy-configuration-settings).
* Update your application to use the proxy for the specified services. In this JavaScript example requests to route.arcgis.com will utilize the proxy.

```
Expand All @@ -36,68 +36,28 @@ http://[yourmachine]/DotNet/proxy.ashx?http://services.arcgisonline.com/ArcGIS/r
```
* Security tip: By default, the proxy.config allows any referrer. To lock this down, replace the ```*``` in the ```allowedReferers``` property with your own application URLs.

##Proxy Configuration Settings

* Use the ProxyConfig tag to specify the following proxy level settings.
* **mustMatch="true"** : When true only the sites listed using serverUrl will be proxied. Set to false to proxy any site, which can be useful in testing. However, we recommend setting it to "true" for production sites.
* **allowedReferers="http://server.com/app1,http://server.com/app2"** : A comma-separated list of referer URLs. Only requests coming from referers in the list will be proxied. See https://github.com/Esri/resource-proxy/issues/282 for detailed usage.
* **logFile="proxylog.txt"** : When a logFile is specified, the proxy will log messages to this file.
* Add a new \<serverUrl\> entry for each service that will use the proxy. The proxy.config allows you to use the serverUrl tag to specify one or more ArcGIS Server services that the proxy will forward requests to. The serverUrl tag has the following attributes:
* **url**: Location of the ArcGIS Server service (or other URL) to proxy. Specify either the specific URL or the root (in which case you should set matchAll="false").
* **matchAll="true"**: When true all requests that begin with the specified URL are forwarded. Otherwise, the URL requested must match exactly.
* **username**: Username to use when requesting a token - if needed for ArcGIS Server token based authentication.
* **password**: Password to use when requesting a token - if needed for ArcGIS Server token based authentication.
* **domain**: The Windows domain to use with username/password when using Windows Authentication.
* **clientId**. Used with clientSecret for OAuth authentication to obtain a token - if needed for OAuth 2.0 authentication. **NOTE**: If used to access hosted services, the service(s) must be owned by the user accessing it, (with the exception of credit-based esri services, e.g. routing, geoenrichment, etc.)
* **clientSecret**: Used with clientId for OAuth authentication to obtain a token - if needed for OAuth 2.0 authentication.
* **oauth2Endpoint**: When using OAuth 2.0 authentication specify the portal specific OAuth 2.0 authentication endpoint. The default value is https://www.arcgis.com/sharing/oauth2/.
* **accessToken**: OAuth2 access token to use instead of on-demand access-token generation using clientId & clientSecret.
* **rateLimit**: The maximum number of requests with a particular referer over the specified **rateLimitPeriod**.
* **rateLimitPeriod**: The time period (in minutes) within which the specified number of requests (rate_limit) sent with a particular referer will be tracked. The default value is 60 (one hour).
* **hostRedirect**: The real URL to use instead of the "alias" one provided in the `url` property and that should be redirected. Example: `<serverUrl url="http://fakedomain" hostRedirect="http://172.16.85.2"/>`.

Note: Refresh the proxy application after updates to the proxy.config have been made.

Example of proxy using application credentials and limiting requests to 10/minute
```
<serverUrl url="http://route.arcgis.com"
clientId="6Xo1d-example-9Kn2"
clientSecret="5a5d50-example-c867b6efcf969bdcc6a2"
rateLimit="600"
rateLimitPeriod="60"
matchAll="true">
</serverUrl>
```
Example of a tag for a resource which does not require authentication
```
<serverUrl url="http://sampleserver6.arcgisonline.com/arcgis/rest/services"
matchAll="true">
</serverUrl>
```
Note: You may have to refresh the proxy application after updates to the proxy.config have been made.

##Folders and Files
## Folders and Files

The proxy consists of the following files:
* proxy.config: This file contains the configuration settings for the proxy. This is where you will define all the resources that will use the proxy. After updating this file you might need to refresh the proxy application using IIS tools in order for the changes to take effect. **Important note:** In order to keep your credentials safe, ensure that your web server will not display the text inside your proxy.config in the browser (ie: http://[yourmachine]/proxy/proxy.config).
* proxy.config: This file contains the [configuration settings for the proxy](../README.md#proxy-configuration-settings). This is where you will define all the resources that will use the proxy. After updating this file you might need to refresh the proxy application using IIS tools in order for the changes to take effect. **Important note:** In order to keep your credentials safe, ensure that your web server will not display the text inside your proxy.config in the browser (ie: http://[yourmachine]/proxy/proxy.config).
* proxy.ashx: The actual proxy application. In most cases you will not need to modify this file.
* proxy.xsd: a schema file for easier editing of proxy.config in Visual Studio.
* Web.config: An XML file that stores ASP.NET configuration data.
* Web.config: An XML file that stores ASP.NET configuration data.
NOTE: as of v1.1.0, log levels and log file locations are specified in proxy config. By default the proxy will write log messages to a file named auth_proxy.log located in 'C:\Temp\Shared\proxy_logs'. Note that the folder location needs to exist in order for the log file to be successfully created.

##Requirements
## Requirements

* ASP.NET 4.0 or greater (4.5 is required on Windows 8/Server 2012, see [this article] (http://www.iis.net/learn/get-started/whats-new-in-iis-8/iis-80-using-aspnet-35-and-aspnet-45) for more information)

##Issues
## Issues

Found a bug or want to request a new feature? Let us know by submitting an issue.

##Contributing
## Contributing

All contributions are welcome.

##Licensing
## Licensing

Copyright 2014 Esri

Expand Down
38 changes: 8 additions & 30 deletions Java/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ A Java proxy that handles support for
* Enabling logging
* Both resource and client IP based rate limiting

##Instructions
## Instructions

* Download and unzip the .zip file or clone the repository. You can download [a released version](https://github.com/Esri/resource-proxy/releases) (recommended) or the [most recent daily build](https://github.com/Esri/resource-proxy/archive/master.zip).
* Install the contents of the Java folder as a Web Application in a web container such as Apache Tomcat.
Expand All @@ -21,7 +21,7 @@ http://[yourmachine]:8080/Java/proxy.jsp?ping
```
http://[yourmachine]:8080/Java/proxy.jsp?http://services.arcgisonline.com/ArcGIS/rest/services/?f=pjson
```
* Edit the proxy.config file in a text editor to set up your proxy configuration settings.
* Edit the proxy.config file in a text editor to set up your [proxy configuration settings](../README.md#proxy-configuration-settings).
* Update your application to use the proxy for the specified services. In this JavaScript example requests to route.arcgis.com will utilize the proxy.

```
Expand All @@ -32,47 +32,25 @@ http://[yourmachine]:8080/Java/proxy.jsp?http://services.arcgisonline.com/ArcGIS
```
* Security tip: By default, the proxy.config allows any referrer. To lock this down, replace the ```*``` in the ```allowedReferers``` property with your own application URLs.

##Proxy Configuration Settings

* Use the ProxyConfig tag to specify the following proxy level settings.
* **mustMatch="true"** : When true only the sites listed using serverUrl will be proxied. Set to false to proxy any site, which can be useful in testing. However, we recommend setting it to "true" for production sites.
* **logFile="\<file with local path\>"** : When a path to a local file is specified event messages will be logged.
* **logLevel="SEVERE"** : Sets the level of logging to be used. Defaults to SEVERE. Possible values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER and FINEST.
* **allowedReferers ="http://server.com/application1,https://server.com/application2"**: A comma-separated list of referer URLs. Only requests coming from referers in the list will be proxied. See https://github.com/Esri/resource-proxy/issues/282 for detailed usage.
* Add new \<serverUrl\> entry for each service that will use the proxy. The proxy.config allows you to use the serverUrl tag to specify one or more ArcGIS Server services that the proxy will forward requests to. The serverUrl tags has the following attributes:
* **url**: Location of the ArcGIS Server service (or other URL) to proxy. Specify either the specific URL or the root (in which case you should set matchAll="false"). If the location starts with "//", any protocol will be accepted, if the location starts with "http://", both http or https will be accepted, and if the location starts with "https://", only https will be accepted.
* **matchAll="true"**: When true all requests that begin with the specified URL are forwarded. Otherwise, the URL requested must match exactly.
* **username**: Username to use when requesting a token - if needed for ArcGIS Server token based authentication.
* **password**: Password to use when requesting a token - if needed for ArcGIS Server token based authentication.
* **tokenServiceUri**: If username and password are specified, the proxy will use the supplied token service uri to request a token. If this value is left blank, the proxy will request a token URL from the ArcGIS server.
* **clientId**. Used with clientSecret for OAuth authentication to obtain a token - if needed for OAuth 2.0 authentication. **NOTE**: If used to access hosted services, the service(s) must be owned by the user accessing it, (with the exception of credit-based esri services, e.g. routing, geoenrichment, etc.)
* **clientSecret**: Used with clientId for OAuth authentication to obtain a token - if needed for OAuth 2.0 authentication.
* **oauth2Endpoint**: When using OAuth 2.0 authentication specify the portal specific OAuth 2.0 authentication endpoint. The default value is https://www.arcgis.com/sharing/oauth2/.
* **rateLimit**: The maximum number of requests from a particular client ip address over the specified **rateLimitPeriod**.
* **rateLimitPeriod**: The time period (in minutes) within which the specified number of requests (rate_limit) sent from a particular client ip address will be tracked. The default value is 60 (one hour).
* **hostRedirect**: The real URL to use instead of the "alias" one provided in the `url` property and that should be redirected. Example: `<serverUrl url="http://fakedomain" hostRedirect="http://172.16.85.2"/>`.

See the proxy.config for examples. Note: Refresh the proxy application after updates to the proxy.config have been made.

##Folders and Files
## Folders and Files

The proxy consists of the following files:
* proxy.jsp: The actual proxy application. In most cases you will not need to modify this file.
* WEB-INF/classes/proxy.config: This file contains the configuration settings for the proxy. This is where you will define all the resources that will use the proxy. After updating this file you will need to restart or update the proxy application from your web container. **Important note:** In order to keep your credentials safe, ensure that your web server will not display the text inside your proxy.config in the browser (ie: http://[yourmachine]:8080/Java/proxy.config).
* WEB-INF/classes/proxy.config: This file contains the [configuration settings for the proxy](../README.md#proxy-configuration-settings). This is where you will define all the resources that will use the proxy. After updating this file you will need to restart or update the proxy application from your web container. **Important note:** In order to keep your credentials safe, ensure that your web server will not display the text inside your proxy.config in the browser (ie: http://[yourmachine]:8080/Java/proxy.config).

##Requirements
## Requirements

* Java 6 or greater

##Issues
## Issues

Found a bug or want to request a new feature? Let us know by submitting an issue.

##Contributing
## Contributing

All contributions are welcome.

##Licensing
## Licensing

Copyright 2014 Esri

Expand Down
Loading

0 comments on commit c576d9a

Please sign in to comment.