Skip to main content

age-oauth

age-oauth is a convenience package which makes it easier for script users to interact with 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. age-oauth supports the storage of multiple connections - this could be different scopes on the same Portal, or multiple Portals, or a combination of the two. Moreover, multiple connections can be used in any automation by simply calling them by their storage label.

Install

Minimal (fine if you're installing into an ArcGIS Pro conda environment, e.g. arcgispro-py3 or clones):

python -m pip install age-oauth

Full dependencies (installs arcgis and arcgis-mapping):

python -m pip install "age-oauth[full]"

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. There are two paths that age-oauth supports:

authentication type use when OAuth flow
user access assets as yourself auth code + refresh token
application access assets as an application client credentials

In either case, you'll need:

  • the Portal root URL (e.g., https://somwhere.com/portal)
  • OAuth2 client ID
  • OAuth2 client secret

For user authentication you are going to need an out-of-band URI for redirect when you create the credentials in ArcGIS Enterprise, if you're not creating a web app with a server:

urn:ietf:wg:oauth:2.0:oob

For application authentication no user redirect or browser challenge is required. Depending on the ArcGIS Enterprise config, you might need to supply the HTTP referer associated with the application. If it's just a script with no web server, just use https:\\localhost.

Step 0.1: PERMISSIONS

Permissions matter - app credentials can be configured with application permissions, or depending on Portal configuration and the privileges of the creating user, it could be set to impersonate the user. Please verify the permissions you give the application in ArcGIS Enterprise and square this all away with your cybersecurity folks before using it for unattended automation. You've been warned!

Step 1: Add a connection

Run:

age-oauth connections add

You'll be prompted for the connection settings, including whether the connection authenticates as a user or as an application.

Connections are given a friendly label so scripts can refer to them without embedding portal URLs, client IDs, secrets, or tokens.

Step 1.a: Add the Portal non-interactively

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

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

If your ArcGIS Enterprise uses a private CA, you can pass the CA's path to --verify-ssl instead.

Assuming an application credential, it would be done like this:

age-oauth connections add `
  --label "some app" `
  --portal "https://somewhere.com/portal" `
  --auth-type app `
  --referer "https://localhost" `
  --verify-ssl true `
  --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). We'll use a user auth type for example - application auth types are handled in the same way, except without the browser challenge.

age-oauth login --connection "some user"

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 "some user"

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="some user")

# 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.

Rotation of refresh_token for user access

While calling the library programmatically will automatically update the refresh_token associated with the active connection automatically (3 day duration), users or admins can also call it interactively.

age-oauth token --rotate-refresh-token --portal <portal label>

If the refresh_token is still good, the command does nothing.

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.

Metadata

Release files for age-oauth 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for age-oauth 0.2.0
File Size Uploaded Provenance Actions
age_oauth-0.2.0.tar.gz 37.4 kB With provenance Details for age_oauth-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for age-oauth 0.2.0
File Interpreter ABI Platform Actions
age_oauth-0.2.0-py3-none-any.whl Python 3 none any Details for age_oauth-0.2.0-py3-none-any.whl

Total release size: 74.6 kB

Release files / age_oauth-0.2.0.tar.gz

Download URL age_oauth-0.2.0.tar.gz
Size 37.4 kB
Tags Source
SHA-256 checksum
How to use checksums
83556259533f9ad708421197e8f52015298caec90701e4742077dd582cd1302a
BLAKE2b-256 checksum
How to use checksums
e03336fb35d9fb107cb0eaa0b7c25ef5e11672e6784fa42a39494c3f7fc22fd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.

Transparency log

Release files / age_oauth-0.2.0-py3-none-any.whl

Download URL age_oauth-0.2.0-py3-none-any.whl
Size 37.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e4581d6c5a22cde16ff7898b16bbe4e8c972f1f2aeb173d569a91e9cf3c0db2
BLAKE2b-256 checksum
How to use checksums
944c177878941a259bc819d40a84f418bd65bbeea1e22d7101be64216a520af2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.

Transparency log

Security for age-oauth 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for age_oauth-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page