Merge pull request #809 from planetlabs/auth-808

Clarify auth source, CLI only sources from config file, add planet auth store, Auth.write() -> Auth.store()

Author: jreiberkyle

docs/get-started/quick-start-guide.md

@@ -83,8 +83,8 @@ And you can see that the value was stored successfully as an environment variabl
 echo $PL_API_KEY
 ```
 
-!!!note "The API Key environment variable is always used first in the Planet SDK"
-    If you do create a `PL_API_KEY` environment variable, the SDK will use this value. `PL_API_KEY` overrides the value that was retrieved using your Planet login with a call to `planet auth init`. The `planet auth value` call currently does not reflect that `PL_API_KEY` overrides the `auth init` value (this should be fixed in 2.0-beta.1 with [issue 643](https://github.com/planetlabs/planet-client-python/issues/643))
+!!!note "The API Key environment variable is ignored by the CLI but used by the Python library"
+    If you do create a `PL_API_KEY` environment variable, the CLI will be unaffected but the Planet library will use this as the source for authorization instead of the value stored in `planet auth init`.
 
 ## Step 5: Search for Planet Imagery
 

docs/python/sdk-guide.md

@@ -46,15 +46,18 @@ asyncio.run(main())
 
 ## Authenticate with Planet services
 
-There are two steps to managing authentication information, obtaining the
-authentication information from Planet and then managing it for local retrieval
-for authentication purposes.
+A `Session` requires authentication to communicate with Planet services. This
+authentication information is retrieved when a `Session` is created. By default,
+a `Session` obtains authorization from the following sources with order
+indicating priority:
 
-The recommended method for obtaining authentication information is through
-logging in, using `Auth.from_login()` (note: using something like the `getpass`
-module is recommended to ensure your password remains secure). Alternatively,
-the api key can be obtained directly from the Planet account site and then used
-in `Auth.from_key()`.
+1. The environment variable `PL_API_KEY`
+2. The secret file
+
+The SDK provides the `auth.Auth` class for managing authentication information.
+This module can be used to obtain authentication information from username
+and password with `Auth.from_login()`. Additionally, it can be created with
+the API key obtained directly from the Planet account site with `Auth.from_key(<API_KEY>)`.
 
 Once the authentication information is obtained, the most convenient way of
 managing it for local use is to write it to a secret file using `Auth.write()`.
@@ -69,16 +72,15 @@ from planet import Auth
 
 pw = getpass.getpass()
 auth = Auth.from_login('user', 'pw')
-auth.write()
+auth.store()
 
 ```
 
-When a `Session` is created, by default, authentication is read from the secret
-file created with `Auth.write()`. This behavior can be modified by specifying
+The default authentication behavior of the `Session` can be modified by specifying
 `Auth` explicitly using the methods `Auth.from_file()` and `Auth.from_env()`.
 While `Auth.from_key()` and `Auth.from_login` can be used, it is recommended
 that those functions be used in authentication initialization and the
-authentication information be stored using `Auth.write()`.
+authentication information be stored using `Auth.store()`.
 
 The file and environment variable read from can be customized in the
 respective functions. For example, authentication can be read from a custom

planet/auth.py

@@ -25,14 +25,13 @@
 import jwt
 
 from . import http
-from .constants import PLANET_BASE_URL, SECRET_FILE_PATH
+from .constants import ENV_API_KEY, PLANET_BASE_URL, SECRET_FILE_PATH
 from .exceptions import AuthException
 from typing import Optional
 
 LOGGER = logging.getLogger(__name__)
 
 BASE_URL = f'{PLANET_BASE_URL}/v0/auth'
-ENV_API_KEY = 'PL_API_KEY'
 
 AuthType = httpx.Auth
 
@@ -135,9 +134,9 @@ def value(self):
     def to_dict(self) -> dict:
         pass
 
-    def write(self,
+    def store(self,
               filename: Optional[typing.Union[str, pathlib.Path]] = None):
-        '''Write authentication information.
+        '''Store authentication information in secret file.
 
         Parameters:
             filename: Alternate path for the planet secret file.

planet/cli/auth.py

@@ -13,10 +13,12 @@
 # limitations under the License.
 """Auth API CLI"""
 import logging
+import os
 
 import click
 
 import planet
+from planet.constants import ENV_API_KEY
 from .cmds import translate_exceptions
 
 LOGGER = logging.getLogger(__name__)
@@ -48,12 +50,32 @@ def init(ctx, email, password):
     '''Obtain and store authentication information'''
     base_url = ctx.obj['BASE_URL']
     plauth = planet.Auth.from_login(email, password, base_url=base_url)
-    plauth.write()
+    plauth.store()
     click.echo('Initialized')
+    if os.getenv(ENV_API_KEY):
+        click.echo(f'Warning - Environment variable {ENV_API_KEY} already '
+                   'exists. To update, with the new value, use the following:')
+        click.echo(f'export {ENV_API_KEY}=$(planet auth value)')
 
 
 @auth.command()
 @translate_exceptions
 def value():
     '''Print the stored authentication information'''
     click.echo(planet.Auth.from_file().value)
+
+
+@auth.command()
+@translate_exceptions
+@click.argument('key')
+def store(key):
+    '''Store authentication information'''
+    plauth = planet.Auth.from_key(key)
+    if click.confirm('This overrides the stored value. Continue?'):
+        plauth.store()
+        click.echo('Updated')
+        if os.getenv(ENV_API_KEY):
+            click.echo(f'Warning - Environment variable {ENV_API_KEY} already '
+                       'exists. To update, with the new value, use the '
+                       'following:')
+            click.echo(f'export {ENV_API_KEY}=$(planet auth value)')

planet/cli/data.py

@@ -37,10 +37,8 @@
 
 @asynccontextmanager
 async def data_client(ctx):
-    auth = ctx.obj['AUTH']
-    base_url = ctx.obj['BASE_URL']
-    async with CliSession(auth=auth) as sess:
-        cl = DataClient(sess, base_url=base_url)
+    async with CliSession() as sess:
+        cl = DataClient(sess, base_url=ctx.obj['BASE_URL'])
         yield cl
 
 
@@ -52,7 +50,6 @@ async def data_client(ctx):
               help='Assign custom base Orders API URL.')
 def data(ctx, base_url):
     '''Commands for interacting with the Data API'''
-    ctx.obj['AUTH'] = None
     ctx.obj['BASE_URL'] = base_url
 
 

planet/cli/orders.py

@@ -31,9 +31,8 @@
 
 @asynccontextmanager
 async def orders_client(ctx):
-    auth = ctx.obj['AUTH']
     base_url = ctx.obj['BASE_URL']
-    async with CliSession(auth=auth) as sess:
+    async with CliSession() as sess:
         cl = OrdersClient(sess, base_url=base_url)
         yield cl
 
@@ -46,7 +45,6 @@ async def orders_client(ctx):
               help='Assign custom base Orders API URL.')
 def orders(ctx, base_url):
     '''Commands for interacting with the Orders API'''
-    ctx.obj['AUTH'] = None
     ctx.obj['BASE_URL'] = base_url
 
 

planet/cli/session.py

@@ -1,12 +1,12 @@
 """CLI HTTP/auth sessions."""
 
-from planet.auth import AuthType
+from planet.auth import Auth
 from planet.http import Session
-from typing import Optional
 
 
 class CliSession(Session):
+    """Session with CLI-specific auth and identifying header"""
 
-    def __init__(self, auth: Optional[AuthType] = None):
-        super().__init__(auth)
+    def __init__(self):
+        super().__init__(Auth.from_file())
         self._client.headers.update({'X-Planet-App': 'python-cli'})

planet/cli/subscriptions.py

@@ -14,9 +14,7 @@
 @click.pass_context
 def subscriptions(ctx):
     '''Commands for interacting with the Subscriptions API'''
-    # None means that order of precedence is 1) environment variable,
-    # 2) secret file.
-    ctx.obj['AUTH'] = None
+    pass
 
 
 # We want our command to be known as "list" on the command line but
@@ -40,7 +38,7 @@ def subscriptions(ctx):
 @coro
 async def list_subscriptions_cmd(ctx, status, limit, pretty):
     """Prints a sequence of JSON-encoded Subscription descriptions."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         async for sub in client.list_subscriptions(status=status, limit=limit):
             echo_json(sub, pretty)
@@ -75,7 +73,7 @@ def parse_request(ctx, param, value: str) -> dict:
 @coro
 async def create_subscription_cmd(ctx, request, pretty):
     """Submits a subscription request and prints the API response."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         sub = await client.create_subscription(request)
         echo_json(sub, pretty)
@@ -89,7 +87,7 @@ async def create_subscription_cmd(ctx, request, pretty):
 @coro
 async def cancel_subscription_cmd(ctx, subscription_id, pretty):
     """Cancels a subscription and prints the API response."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         sub = await client.cancel_subscription(subscription_id)
         echo_json(sub, pretty)
@@ -104,7 +102,7 @@ async def cancel_subscription_cmd(ctx, subscription_id, pretty):
 @coro
 async def update_subscription_cmd(ctx, subscription_id, request, pretty):
     """Updates a subscription and prints the API response."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         sub = await client.update_subscription(subscription_id, request)
         echo_json(sub, pretty)
@@ -118,7 +116,7 @@ async def update_subscription_cmd(ctx, subscription_id, request, pretty):
 @coro
 async def describe_subscription_cmd(ctx, subscription_id, pretty):
     """Gets the description of a subscription and prints the API response."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         sub = await client.get_subscription(subscription_id)
         echo_json(sub, pretty)
@@ -154,7 +152,7 @@ async def list_subscription_results_cmd(ctx,
                                         status,
                                         limit):
     """Gets results of a subscription and prints the API response."""
-    async with CliSession(auth=ctx.obj['AUTH']) as session:
+    async with CliSession() as session:
         client = SubscriptionsClient(session)
         async for result in client.get_results(subscription_id,
                                                status=status,

planet/constants.py

@@ -20,6 +20,8 @@
 
 DATA_DIR = Path(os.path.dirname(__file__)) / 'data'
 
+ENV_API_KEY = 'PL_API_KEY'
+
 PLANET_BASE_URL = 'https://api.planet.com'
 
 SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json'

tests/integration/test_auth_cli.py

@@ -13,6 +13,7 @@
 # the License.
 from http import HTTPStatus
 import json
+import os
 
 from click.testing import CliRunner
 import httpx
@@ -104,3 +105,19 @@ def test_cli_auth_value_failure(redirect_secretfile):
     assert result.exception
     assert 'Error: Auth information does not exist or is corrupted.' \
         in result.output
+
+
+def test_cli_auth_store_cancel(redirect_secretfile):
+    result = CliRunner().invoke(cli.main, ['auth', 'store', 'setval'],
+                                input='')
+    assert not result.exception
+    assert not os.path.isfile(redirect_secretfile)
+
+
+def test_cli_auth_store_confirm(redirect_secretfile):
+    result = CliRunner().invoke(cli.main, ['auth', 'store', 'setval'],
+                                input='y')
+    assert not result.exception
+
+    with open(redirect_secretfile, 'r') as f:
+        assert json.load(f) == {'key': 'setval'}