diff --git a/CHANGELOG.md b/CHANGELOG.md index bc892679..ab262122 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) ## [Unreleased] +- Add authentication to User Guide documentation. ([#763](https://github.com/nsidc/earthaccess/pull/763)) ([@andypbarrett](https://github.com/andypbarrett)) + ### Changed - Use built-in `assert` statements instead of `unittest` assertions in diff --git a/docs/user_guide/authenticate.md b/docs/user_guide/authenticate.md index ea6ce469..37e71648 100644 --- a/docs/user_guide/authenticate.md +++ b/docs/user_guide/authenticate.md @@ -1,11 +1,146 @@ # Authentication -Introduces the `earthaccess.login` method for managing Earthdata Login and cloud credentials. +You can use `earthaccess` to search for datasets and data without needing to log in. +However, to access (download or stream) NASA Earth science data, whether from one of the NASA +Distributed Active Archive Centers (DAACs) or from NASA Earthdata Cloud, you need +an Earthdata Login account. You can register for a free Earthdata Login (EDL) account [here](https://urs.earthdata.nasa.gov/). -!!! note "This Page is a Work in Progress" +Once you have an Earthdata Login account, you may use the `earthaccess.login` method to manage Earthdata Login credentials and, when you are working with cloud-hosted data, cloud credentials. - We are reorganizing and updating the documentation, so not all pages are complete. If you are looking for information about authenticating using earthaccess see the - How-Tos and Tutorials in links below. +`earthaccess.login` offers three methods of logging in (or authenticating) using EDL: - * [Quick start](../quick-start.md) - * [How-To Authenticate with earthaccess](../howto/authenticate.md) +* [a manual login method](#login-manually), where you enter EDL username and password manually +* an automatic login method using EDL credentials stored in a [`.netrc`](#login-using-a-netrc) file +* an automatic login method using EDL credentials stored in [environment variables](#login-using-environment-variables). + +By default, `earthaccess.login()` will look for a `.netrc` or environment variables first. If neither of these are found, it will prompt you to enter your username and password. The three methods are described in detail below. + +`earthaccess.login` can also be used to login to [different endpoints](#accessing-different-endpoints) and [get S3 credentials](#using-earthaccess-to-get-credentials). + +## Login Manually + +If you have not created a `.netrc` file or `EARTHDATA_USERNAME` and `EARTHDATA_PASSWORD` environment variables, you can use the following approach to login. + +``` +>>> import earthaccess + +>>> auth = earthaccess.login() +Enter your Earthdata Login username: your_username +Enter your Earthdata password: +``` + +You don't need to assign the result of `earthaccess.login()` to a variable but doing so enables access session information. These are discussed in [Accessing Session Information](). + +Setting `strategy=interactive` will force a manual login. + +## Login using a `.netrc` + +### Creating a `.netrc` file + +#### Using `earthaccess.login` to create a `.netrc` file + +You can use `earthaccess.login` to create a `.netrc` for you. +``` +earthaccess.login(persist=True) +``` +You will then be prompted for your Earthdata Login username and password. A `.netrc` (or `_netrc`) file will be created automatically. + +#### Manually creating a `.netrc` file for Earthdata Login Credentials + +=== "MacOS" + Type the following on your command line, replacing `` and `` with your + Earthdata Login credentials. + + ``` + echo "machine urs.earthdata.nasa.gov login password " >> $HOME/.netrc + chmod 600 $HOME/.netrc + ``` + +=== "Linux" + Type the following on your command line, replacing `` and `` with your + Earthdata Login credentials. + + ``` + echo "machine urs.earthdata.nasa.gov login password " >> $HOME/.netrc + chmod 600 $HOME/.netrc + ``` + +=== "Windows" + In a `CMD` session, create a `%HOME%` environment variable. The following line + creates `%HOME%` from the path in `%USERPROFILE%`, which looks something like + `C:\Users\"username"`. + ``` + setx HOME %USERPROFILE% + ``` + You now need to create a `_netrc` file in `%HOME%`. + ``` + echo "machine urs.earthdata.nasa.gov login password " >> %HOME%\_netrc + ``` + +## Login using environment variables + +Alternatively, Earthdata Login credentials can be created as environment variables `EARTHDATA_USERNAME` and `EARTHDATA_PASSWORD`. + +=== "MacOS" + If you want to set the environment variables for the current shell session, type the following on the command line. + ``` + export EARTHDATA_USERNAME="username" + export EARTHDATA_PASSWORD="password" + ``` + If you want to set these environmental variables permanently, add these two lines to your `.profile` file. + + +=== "Linux" + If you want to set the environment variables for the current shell session, type the following on the command line. + ``` + export EARTHDATA_USERNAME="username" + export EARTHDATA_PASSWORD="password" + ``` + If you want to set these environmental variables permanently, add these two lines to your `.bashrc` file. + +=== "Windows" + To set the environment variables for the current `CMD` session, type the following: + ``` + setx EARTHDATA_USERNAME "username" + setx EARTHDATA_PASSWORD "password" + ``` + To set these environmental variables permanantly + 1. Open the start menu. + 2. Search for the "Advanced System Settings" control panel and click on it. + 3. Click on the "Environment Variables" button toward the bottom of the screen. + 4. Follow the prompts to add the variable to the user table. + + +## Accessing different endpoints + +### Earthdata User Acceptance Testing (UAT) endpoint + +If your EDL account is authorized to access the User Acceptance Testing (UAT) system, +you can set earthaccess to work with its EDL and CMR endpoints +by setting the `system` argument at login, as follows: + +```python +import earthaccess + +earthaccess.login(system=earthaccess.UAT) + +``` + +## Using `earthaccess` to get S3 credentials + +`earthaccess.login` is a very convenient way to manage and provide Earthdata Login credentials. `earthaccess.login` can also be used to obtain S3 credentials to access NASA Earthdata Cloud. If you use `earthaccess` to access data in the cloud, you do not have to use this option, `earthaccess` handles this. However, if you are using other packages, such as `h5coro`, `earthaccess` can save a lot of time. + +``` +import earthaccess +import xarray as xr +import h5coro + +auth = earthaccess.login() +s3_credentials = auth.get_s3_credentials(daac="NSIDC") + +s3url_atl23 = 'nsidc-cumulus-prod-protected/ATLAS/ATL23/001/2023/03/' \ + '01/ATL23_20230401000000_10761801_001_01.h5' +ds = xr.open_dataset(s3url_atl23, engine='h5coro', + group='/mid_latitude/beam_1', + credentials=s3_credentials) +``` \ No newline at end of file