EarthScope SDK Authentication

EarthScope SDK Authentication#

The EarthScope SDK provides multiple authentication methods to suit different use cases. Once refreshable credentials are available, the SDK will transparently handle access token refresh on your behalf.

CLI-based Authentication (Same Host)#

If you have the EarthScope CLI installed on the same host that is running your application, you can use the CLI to authenticate. The CLI shares credentials and configuration with the SDK when running on the same host.

# Log in using the CLI
$ es login
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://login.earthscope.org/activate?user_code=ABCD-EFGH

Successful login! Access token expires at 2024-12-27 18:50:37+00:00

After logging in, the SDK will automatically find and use your credentials.

Bootstrapping Authentication on Remote Hosts#

When your workload runs on different hosts than your main workstation (e.g., in containers or on remote servers), you can still use the EarthScope CLI to authenticate, then pass your refresh token to the remote environment(s).

Step 1: Log in on Primary Workstation#

First, log in on your primary workstation using the CLI:

$ es login

Step 2: Retrieve Refresh Token#

Get your refresh token from the CLI:

$ es user get-refresh-token
<your-refresh-token>

Warning

Your refresh token is a sensitive credential. Anyone with access to it can use it to continually retrieve new access tokens on your behalf. Treat it like a password and never commit it to version control.

Step 3: Configure Remote Hosts#

Pass the refresh token to your remote hosts using one of these methods:

  1. Environment Variable (easiest):

    export ES_OAUTH2__REFRESH_TOKEN="<your-refresh-token>"

  2. Configuration File:

    # ~/.earthscope/config.toml
[profile.default]
oauth2.refresh_token = "<your-refresh-token>"

  3. Docker Environment:

    # docker-compose.yml
services:
  app:
    environment:
      - ES_OAUTH2__REFRESH_TOKEN=<your-refresh-token>

Token Management#

The SDK automatically handles token refresh and management. Here’s what happens behind the scenes:

  1. The SDK checks for an existing access token

  2. If the token is expired or about to expire, it uses the refresh token to get a new one

  3. The new tokens are automatically saved for future use

Security Best Practices#

  1. Never commit tokens to version control

    • Use environment variables or secure secret management systems

    • Add token files to .gitignore

  2. Rotate tokens regularly

    • Periodically generate new refresh tokens

    • Revoke old tokens when no longer needed

  3. Use appropriate token storage

    • For development: local configuration files

    • For production: environment variables or secret management systems

Contents