Add support for authentication with Earthdata login token only

[kgrimes2]

This change addresses the use case of authenticating with an existing Earthdata Login token (#484). Users may set the EARTHDATA_TOKEN environment variable before calling auth.login(). If a token is provided, only it is used; that is, any provided username and password are ignored.

Note that this method does not support the "interactive" login strategy, yet (but that can be added if there's interest).

Pull Request (PR) draft checklist - click to expand

• Please review our
  contributing documentation
  before getting started.
• Populate a descriptive title. For example, instead of "Updated README.md", use a
  title such as "Add testing details to the contributor section of the README".
  Example PRs: #763
• Populate the body of the pull request with:
  • A clear description of the change you are proposing.
  • Links to any issues resolved by this PR with text in the PR description, for
    example closes #1. See
    GitHub docs - Linking a pull request to an issue.
• Update CHANGELOG.md with details about your change in a section titled
  ## Unreleased. If such a section does not exist, please create one. Follow
  Common Changelog for your additions.
  Example PRs: #763
• Update the documentation and/or the README.md with details of changes to the
  earthaccess interface, if any. Consider new environment variables, function names,
  decorators, etc.

Click the "Ready for review" button at the bottom of the "Conversation" tab in GitHub
once these requirements are fulfilled. Don't worry if you see any test failures in
GitHub at this point!

Pull Request (PR) merge checklist - click to expand

Please do your best to complete these requirements! If you need help with any of these
requirements, you can ping the @nsidc/earthaccess-support team in a comment and we
will help you out!

• Add unit tests for any new features.
• Apply formatting and linting autofixes. You can add a GitHub comment in this Pull
  Request containing "pre-commit.ci autofix" to automate this.
• Ensure all automated PR checks (seen at the bottom of the "conversation" tab) pass.
• Get at least one approving review.

---

📚 Documentation preview 📚: https://earthaccess--1020.org.readthedocs.build/en/1020/

[github-actions]

👈 Launch a binder notebook on this branch for commit 836982c

I will automatically update this comment whenever this PR is modified

👈 Launch a binder notebook on this branch for commit 1430a59

[betolink]

This is a great contribution @kgrimes2! we were jut working on something similar today, I think we should combine those but your PR probably needs to go first (FIFO 😄 ). Integrations tests will fail because we have no easy way of sharing the default username/password with PRs from forks.

EDIT: I'll open a PR with the work we did today(draft) so you can take what's useful with the idea of eventually merging this one. #1021

[kgrimes2]

@betolink That's awesome! @mfisher87 re-ran one of the integration tests because I ran into the permissions issue you mentioned. When he ran it it failed checking the number of files that got downloaded in one of the tests: https://github.com/nsidc/earthaccess/actions/runs/15286174529/job/42998438063?pr=1020#step:8:442

Looking at the test, I think it may be benign, and just a case where the number of files to download is genuinely 1. The test expects at least 2 files to be downloaded:

earthaccess/tests/integration/test_onprem_download.py

Line 19 in fcb0c22

"granules_sample_size": 2,

but the method that gets a random sample even has a comment that the returned amount might be less than the sample size:

earthaccess/tests/integration/sample.py

Lines 37 to 38 in 310dc44

	Attempt to find only granules smaller or equal to max_granule_size. May return a
	sample smaller than sample_size.

Retrying the integration test may resolve. I'll defer to whoever has permission to merge these PRs on what to do :) Happy to consolidate my work with yours, or vice versa.

[betolink]

I think we should consolidate the changes from the other PR #1021 into this one, the main thing would be to actually use the token to create sessions, the token cannot be used to retrieve the user's profile or their credentials, this means when we use this auth method we'll assume the token works and the flag of authenticated will be set to True. What do you all think? @jhkennedy @danielfromearth

[danielfromearth]

Might there be another way to do a kind of "ping" and check that the token works before setting authenticated to True?

[kgrimes2]

@danielfromearth Looking at the API docs for the EDL API, unfortunately they all seem to require a username and password. I tried using only the bearer token without luck.

We could always make a test query to CMR or something to exercise the token? Like a search request for 0 documents

[chuckwondo]

@danielfromearth Looking at the API docs for the EDL API, unfortunately they all seem to require a username and password. I tried using only the bearer token without luck.

We could always make a test query to CMR or something to exercise the token? Like a search request for 0 documents

Queries don't require credentials, so that won't help. A token is for obtaining S3 credentials via an S3 credentials endpoint, so we would need to choose an arbitrary endpoint and attempt a GET request with a bearer token auth header, without allowing redirect. If the response is a redirect, then the token is invalid.

However, I don't think we should complicate things. As soon as a download is attempted, the user will find out whether or not their token is valid. If not, they should get a 401 response, which we could catch and perhaps rethrow with a more helpful error message for the user, such as, f"Your Earthdata Login user token for {host} is invalid. It may have expired or be for a different host.", where {host} represents whichever system host we're hitting (I don't have the code in front of me, so I can't recall our var that references which system we're hitting, OPS or UAT).