age-oauth 0.1.6

ArcGIS Enterprise OAuth helper with per user token cache.

age-oauth

age-oauth is a convenience package which makes it easier for script users to interact with an ArcGIS Enterprise by simplifying the OAuth 2.0 process, and eliminating the need (and bad security practice) of having to store username/passwords in your scripts.

Install

NOTE: You must have arcgis installed in your desired Python environment. If you want the full capabilities of ArcGIS API for Python, go ahead and install arcgis-mapping too. If you're working with ArcGIS Pro, these are already available to you in arcgispro-py3 and any cloned environments. Otherwise grab them from either Esri's conda channel (recommended):

conda install -c esri arcgis arcgis-mapping

or pip:

pip install arcgis arcgis-mapping

Then Grab the latest .whl.

In your desired Python environment, do:

pip install <path to wheel file> or pip install --user <path to wheel file>

Usage

Step 0: Prereqs

This README presumes you already have the needed permissions to have created a valid set of OAuth 2.0 app/developer tokens on a target ArcGIS Enterprise system. You should have ready:

• the Portal root URL (e.g., https://somwhere.com/portal)
• OAuth2 client ID
• OAuth2 client secret
• The app's Redirect URI set to urn:ietf:wg:oauth:2.0:oob (Esri's default out of band URI)

Step 1: Add a Portal to your local store

Run:

age-oauth connections add

You'll be prompted for the following:

Connection label:        <short, plain language name to identify portal, no spaces>
Portal URL:              https://somewhere.com/portal
Verify SSL:              false, true, or path to custom CA cert
OAuth Client ID:         <your client ID>
OAuth Client Secret:     <your client secret>

When it's done, you'll see:

[OK] Created connection: my_portal

Step 1.a: Add the Portal non-interactively

You can also add the Portal non-interactively. Assuming a PowerShell environment:

age-oauth connections add `
  --label "Prod" `
  --portal "https://somewhere.com/portal" `
  --verify-ssl false `
  --client-id "client_id_value" `
  --client-secret "client_secret_value"

Step 2: Authenticate / Onboard

Now we'll authenticate for the first time (interactively, from CLI)

age-oauth login --connection my_portal

You'll see:

Opening browser for ArcGIS Enterprise OAuth sign-in...

A browser will open to your Portal login screen. You need to:

1. Sign in
2. Portal displays an authorization code
3. Copy the code
4. Paste it back into the terminal where you are being prompted for it

age-oauth will swap the authorization code for an access token, a refresh token, and an expiration timestamp. This is then securely stored in your user profile. If all is successful, you'll see:

New access_token acquired!  Expires in: 1:00:00
Token is for user: your.username

Step 3: Confirm authentication

To verify, do:

age-oauth whoami --connection my_portal

You should see:

your.username

Your OAuth credentials are now onboarded and you can proceed to use it programmatically.

Step 4: Programmatic use

Now, you can use it in Python:

from age_oauth import get_gis

gis = get_gis(connection="my_portal")

# verify
print(gis.properties.portalName)
print(gis.users.me.username)

No username/passwords, no tokens, no PKI decryption in your scripts. age-oauth handles negotiation and refresh automatically.

Storage

Portal profiles are stored per-user under your OS home (profile) directory. Nothing is stored globally:

Windows

%APPDATA%\age_oauth\

Each connection contains the following:

connections/
    my_portal_<uuid>/
        .env         # OAuth settings and tokens
        meta.json    # metadata

Why does this exist?

It is tempting to write scripts like:

gis = GIS("https://my-portal.com/portal", "username", "password")

# or

gis = GIS("https://my-portal.com/portal", token="abcdef12345abcdef12345abcdef...")

Or do any number of other sketchy things like -

• usernames/passwords in .py or sidecar files
• decrypt PKI client certs into unencrypted, plain-text .pem files
• copy static access tokens from a browser
• paste your API keys right into scripts

All of these practices create both security and maintainability problems, with compromise at worst and increased technical debt at best. In a secure setting, we're going for:

• credentials that can be revoked
• clear ownership of access
• clear expiration policy
• centralized control

This is exactly what the OAuth workflow gives you when it's properly used. You have to authenticate via Portal. A short-lived access_token is issued (expiration and rotation policy). A longer-lived refresh_token can renew access automatically once the "app" is authorized. These tokens can then be revoked via Portal (centralization). So while nothing's perfect, this workflow aligns much better with typical enterprise security expectations.

age-oauth is designed to make the more secure way also the more convenient way. It will give you:

• A per-user connection store to manage multiple Portal connections
• OAuth client configuration per Portal
• Automatic token refresh
• A simple, injected arcgis.gis.GIS class object instantiated via age_oauth.get_gis()

But why not just use API keys?

ArcGIS Enterprise developer API keys are useful, but they have short lifetimes and require manual renewal. This introduces friction into automations you may need to run under your human-user persona. OAuth supports refresh tokens that can be reused indefinitely to get new access tokens. Going through the up-front setup to establish OAuth client access pays off in the long run by giving you way cleaner scripts that are:

• more easily maintained,
• can be passed around without fear of accidentally leaking credentials,
• better aligned with enterprise security and therefore help everyone sleep better at night.