Working with different authentication schemes

The GIS class in the ArcGIS API for Python supports several classes of users with varied authentication schemes:

• Anonymous users
• Built-in users
  • Enterprise identity store
  • Web-tier authentication with LDAP
  • Portal-tier authentication with Active Directory
  • Portal-tier authentication with LDAP
  • Web-tier authentication secured with PKI
  • Web-tier authentication secured with IWA
• User authentication with OAuth 2.0
• Connecting through ArcGIS Pro
• Storing your credentials locally

The GIS class supports constructing a GIS object given an url and user credentials to ArcGIS Online or an ArcGIS Enterprise instance. User credentials can be passed in using username / password pair, or using a key_file / cert_file pair (in case of PKI). The GIS class also supports built-in users, LDAP, PKI and anonymous access.

If no url is provided, ArcGIS Online is used. If username / password or key / cert files are not provided, anonymous access is used. Additionally, the script can leverage the ArcGIS Pro app to login to the portal and their scripts can use whichever Portal is currently active.

The examples below demonstrate how to connect using these different authentication schemes:

# import the GIS class in gis module
from arcgis.gis import GIS

Anonymous users

You can make use of the Python API as anonymous user. However, tasks that you can accomplish are fewer, as you would not be able to create or modify content or perform any analysis tasks. As an anonymous user, you can query and view publicly shared maps and layers.

Connect to ArcGIS Online as an anonymous user

print("ArcGIS Online as anonymous user")    
gis = GIS()
print("Logged in as anonymous user to " + gis.properties.portalName)

ArcGIS Online as anonymous user
Logged in as anonymous user to ArcGIS Online

Connect to your ArcGIS Enterprise as an anonymous user

If your ArcGIS Enterprise allows anonymous usage, you can connect to it as such by specifying the URL and leaving the username and password parameters empty.

Note: If your enterprise is configured with IWA authentication, and if you are running this on a Windows computer, you might get automatically signed in.

gis = GIS("https://pythonapi.playground.esri.com/portal")
print("Logged in as anonymous user to " + gis.properties.portalName)

Logged in as anonymous user to Portal for ArcGIS

Authenticated Connections

Retrieving the token

Most Web GIS users will connect using a method to authenticate and authorize use of the Web GIS. Once authenticated, it can often times be necessary or desirable to retrieve the token from the authenticated GIS. The code below documents how to get the token object:

token = gis.session.auth.token

note: See the Module Contents documentation for type of authentication object returned depending upon which authentication schema is being used.

Built-in users

Both ArcGIS Online and ArcGIS Enterprise come preconfigured with a built-in identity store, so you can easily create accounts and groups in your portal. When signing in to such accounts, specify your username and password, as you type them into the portal website.

Connect to ArcGIS Online using a built-in account

print("ArcGIS Online Org account")    
gis = GIS('home')
print("Logged in as " + str(gis.properties.user.username))

ArcGIS Online Org account
Logged in as arcgis_python

Connect to ArcGIS Enterprise using a built-in account

print("Portal for ArcGIS as a built in user")
gis = GIS("https://portalname.domain.com/webadapter_name", "sharinguser", "password")
print("Logged in as: " + gis.properties.user.username)

Portal for ArcGIS as a built in users
Logged in as sharinguser

Enterprise identity store

ArcGIS Online and Enterprise is designed so you can use your enterprise accounts and groups to control access to your ArcGIS organization.

Web-tier authentication with LDAP

print("\n\nBasic Authentication with LDAP")    
ldapbasic = GIS("https://portalname.domain.com/webadapter_name", "amy", "password")
print("Logged in as: " + ldapbasic.properties.user.username)

Basic Authentication with LDAP
Logged in as: amy

Portal-tier authentication with Active Directory

When connecting using an enterprise user account from an Active Directory, specify your username as domain\\username

print("\n\nPortal-tier Authentication with LDAP - enterprise user")
gisldap = GIS("https://portalname.domain.com/webadapter_name", "AVWORLD\\Publisher", "password")
print("Logged in as: " + gisldap.properties.user.username)

Portal-tier Authentication with LDAP - enterprise user
Logged in as: Publisher@AVWORLD

Portal-tier authentication with LDAP

When connecting using an enterprise user account from LDAP, specify your username and password as usual

print("\n\nPortal-tier Authentication with LDAP - builtin user")    
gisldap = GIS("https://portalname.domain.com/webadapter_name", "sharing1", "password")
print("Logged in as: " + gisldap.properties.user.username)

Portal-tier Authentication with LDAP - builtin user
Logged in as: sharing1

Web-tier authentication secured with PKI

You can also use two different methods of connecting to a PKI protected ArcGIS Enterprise.

First, you can specify a local PEM-encoded certificate and a 'key' file to use as client side certificate, when logging into your ArcGIS Enterprise using PKI-based client certificate authentication.

print("\n\nPKI with key and cert files")  
gis = GIS("https://portalname.domain.com/webcontext", 
          key_file="C:\\path\\to\\key.pem",
          cert_file="C:\\path\\to\\cert.pem")
print("Logged in as: " + gis.properties.user.username)

PKI with key and cert files
Logged in as: username@DOMAIN

Second, you can use a PKCS12 formatted certificate file (for example .pfx or .p12) and password when logging into your ArcGIS Enterprise using PKI-based client certificate authentication.

print("\n\nPKI with PFX file and password")  
gis = GIS("https://portalname.domain.com/webcontext", 
          cert_file="C:\\path\\to\\mycert.pfx",
          password="secret.password")
print("Logged in as: " + gis.properties.user.username)

PKI with PFX file and password
Logged in as: BMAJOR@ESRI.COM

Web-tier authentication secured with IWA

If your Enterprise is configured with the ArcGIS Portal WebAdaptor for IIS on Microsoft's IIS Web Server and enabled for Windows Authentication with Kerberos or NTLM providers, you can omit passing in the username and password. The ArcGIS API for Python is able to figure out when the GIS is using Windows authentication and picks the login credentials from the currently running process providing a seamless and secure login experience.

Note: SAML-compliant identity providers configured to use Kerberos or NTLM will not create this same seamless login experience.

Windows authentication only works on the Windows OS and requires pywin32 and kerberos-sspi python packages.

print("\n\nIntegrated Windows Authentication using NTLM or Kerberos")  
gis = GIS("https://portalname.domain.com/webcontext")
print("Logged in as: " + gis.properties.user.username)

Integrated Windows Authentication using NTLM or Kerberos
Logged in as: username@DOMAIN

User authentication with OAuth 2.0

The ArcGIS Python API supports OAuth 2.0 as an authentication method, and acts as a serverless native application when using OAuth 2.0 authorization with ArcGIS.

To use this mode of authorization, you need a client id. If you already have a client id, you can skip the following section.

Obtaining a client id

The steps below show how a client id can be obtained by registering a new application with your GIS. Only one client id is required, so if your GIS has one already, you may use it instead of creating a new application.

• Log in to your ArcGIS Online or ArcGIS Enterprise organization.
• Go to the Content tab.
• Click 'New item', then select 'Application'.
• On the 'New item' dialog, select 'Other application' and click 'Next'.
• Type in a title for the application item. Optionally, specify the folder, tags, and summary.
• Click 'Save' to add the item.
• On the item details page of this newly created application, browse to the Credentials section and find the Client ID. The string listed is the value that you will pass in as the client_id parameter when creating the GIS object.

You can then log on to your org using the Python API using the code shown below:

Interactive Login Experience

This uses interactive sign-in experience: you would be redirected to your organization's sign-in page using the configured identity provider. Upon signing in, you would get a code that you can paste back to complete the sign-in process:

gis = GIS("https://pythonapi.playground.esri.com/portal", client_id='f8cRxbP3NO8bf9ag')
print("Successfully logged in as: " + gis.properties.user.username)

Please sign in to your GIS and paste the code that is obtained below.
If a web browser does not automatically open, please navigate to the URL below yourself instead.
Opening web browser to navigate to: https://pythonapi.playground.esri.com/portal/sharing/rest/oauth2/authorize?client_id=f8cRxbP3NO8bf9ag&response_type=code&expiration=-1&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
Enter code obtained on signing in using SAML: ········
Successfully logged in as: arcgis_python

Non-Interactive Login Experience

The recommended suggestion for non-interactive login scripts is to use the built-in identity provider instead of SAML.

Connecting through ArcGIS Pro

It is often useful to write scripts that work against the active portal in the ArcGIS Pro app.

Using the pro authentication scheme, scripts can create an instance of the GIS class representing the active portal in ArcGIS Pro without requiring the user to pass their credentials. In this mode, users can leverage the Pro app to login to the portal and their scripts can use whichever Portal is currently active. This mode can also serve as a bridge for users with advanced authentication scenarios like IWA using NTLM or Kerberos or Smart Card where signing in with credentials may not be possible or desirable.

NOTE: When using a Named User license to license ArcGIS Pro, unless the Sign me in automatically checkbox is selected when signing into the licensing portal or ArcGIS Pro has been licensed for offline use, ArcGIS Pro should be installed and concurrently running on the machine that executes the script for authentication to succeed. When selecting Sign me in automatically, ArcGIS Pro can remain closed for 2 weeks by default before the portal token expires. See here for details on configuring token settings.

print("\n\nActive Portal in ArcGIS Pro")  
gis = GIS("pro")

Active Portal in ArcGIS Pro

Protecting your credentials

When sharing your notebooks with other users or if you are storing it in a public location you want to obfuscate your credentials stored in the notebook. You can do so by simply not providing the password. The Python API uses the getpass module internally and would request your password in such a way that your keystrokes would not be printed on the screen.

gis = GIS("https://pythonapi.playground.esri.com/portal", username='arcgis_python')
print("Successfully logged in as: " + gis.properties.user.username)

Enter password: ········
Successfully logged in as: arcgis_python

This halts execution of the cell and waits for the user to input text into text box. All keystrokes are masked with an asterisk or similar character. Upon entry, execution resumes. The value entered by the user can be stored in a variable as shown in the code above.

This technique could be used with any authentication scheme that requires a password. You can choose to mask the username as well. The getpass() function can be used in a standalone Python script as well. When doing so, remember, the script has to be run interactively as it expects input from user at runtime.

Storing your credentials locally

If you are signing in frequently to a particular GIS and would like to store the credentials locally on your computer, then you could do so using the profile parameter of your GIS.

Persistent profiles for the GIS can be created by giving the GIS authorization credentials and specifying a profile name. The profile stores all of the authorization credentials (except the password) in the user’s home directory in an unencrypted config file named .arcgisprofile. The profile securely stores the password in an OS specific password manager through the keyring python module. (Note: Linux systems may need additional software installed and configured for proper security) Once a profile has been saved, passing the profile parameter by itself uses the authorization credentials saved in the configuration file/password manager by that profile name. Multiple profiles can be created and used in parallel.

#Define 2 different profiles for two different urls
playground_gis = GIS(url="https://pythonapi.playground.esri.com/portal", username='arcgis_python', password='amazing_arcgis_123',
                     profile='python_playground_prof')
agol_gis = GIS('home')
print("profile defined for {}".format(playground_gis))
print("profile defined for {}".format(agol_gis))

profile defined for GIS @ https://pythonapi.playground.esri.com/portal
profile defined for GIS @ https://geosaurus.maps.arcgis.com

To sign in during a different session, simply specify the profile file name. You can work with any number of connections concurrently, as the authentication credentials stored for each profile will be automatically loaded at runtime.

def print_profile_info(gis):
    print("Successfully logged into '{}' via the '{}' user".format(
           gis.properties.portalHostname,
           gis.properties.user.username)) 

playground_gis = GIS(profile='python_playground_prof')
print_profile_info(playground_gis)

agol_gis = GIS(profile="AGOL_prof")
print_profile_info(agol_gis)

Successfully logged into 'pythonapi.playground.esri.com/portal' via the 'arcgis_python' user
Successfully logged into 'www.arcgis.com' via the 'arcgis_python' user

Persistent profiles details

Persistent profiles will store the any combination of the following GIS() parameters in the unencrypted .arcgisprofile file:

• url
• username
• key_file
• cert_file
• client_id

The password parameter (if specified) will be securely stored through the keyring module. This means that, behind the scenes, your password is retrieved at run-time from an operating system specific password store.

Windows

On Windows, your password will be stored in the Windows Credentials Manager. You can access the Credentials Manager to manage stored passwords by selecting:

Start > Control Panel > User Accounts > Credential Manager > Windows Credentials > Generic Credentials

If you had a password stored through a profile named "profile_example", you would see this entry under "arcgis_python_api_profile_passwords":

Notice that in the Windows Credentials Manager's view, the profile name "profile_example" is filed under "User name".

macOS

On macOS, your password will be stored in Keychain Access. You can access the Keychain to manage stored passwords by selecting:

Applications > Utilities > Keychain Access > Passwords > "arcgis_python_api_profile_passwords"

Linux

On Linux, you may need additional software installed and configured to securely store passwords with persistent profiles. The Python executable running must have access over dbus to any of the following:

• Freedesktop Secret Service / secretstorage for a GNOME environment
• KWallet for a KDE environment
• A custom configuration of the previous software packages and gnome-key-ring for a headless environment.

Conda cannot use the dbus python module required for this, so it is best to install the arcgis package through the system-level python and pip. Read more about how to configure keyring on linux on the keyring doc page.