ArcGIS Server .NET 9.x-10.0

= Overview =

ArcGIS Server .NET is the most reliable, scalable, efficient, and supportable of these is the ArcGIS Server .NET. The reason behind this is ArcGIS Server's reliance on DCOM, a MS Technology that is best suited to Windows environments and MS integrated technologies. For this reason, ArcGIS Server .NET eclipses deployments of ArcGIS Server Java 10.0.

= Token Security =

When enabled token security allows a token value to be used to access secured services. This token value contains a pre-authenticated username, referrer value, and expiration.

How Token Security Works
Token security works by querying a token service URL (which by default requires SSL) with a specific set of parameters (user,pass,referrer,timeout,etc..) as a HTTP GET request. The token service responds by first authenticating the user/pass combination, and then generating a hashed value that contains the username and referrer value. Once a token is obtained, it must be appended to each and every subsequent request to the secured service, which allows the requestor access to service data they are authorized to view.

Example of How Token Security Works


1. ArcCatalog connects to a Service endpoint be it a REST or SOAP endpoint (http://server/arcgis/rest/services or http://server/arcgis/services) and is presented with a HTTP 401 Challenge.

2. ArcGIS Server sends ArcCatalog the token service URL where it can obtain a token to access the secured endpoint: http://server/arcgis/tokens).  This information is configurable within the C:\inetpub\wwwroot\arcgis\rest\web.config (REST) and the C:\inetpub\wwwroot\arcgis\services\web.config (SOAP) files: C:\inetpub\wwwroot\arcgis\rest\web.config (Sample file)

          3. ArcCatalog requests a token from https://server/arcgis/tokens (SSL is required for this to function): http://westshore/ArcGIS/tokens?request=getToken&username=avi&password=avi@esri.com&referrer=westshore 4. The token service responds with a token string that contains the username, referrer value, and timeout if applicable. BQfVFxZeKyB0y6XeZXeU4j7i3-ASPvOEVzTGgSNwy6g. 5. ArcCatalog then appends the token to each subsequent request for service data: http://westshore/arcgis/services?token=BQfVFxZeKyB0y6XeZXeU4j7i3-ASPvOEVzTGgSNwy6g.

Example of Token Validation
When a token string is passed to a service endpoint (REST/SOAP) the following validation procedure kicks off:

1. Once a token is received by the SOAP/REST endpoint, it is passed to the token service to validate it:
 * BQfVFxZeKyB0y6XeZXeU4j7i3-ASPvOEVzTGgSNwy6g. -> Passed to http://westshore/ArcGIS/tokens for validation
 * Note that the service endpoint looks to it's web.config file for the Token Service URL it should use.

2. At this point the Token service does a few things:

2a. Validates Token String can be decoded based on the "Shared Key Value" within the token service's web.config file. (HTTP 499 if validation fails)

2b. Validates Token Timeout is > Current Date (HTTP 499 if validation fails)

2c. Validates Referrer (This is where things get deep): Accept: */* Content-Type: text/xml SOAPAction: "" Referer: westshore User-Agent: ArcGIS Client Using WinInet Host: westshore Content-Length: 332 Connection: Keep-Alive Pragma: no-cache Accept: */* Content-Type: text/xml SOAPAction: "" Referer: 49.22.49.18 User-Agent: ArcGIS Client Using WinInet Host: westshore Content-Length: 332 Connection: Keep-Alive Pragma: no-cache
 * If the token created contains a "referrer" value, then the token service compares that value against the header value from the service endpoint that made the request. If the referrer value contained within the token = the referrer value from the header of the service making the request, the token validates. If not, an HTTP 499 error is thrown.
 * If the token created contains a "clientid" value, then the token service compares that value against the header value from the client machine that initially provided the user/pass. If the clientid value contained within the token = the referrer value from the header of the service making the request, the token validates. If not, an HTTP 499 error is thrown.

Easy Peasy Short Lived Token
By far the easiest way to validate token security is working is to create a short-lived, unlocked token. This is a token with no timeout and no referrer value specified. These tokens last, by default, 60 minutes. (It is possible to increase or decrease this timeout value within the web.config file for the token service).

Request a short lived token:

http(s):///ArcGIS/tokens? request=gettoken &username= &password= &referrer= &timeout=

Example:

https://westshore/ArcGIS/tokens?request=gettoken&username=avi&password=avi@esri.com&f=html

Returns:

EqG6-o-6TCNwDNBwcAq-IIbSjwBx1uXyDTgvdSp_0nc.

Site Locked Long Lived Token
To request a long lived token, access the following URL either through a browser or programatically. Long lived tokens last for the period defined in the timeout value below, up to 365 days.

http(s):///ArcGIS/tokens? request=gettoken &username=<USER> &password=<PASSWORD> &referrer=<HOST/FQDN OF SERVER HOSTING SERVICE> &timeout=<TIMEOUT IN MINUTES>

Example:

https://westshore/ArcGIS/tokens?request=gettoken&username=avi&password=avi@esri.com&referrer=westshore&timeout=14400

Returns:

BQfVFxZeKyB0y6XeZXeU4j7i3-ASPvOEVzTGgSNwy6g.

Client Locked Long Lived Token
The following requests a long lived token (timeout defined by the timeout value in minutes) which is only usable by an a machine with the IP Address specified by the clientid value.

http(s)://<SERVERNAME>/ArcGIS/tokens? request=gettoken &username=<USER> &password=<PASSWORD> &clientid=<CLIENT IP ADDRESS> &timeout=<TIMEOUT IN MINUTES>

Example:

https://westshore/ArcGIS/tokens?request=gettoken&username=avi&password=avi@esri.com&clientid=42.56.17.12&timeout=14400

Returns:

JogurNKROlnN0xfZdTwFihVISynMwJhSq1dfPpApBSFy4RPAlHNz4k1aVDZer-3n

Dynamic Client Locked Long Lived Token
The following requests a long lived token (timeout defined by the timeout value in minutes) that queries the client IP address before generating the token, and then uses the address that comes back from the client to generate the token. This is the best way to support reverse proxied/load balanced ArcGIS Servers with Client Locked tokens because it is the only way to ensure that the IP used to create the token is the IP of the actual client system.

http(s)://<SERVERNAME>/ArcGIS/tokens? request=gettoken &username=<USER> &password=<PASSWORD> &clientid=requestip &timeout=<TIMEOUT IN MINUTES>

Example:

https://westshore/ArcGIS/tokens?request=gettoken&username=avi&password=avi@esri.com&clientid=requestip&timeout=14400

Returns:

JogurNKROlnN0xfZdTwFihVISynMwJhSq1dfPpApBSFy4RPAlHNz4k1aVDZer-3n

Revalidating an Invalid Token
A token can only be revalidated if:
 * Its timeout value has not expired.
 * The reason it is invalid is because the username that created it is disabled.
 * The password doesn't actually matter because the token doesn't contain a password.

If the above is true, a token that is no longer functioning can be re-validated if the user account that it was created with is restored with the same username. If this does not work, its safe to assume the timeout has expired and the token will have to be re-generated.

Within Applications
Once we have a token (regardless of what type of token), it must be appended to each and every URL request for a secured service. Taking the above token, we can access a secured service as follows:

http://<SERVER>/ArcGIS/rest/services/<SERCUREDSERVICE>/MapServer?token=lxLwgOVMRGc0rGcVjropZnd4-H_O9HOmN8WOgabrpds.

This also means that the token must be updated within all applications before the timeout expires or the applications will cease functioning once the token expiration date has passed

Example (Using Token to Connect to REST endpoint):
http://westshore/ArcGIS/rest/services/Secured/Exercise3/MapServer?token=lxLwgOVMRGc0rGcVjropZnd4-H_O9HOmN8WOgabrpds.

Example (Using Token to Connect to SOAP endpoint):
http://westshore/ArcGIS/services/Secured/Exercise3/MapServer?wsdl&token=lxLwgOVMRGc0rGcVjropZnd4-H_O9HOmN8WOgabrpds.

Dynamic Tokens
Organizations that do not want to update their code regularly with a new long-lived token should implement the following proxy page solution with their applications:

Proxy Page - Dynamic Token Generation & Use http://forums.esri.com/Attachments/39143.zip

Deploy the above application on an IIS Server with ASP.NET 2.0 installed. Edit the code within the proxy.config file as follows:

<serverUrl url="http://YOURSERVER.DOMAIN.COM/ArcGIS/rest/services/SecuredMapServices/NorthAmerica/MapServer" matchAll="true" dynamicToken="true" host="" userName="YOURUSERNAME" password="YOURPASSWORD"> </serverUrl>

Once deployed, applications will need to be updated to use resources through the above published Proxy Page. See the following for further details: http://help.arcgis.com/en/webapi/javascript/arcgis/help/jshelp_start.htm

Shared Token Key
One use case for the Shared Token Key covered in the ArcGIS Help (http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_dotnet_help/index.html#/Configuring_the_Token_Service/0093000000q5000000/) is to support Token Security behind a Load Balancer. If you are running multiple back-end ArcGIS Servers behind a Load Balancer, and you wish to support Token Security, you should seriously consider using the same Shared Key for all back-end ArcGIS Servers. As a result, any token generated from Server 1 will authenticate within Server 2.

SSL Security
SSL (Secure Socket Layer) sometimes/incorrectly described as HTTPS is a means of establishing a secure channel between ArcGIS Server (or web server) and ArcGIS Clients. Implementing SSL Security has a number of challenges that must be mitigated.

Rest Login HTTPS
To make the Rest Login page use HTTPS follow the guidance in the following help topic: http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_dotnet_help/index.html#//0093000000q4000000#GUID-32B82F61-B34B-4906-ACB9-B1A2B3F35771

SSL & Reverse Proxy
If SSL (https) is enabled on either the reverse proxy web server or on the internal web server ArcGIS Server is using then SSL will actually need to be enabled on both web servers to avoid communication issues (NIM056497).

In addition 'Require Encrypted Web Access' will also have to be enabled for the Root services directory within ArcGIS Server: http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_dotnet_help/0093/0093000000q4000000.htm#GUID-32B82F61-B34B-4906-ACB9-B1A2B3F35771

Login Problems with Nested Domain Groups
Nesting a Domain Group into the Local "agsadmin" group will fail on all versions prior to AGS .NET 10.0 SP2. If you see this issue, apply SP2.

Security Auditing
Commonly customers will report login problems both with DCOM authenication as well as login problems with ArcGIS Server Manager (among other login interfaces.) When the basic documented requirements are met (member of agsadmin or agsusers) and a login problem persists, the cause can sometimes be uncovered by auditing LOGIN FAILURES and reviewing the details within the Windows Event Viewer.

See the following MS Article for details on both enabling auditing and reviewing audit logs: http://technet.microsoft.com/en-us/library/cc731607(WS.10).aspx

It is always advisable to begin auditing on the local ArcGIS Server system first, where the initial authentication occurs. If no failure audits are found but a login failure occurs, it will be necessary to perform the security audits on the Active Directory domain controller.

Windows Security Requirements
Professional Services provided a document on what local security policy settings need to be set at to allow ArcGIS Server to function. Professional Services Windows Security Requirements

= Windows Security =

Login Problems with Nested Domain Groups
Nesting a Domain Group into the Local "agsadmin" group will fail on all versions prior to AGS .NET 10.0 SP2. If you see this issue, apply SP2.

Security Auditing
Commonly customers will report login problems both with DCOM authenication as well as login problems with ArcGIS Server Manager (among other login interfaces.) When the basic documented requirements are met (member of agsadmin or agsusers) and a login problem persists, the cause can sometimes be uncovered by auditing LOGIN FAILURES and reviewing the details within the Windows Event Viewer.

See the following MS Article for details on both enabling auditing and reviewing audit logs: http://technet.microsoft.com/en-us/library/cc731607(WS.10).aspx

It is always advisable to begin auditing on the local ArcGIS Server system first, where the initial authentication occurs. If no failure audits are found but a login failure occurs, it will be necessary to perform the security audits on the Active Directory domain controller.

Windows Security Requirements
Professional Services provided a document on what local security policy settings need to be set at to allow ArcGIS Server to function. Professional Services Windows Security Requirements

Known Issues with ArcCatalog Local Connections
Clients establishing local connections to ArcGIS Server for the purpose of administration and/or to support fine-grained ArcObjects calls rely on network conenctivity provided by DCOM. Provided by the Windows Operating System, DCOM is known to exhibit authentication instabilities as OS versions between client and server diverge significantly. For this reason the following recommendation comes from Esri Support given the number of issues reported by customers:


 * Ensure ArcGIS Desktop version is greater-than or equal to the version of ArcGIS Server
 * Ensure ArcGIS Desktop OS (Operating System) version is greater-than or equal to the OS version on which ArcGIS Server is running.
 * Ensure Domain Controller OS version is less than or equal to the oldest client version on which ArcGIS Desktop is running.

Example Good Configuration: ArcGIS Server - Windows 2008 Server STANDARD ArcGIS Desktop - Windows 7 Domain Controller - Windows 2008 Server R2

Example Bad Configuration: ArcGIS Server - Windows 2008 Server STANDARD ArcGIS Desktop - Windows XP Domain Controller - Windows 2008 Server R2

''Note: DCOM has been officially deprecated by Microsoft, replaced by more stable, scalable, and enterprise oriented .NET Framework connectivity technologies. The 10.1 release of ArcGIS Server officially removes all reliance on DCOM.''

Unable to Make Local Connection to ArcGIS Server from Windows XP to Server 2008
We've seen a number of cases come up where Windows XP is no longer able to connect to ArcGIS Server when the following configuration exists:


 * Domain Controller - Windows 2008 Server
 * ArcGIS Server - Windows 2008 Server
 * ArcGIS Desktop - Windows XP

Fixes:

 * Fix 1:Use local accounts to connect from XP to ArcGIS Server. Add local account to administrator group on ArcGIS Server box.
 * Fix 2: Run ArcGIS Desktop on Windows 7
 * Fix 3: Run ArcGIS Server on Windows 2003 Server
 * Fix 4: Run Domain on Windows 2003 Server
 * Fix 5: Create Active Directory Service Accounts for ArcGISSOC, ArcGISSOM, ArcGISWebServices Accounts. Run the GIS Server Post Install and configure ArcGIS Server to Use these accounts.  Then, on the domain controller, create SPNs for each account: Kerberos Service Principal Name Configuration Issues

Reverse Proxy
Refer to Knowledge Base article 32634: http://support.esri.com/en/knowledgebase/techarticles/detail/32634

If SSL (https) is enabled on either the reverse proxy web server or on the internal web server ArcGIS Server is using then SSL will actually need to be enabled on both web servers to avoid communication issues (NIM056497). In addition 'Require Encrypted Web Access' will also have to be enabled for the Root services directory within ArcGIS Server: http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_dotnet_help/0093/0093000000q4000000.htm#GUID-32B82F61-B34B-4906-ACB9-B1A2B3F35771

Performance
Esri Support does not guarantee server performance due to the range of possible factors involved in achieving performance level. In cases where a specific service is reported slow, Esri Support will request all services but the slowly performing service be stopped for further investigation. If the reported service continues to exhibit performance problems, Esri Support can perform tests including MXD Perfstat http://arcscripts.esri.com/details.asp?dbid=16931 to verify optimal data configuration.

Performance tests run by Esri indicate that, generally, the Maximum number of simultaneously processing instances that can be supported on a CPU core varies by service type, but rarely exceeds 4. This means that even if the ArcGIS Server soc machine is very powerful, it can only really support 4 times the CPU cores' service instances. For example, a machine with 16 cores and 32GB of RAM can support 4*16 = 64 simultaneously executing instances (ArcSOC.exe processes).

Support of performance issues beyond this limit fall within the scope of Esri Professional Services - Implementation Services.

Serving Compact Caches - Workflow

 * 1) Client Accesses AGS Service (SOAP) through Web Tier as HTTP anonymous account. For secure services AppPool owner is associated with the connection.
 * 2) "Services” web application running under ArcGIS Application Pool as ArcGISWebServices account, impersonates access to ArcGISWebServices.
 * 3) Web Tier performs COM/DCOM authentication against GIS Tier as ArcGISWebServices.
 * 4) GIS Tier reads service data as ArcGISSOC account. If the cache does not exist and “cache on demand” is enabled, a call is made to the SOC to generate the tile by accessing the map service data.
 * 5) GIS Tier queries compact cache file as ArcGISSOC account. If the cache exists the “tile handler” is able to query the compact cache and serve it to the client as ArcGIS Web Services user. If the cache does not exist and “cache on demand” is enabled, a call is made to the SOC to generate the tile by accessing the map service data.
 * 6) GIS Tier generates tile from Compact Cache (image file PNG, JPEG, etc).
 * 7) GIS Tier responds (COM/DCOM as ArcGISWebServices) to Web Tier that tile (image file PNG, JPEG, etc) is available at the physical path indicated by cache directory property on the map service.
 * 8) Web Tier accesses location where tile (image file PNG, JPEG, etc) is available at the physical path indicated by cache directory property on the map service as ArcGISWebServices account.
 * 9) Web Tier serves tile to Client as HTTP anonymous account. For secure services AppPool owner serves the tile(s).

Bing Maps
See Bing Maps