When starting working with any new package, there is always a learning curve, and I am trying to make ArcREST easy and fun to use. So here is my first of many ArcREST posts on how to use this package to meet your Esri REST API use cases.
This post will focus on the most basic thing, authentication. Authentication is the most basic idea to understand when working with ArcGIS Online, ArcGIS Server, or ArcGIS Portal. It identifies who you are, and what you are allowed to do. Not all operations require authentication, but it's good to understand the token based security model and how it applies to you ArcGIS stack.
A quick blurb from the ArcGIS help describes what token security does:
ArcGIS Server provides a proprietary token-based authentication mechanism where users can authenticate themselves by providing a token instead of a user name and password. An ArcGIS token is a string of encrypted information that contains the user's name, the token expiration time, and some proprietary information. To obtain a token, a user provides a valid user name and password. ArcGIS Server verifies the supplied credentials and issues a token. The user presents this token whenever accessing a secured resource.
Before ArcREST, I you probably had to write this function out a lot:
import urllib
import urllib2
import httplib
import time
import json
import contextlib
def submit_request(request):
""" Returns the response from an HTTP request in json format."""
with contextlib.closing(urllib2.urlopen(request)) as response:
job_info = json.load(response)
return job_info
def get_token(portal_url, username, password):
""" Returns an authentication token for use in ArcGIS Online."""
# Set the username and password parameters before
# getting the token.
#
params = {"username": username,
"password": password,
"referer": "http://www.arcgis.com",
"f": "json"}
token_url = "{}/generateToken".format(portal_url)
request = urllib2.Request(token_url, urllib.urlencode(params))
token_response = submit_request(request)
if "token" in token_response:
print("Getting token...")
token = token_response.get("token")
return token
else:
# Request for token must be made through HTTPS.
#
if "error" in token_response:
error_mess = token_response.get("error", {}).get("message")
if "This request needs to be made over https." in error_mess:
token_url = token_url.replace("http://", "https://")
token = get_token(token_url, username, password)
return token
else:
raise Exception("Portal error: {} ".format(error_mess))
It is lots of code just to gain access. As a user/developer you have not even begun to work on your actual workflow of what you need.
So there has to be an easier way?
Well there is! ArcREST supports three main forms of token based security in the form of classes.
- PortalTokenSecurityHandler - this allows access to ArcGIS Portal Site
- AGOLTokenSecurityHandler - this generates a token for ArcGIS Online
- AGSTokenSecurityHandler - this generates a token for ArcGIS Server Sites
Why should I use this?
- allows for cleaner code
- pass username/password once in your code
- built in proxy support
- handles token expiration automatically
#3 is a biggie, at least in my eyes. For long running tasks, there is a chance, depending on your expiration time, that your token might fail you because it is too old. The SecurityHandler classes automatically handle the expiration for you, and regenerate new tokens as needed.
Examples of creating Securityhandler objects:
1. Creating an ArcGIS Server Security Handler
import arcrest
if __name__ == "__main__":
token_url = "http://mysite.com:6080/arcgis/admin/generateToken"
username = "username"
password = "password"
sh = arcrest.AGSTokenSecurityHandler(username=username,
password=password,
token_url=token_url)
2. Creating an ArcGIS Online Security Handler
import arcrest
if __name__ == "__main__":
username = "< username >"
pw = "< password >"
proxy_url = None
proxy_port = None
sh = arcrest.AGOLTokenSecurityHandler(username, password=pw)
3. Creating an ArcGIS for Portal Security Handler
import arcrest
if __name__ == "__main__":
username = "< username >"
pw = "< password >"
tokenUrl = "https://mysite.com/portal/sharing/rest/generateToken"
org_url = "https://mysite.com/portal/sharing/rest"
sh = arcrest.PortalTokenSecurityHandler(username=username,
password=pw,
org_url=org_url,
token_url=tokenUrl)
In each example, it shows how to generate the token handlers. You then can pass the security handlers objects onto other functions like arcrest.manageorg.Administration(), which will allow administrators to perform operations to manage a portal or AGOL site.
Hope this helps!
Please download ArcREST
here (http://www.github.com/Esri/ArcREST)
If you use ArcREST, help us out and post comments in the issues sections. We are always trying to make it better. If you think you can make it better, fork it and submit a pull request!
