ArcGIS Server Security::Token Based Authentication w/ JavaScript API

Securing services for ArcGIS Server is not as difficult as one would think. The ArcGIS Server Manager works as a great tool to lock down services, create and manage a security database, and grant permissions for specific services and or folders.

Step 1: Before you lock down your server, you will need to create a database to manage the security.
Log in into the ArcGIS Server Manager and click on the "Security" tab. Then click on "Settings".

The settings window will have a wizard that allows you to connect to a database server. The wizard will then create a new database with the needed tables to store permissions.  As you are going through the wizard, be sure that you check the box that automatically creates a user and role for "Everyone." We will use this later.

Step 2: Create roles and users
Permissions for the services are managed via roles. After you successfully create a role, you can create a new user or add existing users to that role.  Creating users and roles can be done easily via the ArcGIS Server Manager wizard.


Step 3: Lock down your server
Now that you have a database set up, you are ready to lock down your services.
Go back to the "Setting" section of the "Security" tab.
You will see a section that says: "Security for GIS Services is:   Not Enabled". Beside this text is a button that says "Enable"

Note: Once you Enable security, you cannot undo this via the ArcGIS Server manager.  Don't get frightened away yet, you will see in the next step that this is not a big deal.

Step 4: Grant permission for "Everyone" at the root level
Now that your site is locked down, you need to grant permissions to your services.

 The next few steps are going to assume you have some public services and some private services. Even though security is turned on, we want to make sure that our public services remain public, not requiring a username / password.

Click on the "Services" tab.  It should automatically load the "Manage Services" section. If you are not already there, change the "Services In" pulldown value to your root directory. Then Click Manage Folders -> Permissions. At the root level, grant "Everyone" permission by adding the role to the Access List.

Now security is turned on, but all of your services are public.  I recommend this set up for any initial installation of ArcGIS Server. This will allow you to quickly add permissions when needed.

Step 5: Lock down a folder in your ArcGIS Server
Now that all of our sites are public, we want to lock down specific services.

If your services are organized into folders, this can be done easily. Let's assume you have a folder called "Private".  Switch the "Services in" value to your private folder. Then, click Manage Folders - > Permissions.  Add the role you created to this folder. Be sure to remove "Everyone" from the Access list.

Now your services in this folder will require the a username and password that is associated to that role.

Step 6: Access the Secure Folder via REST interface.
If you're developing applications with the ArcGIS Server Javascript API, the REST interface should be your best friend. However after you lock down a folder, you will notice the interface for that folder is gone from your root services directory:
http://<servername>/ArcGIS/rest/services

To access the "Private" folder, simply type in the URL for your secure folder:
http://<servername>/ArcGIS/rest/services/Private

This will open up a login screen. You can now access the folder with a username / password.

Step 7: Using a secure service in your ArcGIS Server JavaScript API application
The following setup will work great if you would like to have a public ArcGIS Server Javascript API application with secure services embeded into the application. As a result, users will not be able to grab your service URLs and use them in their own applications.

To keep this blog from getting to long, we are going to assume you already have a proxy page set up in your application.  If you do not, that probably means 2 things. You are not printing your maps, and you are not receiving data back in IE where the queries are longer than 2000 characters. Here is a link to setting up your proxy: http://resources.esri.com/help/9.3/arcgisserver/apis/javascript/arcgis/help/jshelp/ags_proxy.htm#webprint

Since we're assuming you already have a proxy set up, the first step is going to be an updating your settings for the proxy in your JavaScript.

The sites are now secure, so you will need to use the proxy page for each request. If you have not done so already, change the "alwaysUseProxy" setting to "true" in your application.
esri.config.defaults.io.alwaysUseProxy = true;
Additionally, change your http references to https for your secure servcies.

Step 8: Token Based Authentication
Token based authentication is used for authorization of ArcGIS Server Services via the JavaScript API.  You have two options:  1. Create a token via the Token generation page. 2. Create a token Dynamically

Option 1. Create a token via the Token generation page
After you turn on security for your ArcGIS Server installation, you will have access to a token generation page. http://<servername/ArcGIS/Tokens/ gettoken.html (You can also get to this page from the REST interface.) Type in a valid user name/password and it will return a token value.  

Change the http reference in the proxy.config to https. Copy  and paste the token into the service url references in your proxy.config file.
Sample from ESRI's Help:
<serverUrl url="https://www.example.com/arcgis/rest/services/MyMapSecureService/MapServer" matchAll="false"token="5fFo4%2fI4Tv8IGSqSYbpUNORRD%2fYxXMSPo6NEHNNGMpt9CMknpXIjEVqYGm3uuQnU" ></serverUrl>

You will notice on the token generation page that by default this token is only good for 10 days. You can change this if needed in the ArcGIS Server Manager. Optionally, you can set up your services as done below.

Option 2. Create a token dynamically:
If you wish to create tokens dynamically, you will need to download a new proxy.ashx page.

We posted a question on ESRI's users forums about this setup. Thang Le from ESRI Support, provided us with the new proxy file. You can download it from the user forums here:
http://forums.esri.com/Thread.asp?c=158&f=2396&t=297001#926770

After you download the zip file, replace your existing proxy.ashx page with the new one. Then, you will need to update your server url references in your proxy.config file. Change the http reference to https. Add the following new attributes:
dynamicToken="true"
host=""
userName=""
password=""