From bf662f0c19797b27b86d48af92a99ab522761b9f Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Sun, 7 Jul 2024 08:52:09 -0700
Subject: [PATCH 01/81] ignore venv and pycharm files.
---
.gitignore | 2 ++
1 file changed, 2 insertions(+)
diff --git a/.gitignore b/.gitignore
index 17f499ee..df10277b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,7 +23,9 @@ coverage.xml
*.pyc
# Editors
+.idea/
.vscode/
# Docs build
site
.venv
+venv
From 92fb28bd020daf831627101461d909c3cf3f7b7e Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Sun, 7 Jul 2024 21:41:58 -0700
Subject: [PATCH 02/81] Work in progress.
---
planet/auth.py | 266 +++++++++++--------------------------------
planet/cli/auth.py | 61 ++++++----
planet/cli/cli.py | 22 +++-
planet/cli/cmds.py | 6 +-
planet/constants.py | 4 +-
planet/exceptions.py | 5 -
setup.py | 10 +-
7 files changed, 140 insertions(+), 234 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 38dda64b..3e74dc75 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -1,5 +1,5 @@
# Copyright 2020 Planet Labs, Inc.
-# Copyright 2022 Planet Labs PBC.
+# Copyright 2022, 2024 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -15,28 +15,31 @@
"""Manage authentication with Planet APIs"""
from __future__ import annotations # https://stackoverflow.com/a/33533514
import abc
-import json
-import logging
-import os
import pathlib
-import stat
import typing
-from typing import Optional
-
+import warnings
import httpx
-import jwt
-from . import http
-from .constants import ENV_API_KEY, PLANET_BASE_URL, SECRET_FILE_PATH
-from .exceptions import AuthException
+from .constants import SECRET_FILE_PATH
-LOGGER = logging.getLogger(__name__)
+from planet_auth import Auth as PLAuth
+from planet_auth import PlanetLegacyAuthClientConfig as PLAuth_PlanetLegacyAuthClientConfig
+from planet_auth_config import Production as PLAuthConf_Production
-BASE_URL = f'{PLANET_BASE_URL}/v0/auth'
AuthType = httpx.Auth
+# TODO: planet_auth.Auth potentially entirely supersedes this class.
+# But, keeping this here for now for interface stability.
+# TODO: Add from_oauth_user_browser / no browser / service account?
+# Between confidential and non-confidential clients, user clients
+# and m2m clients, and clients with and without browsers and rich
+# user interaction, there are a wide variety of ways a customer's
+# client may need to obtain OAuth tokens. With time limited
+# access tokens and the need to manage refresh activity, the auth
+# service interaction model is also necessarily different than
+# what this Auth class models.
class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
@@ -47,14 +50,19 @@ def from_key(key: str) -> AuthType:
Parameters:
key: Planet API key
"""
- auth = APIKeyAuth(key=key)
- LOGGER.debug('Auth obtained from api key.')
- return auth
+ # TODO : document preferred new method in the warning. User OAuth flows should be favored
+ # for user API access. M2M OAuth flows for other use cases.
+ warnings.warn("Auth.from_key() will be deprecated.", PendingDeprecationWarning)
+ plauth_config = {
+ "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ "api_key": key,
+ }
+ pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config)
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
def from_file(
- filename: Optional[typing.Union[str,
- pathlib.Path]] = None) -> AuthType:
+ filename: typing.Optional[typing.Union[str, pathlib.Path]] = None) -> AuthType:
"""Create authentication from secret file.
The secret file is named `.planet.json` and is stored in the user
@@ -65,21 +73,19 @@ def from_file(
filename: Alternate path for the planet secret file.
"""
- filename = filename or SECRET_FILE_PATH
-
- try:
- secrets = _SecretFile(filename).read()
- auth = APIKeyAuth.from_dict(secrets)
- except FileNotFoundError:
- raise AuthException(f'File {filename} does not exist.')
- except (KeyError, json.decoder.JSONDecodeError):
- raise AuthException(f'File {filename} is not the correct format.')
-
- LOGGER.debug(f'Auth read from secret file {filename}.')
- return auth
+ # TODO - Document preferred replacement. A token file from PLAuth's Legacy client
+ # is formatted to be compatible with this library's .planet.json format files.
+ warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
+ plauth_config = {
+ **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ }
+ pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config,
+ token_file=filename or SECRET_FILE_PATH)
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
- def from_env(variable_name: Optional[str] = None) -> AuthType:
+ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
"""Create authentication from environment variable.
Reads the `PL_API_KEY` environment variable
@@ -87,21 +93,16 @@ def from_env(variable_name: Optional[str] = None) -> AuthType:
Parameters:
variable_name: Alternate environment variable.
"""
- variable_name = variable_name or ENV_API_KEY
- api_key = os.getenv(variable_name, '')
- try:
- auth = APIKeyAuth(api_key)
- LOGGER.debug(f'Auth set from environment variable {variable_name}')
- except APIKeyAuthException:
- raise AuthException(
- f'Environment variable {variable_name} either does not exist '
- 'or is empty.')
- return auth
+ # TODO: document all the new ways the env can set things up for OAuth clients.
+ if variable_name:
+ warnings.warn("The variable_name parameter has been deprecated from planet.Auth.from_env().", DeprecationWarning)
+ pl_authlib_context = PLAuth.initialize_from_env()
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
def from_login(email: str,
password: str,
- base_url: Optional[str] = None) -> AuthType:
+ base_url: typing.Optional[str] = None) -> AuthType:
"""Create authentication from login email and password.
Note: To keep your password secure, the use of `getpass` is
@@ -113,159 +114,28 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- cl = AuthClient(base_url=base_url)
- auth_data = cl.login(email, password)
-
- api_key = auth_data['api_key']
- auth = APIKeyAuth(api_key)
- LOGGER.debug('Auth set from login email and password')
- return auth
-
- @classmethod
- @abc.abstractmethod
- def from_dict(cls, data: dict) -> AuthType:
- pass
-
- @property
- @abc.abstractmethod
- def value(self):
- pass
-
- @abc.abstractmethod
- def to_dict(self) -> dict:
- pass
-
- def store(self,
- filename: Optional[typing.Union[str, pathlib.Path]] = None):
- """Store authentication information in secret file.
-
- Parameters:
- filename: Alternate path for the planet secret file.
- """
- filename = filename or SECRET_FILE_PATH
- secret_file = _SecretFile(filename)
- secret_file.write(self.to_dict())
-
-
-class AuthClient:
-
- def __init__(self, base_url: Optional[str] = None):
- """
- Parameters:
- base_url: The base URL to use. Defaults to production
- authentication API base url.
- """
- self._base_url = base_url or BASE_URL
- if self._base_url.endswith('/'):
- self._base_url = self._base_url[:-1]
-
- def login(self, email: str, password: str) -> dict:
- """Login using email identity and credentials.
-
- Note: To keep your password secure, the use of `getpass` is
- recommended.
-
- Parameters:
- email: Planet account email address.
- password: Planet account password.
-
- Returns:
- A JSON object containing an `api_key` property with the user's
- API_KEY.
- """
- url = f'{self._base_url}/login'
- data = {'email': email, 'password': password}
-
- sess = http.AuthSession()
- resp = sess.request(url=url, method='POST', json=data)
- return self.decode_response(resp)
-
- @staticmethod
- def decode_response(response):
- """Decode the token JWT"""
- token = response.json()['token']
- return jwt.decode(token, options={'verify_signature': False})
-
-
-class APIKeyAuthException(Exception):
- """exceptions thrown by APIKeyAuth"""
- pass
-
-
-class APIKeyAuth(httpx.BasicAuth, Auth):
- """Planet API Key authentication."""
- DICT_KEY = 'key'
-
- def __init__(self, key: str):
- """Initialize APIKeyAuth.
-
- Parameters:
- key: API key.
-
- Raises:
- APIKeyException: If API key is None or empty string.
- """
- if not key:
- raise APIKeyAuthException('API key cannot be empty.')
- self._key = key
- super().__init__(self._key, '')
-
- @classmethod
- def from_dict(cls, data: dict) -> APIKeyAuth:
- """Instantiate APIKeyAuth from a dict."""
- api_key = data[cls.DICT_KEY]
- return cls(api_key)
-
- def to_dict(self):
- """Represent APIKeyAuth as a dict."""
- return {self.DICT_KEY: self._key}
-
- @property
- def value(self):
- return self._key
-
-
-class _SecretFile:
-
- def __init__(self, path: typing.Union[str, pathlib.Path]):
- self.path = pathlib.Path(path)
-
- self.permissions = stat.S_IRUSR | stat.S_IWUSR # user rw
-
- # in sdk versions <=2.0.0, secret file was created with the wrong
- # permissions, fix this automatically as well as catching the unlikely
- # cases where the permissions get changed externally
- self._enforce_permissions()
-
- def write(self, contents: dict):
- try:
- secrets_to_write = self.read()
- secrets_to_write.update(contents)
- except (FileNotFoundError, KeyError, json.decoder.JSONDecodeError):
- secrets_to_write = contents
-
- self._write(secrets_to_write)
-
- def _write(self, contents: dict):
- LOGGER.debug(f'Writing to {self.path}')
-
- def opener(path, flags):
- return os.open(path, flags, self.permissions)
-
- with open(self.path, 'w', opener=opener) as fp:
- fp.write(json.dumps(contents))
-
- def read(self) -> dict:
- LOGGER.debug(f'Reading from {self.path}')
- with open(self.path, 'r') as fp:
- contents = json.loads(fp.read())
- return contents
-
- def _enforce_permissions(self):
- """if the file's permissions are not what they should be, fix them"""
- if self.path.exists():
- # in octal, permissions is the last three bits of the mode
- file_permissions = self.path.stat().st_mode & 0o777
- if file_permissions != self.permissions:
- LOGGER.info('Fixing planet secret file permissions.')
- self.path.chmod(self.permissions)
+ # TODO - PLAuth.login will save the credential if the file is set. Handle this case?
+ # We need to conditionally set the token file in the initialize call.
+ # TODO - update warning with directions on what to replace this with. (maybe from_user_oauth_login?)
+ warnings.warn("Auth.from_login will be deprecated.", PendingDeprecationWarning)
+ plauth_config = {
+ **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ }
+ if base_url:
+ plauth_config["legacy_auth_endpoint"] = base_url
+
+ pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config)
+ pl_authlib_context.login(username=email, password=password, allow_tty_prompt=False)
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
+
+
+class _PLAuthLibAuth(Auth, AuthType):
+ # PLAuth uses a "has a" AuthType authenticator pattern.
+ # This library's Auth class employs a "is a" AuthType authenticator design pattern.
+ # This class smooths over that design difference.
+ def __init__(self, plauth: PLAuth):
+ self._plauth = plauth
+
+ def auth_flow(self, r: httpx._models.Request):
+ return self._plauth.request_authenticator().auth_flow(r)
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index 06033669..a4f8b0f7 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -14,16 +14,29 @@
"""Auth API CLI"""
import logging
import os
-
+import warnings
import click
-import planet
-from planet.constants import ENV_API_KEY
+from planet_auth import Auth as PLAuth
+from planet_auth import PlanetLegacyAuthClientConfig as PLAuth_PlanetLegacyAuthClientConfig
+from planet_auth import FileBackedPlanetLegacyApiKey as PLAuth_FileBackedPlanetLegacyApiKey
+from planet_auth_config import Production as PLAuthConf_Production
+import planet_auth_utils.commands.cli.planet_legacy_auth_cmd
+
+from planet.constants import ENV_API_KEY, SECRET_FILE_PATH
from .cmds import translate_exceptions
LOGGER = logging.getLogger(__name__)
+def _api_key_env_warning():
+ 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)')
+
+
@click.group() # type: ignore
@click.pass_context
@click.option('-u',
@@ -32,7 +45,19 @@
help='Assign custom base Auth API URL.')
def auth(ctx, base_url):
"""Commands for working with Planet authentication"""
- ctx.obj['BASE_URL'] = base_url
+ # TODO: should we deprecate this whole command in favor of the functionality of the embedded 'plauth'?
+ # warnings.warn("'auth' command will be deprecated. Please use 'plauth' to manage user credentials.", PendingDeprecationWarning)
+
+ # Override any newer style planet_auth library auth profiles and
+ # always wire up the legacy auth implementation to the planet library's
+ # preferred paths.
+ _plauth_config = {
+ **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ }
+ if base_url:
+ _plauth_config["legacy_auth_endpoint"] = base_url
+ ctx.obj["AUTH"] = PLAuth.initialize_from_config_dict(client_config=_plauth_config, token_file=SECRET_FILE_PATH)
@auth.command() # type: ignore
@@ -48,34 +73,26 @@ def auth(ctx, base_url):
help=('Account password. Will not be saved.'))
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.store()
+ ctx.invoke(planet_auth_utils.commands.cli.planet_legacy_auth_cmd.pllegacy_do_login, username=email, password=password)
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)')
-
+ _api_key_env_warning()
@auth.command() # type: ignore
+@click.pass_context
@translate_exceptions
-def value():
+def value(ctx):
"""Print the stored authentication information"""
- click.echo(planet.Auth.from_file().value)
+ ctx.forward(planet_auth_utils.commands.cli.planet_legacy_auth_cmd.do_print_api_key)
@auth.command() # type: ignore
+@click.pass_context
@translate_exceptions
@click.argument('key')
-def store(key):
+def store(ctx, key):
"""Store authentication information"""
- plauth = planet.Auth.from_key(key)
+ _token_file = PLAuth_FileBackedPlanetLegacyApiKey(api_key=key, api_key_file=ctx.obj["AUTH"].token_file_path())
if click.confirm('This overrides the stored value. Continue?'):
- plauth.store()
+ _token_file.save()
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)')
+ _api_key_env_warning()
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 862eb489..c4d1355b 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -18,9 +18,15 @@
import click
+from planet_auth_utils import embedded_plauth_cmd_group
+from planet_auth_utils import initialize_auth_client_context
+from planet_auth_utils import opt_auth_profile
+from planet_auth_utils import opt_auth_client_config_file
+from planet_auth_utils import opt_token_file
+
import planet
-from . import auth, collect, data, orders, subscriptions
+from . import auth, cmds, collect, data, orders, subscriptions
LOGGER = logging.getLogger(__name__)
@@ -36,7 +42,11 @@
default="warning",
help=("Optional: set verbosity level to warning, info, or debug.\
Defaults to warning."))
-def main(ctx, verbosity, quiet):
+@opt_auth_profile
+# @opt_token_file # TODO - support this? Check compatibility with other commands or legacy file?
+# @opt_auth_client_config_file # TODO - support this? Limit it to make interface simpler?
+@cmds.translate_exceptions
+def main(ctx, verbosity, quiet, auth_profile):
"""Planet SDK for Python CLI"""
_configure_logging(verbosity)
@@ -44,7 +54,11 @@ def main(ctx, verbosity, quiet):
# by means other than the `if` block below)
ctx.ensure_object(dict)
ctx.obj['QUIET'] = quiet
-
+ ctx.obj['AUTH'] = initialize_auth_client_context(
+ auth_profile_opt=auth_profile,
+ token_file_opt=None, # TODO - support arg? token_file_opt=token_file
+ auth_client_config_file_opt=None, # TODO - support arg? auth_client_config_file_opt=auth_client_config_file
+ )
def _configure_logging(verbosity):
"""configure logging via verbosity level, corresponding
@@ -73,6 +87,8 @@ def _configure_logging(verbosity):
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+# main.add_command(cmd=embedded_plauth_cmd_group, name="auth") # type: ignore
+main.add_command(cmd=embedded_plauth_cmd_group, name="plauth") # type: ignore
main.add_command(auth.auth) # type: ignore
main.add_command(data.data) # type: ignore
main.add_command(orders.orders) # type: ignore
diff --git a/planet/cli/cmds.py b/planet/cli/cmds.py
index f25cadc8..3cfba616 100644
--- a/planet/cli/cmds.py
+++ b/planet/cli/cmds.py
@@ -17,6 +17,8 @@
import click
+from planet_auth import AuthException as PLAuth_AuthException
+
from planet import exceptions
@@ -55,10 +57,10 @@ def translate_exceptions(func):
def wrapper(*args, **kwargs):
try:
func(*args, **kwargs)
- except exceptions.AuthException:
+ except PLAuth_AuthException:
raise click.ClickException(
'Auth information does not exist or is corrupted. Initialize '
- 'with `planet auth init`.')
+ 'with `planet auth init`.') # TODO: where do we want to steer users now? `planet plauth`?
except exceptions.PlanetError as ex:
raise click.ClickException(ex)
diff --git a/planet/constants.py b/planet/constants.py
index c9b1843b..d1508eb6 100644
--- a/planet/constants.py
+++ b/planet/constants.py
@@ -20,8 +20,8 @@
DATA_DIR = Path(os.path.dirname(__file__)) / 'data'
-ENV_API_KEY = 'PL_API_KEY'
+ENV_API_KEY = 'PL_API_KEY' # TODO: belongs to plauth lib
PLANET_BASE_URL = 'https://api.planet.com'
-SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json'
+SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json' # TODO: deprecate
diff --git a/planet/exceptions.py b/planet/exceptions.py
index eee852bd..1935e65a 100644
--- a/planet/exceptions.py
+++ b/planet/exceptions.py
@@ -78,11 +78,6 @@ class ClientError(PlanetError):
pass
-class AuthException(ClientError):
- """Exceptions encountered during authentication"""
- pass
-
-
class PagingError(ClientError):
"""For errors that occur during paging."""
pass
diff --git a/setup.py b/setup.py
index c8a8c29e..dc3f0a29 100644
--- a/setup.py
+++ b/setup.py
@@ -28,9 +28,11 @@
'geojson',
'httpx>=0.23.0',
'jsonschema',
- 'pyjwt>=2.1',
'tqdm>=4.56',
'typing-extensions',
+ 'planet-auth>=1.5.2',
+ 'planet-auth-util>=1.5.1',
+ 'planet-auth-config>=0.3.2', # FIXME - This currently has internal endpoints, too.
]
test_requires = ['pytest', 'anyio', 'pytest-cov', 'respx>=0.20']
@@ -44,6 +46,10 @@
'mkdocstrings==0.18.1'
]
+dev_requires = [
+ 'nox'
+]
+
setup(
name='planet',
version=version,
@@ -80,7 +86,7 @@
'test': test_requires,
'lint': lint_requires,
'docs': doc_requires,
- 'dev': test_requires + lint_requires + doc_requires
+ 'dev': test_requires + lint_requires + doc_requires + dev_requires
},
entry_points={
'console_scripts': [
From 03beb9f9101617725ac973870030218a73d41376 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Sun, 25 Aug 2024 16:39:58 -0700
Subject: [PATCH 03/81] working on using planet_auth library
---
planet/auth.py | 39 +++++++++++++++++++++----------------
planet/cli/auth.py | 33 ++++++++++++++++++-------------
planet/cli/cli.py | 31 ++++++++++++++++-------------
planet/cli/cmds.py | 5 +++--
planet/cli/data.py | 2 +-
planet/cli/orders.py | 2 +-
planet/cli/session.py | 4 ++--
planet/cli/subscriptions.py | 2 +-
planet/constants.py | 4 +---
setup.py | 4 ++--
10 files changed, 70 insertions(+), 56 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 3e74dc75..3df61d5a 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -20,11 +20,10 @@
import warnings
import httpx
-from .constants import SECRET_FILE_PATH
+import planet_auth
+import planet_auth_config
-from planet_auth import Auth as PLAuth
-from planet_auth import PlanetLegacyAuthClientConfig as PLAuth_PlanetLegacyAuthClientConfig
-from planet_auth_config import Production as PLAuthConf_Production
+from .constants import SECRET_FILE_PATH
AuthType = httpx.Auth
@@ -54,10 +53,10 @@ def from_key(key: str) -> AuthType:
# for user API access. M2M OAuth flows for other use cases.
warnings.warn("Auth.from_key() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
- "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
"api_key": key,
}
- pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config)
+ pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -77,10 +76,10 @@ def from_file(
# is formatted to be compatible with this library's .planet.json format files.
warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
- **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
- "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
- pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config,
+ pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config,
token_file=filename or SECRET_FILE_PATH)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@@ -96,7 +95,7 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
# TODO: document all the new ways the env can set things up for OAuth clients.
if variable_name:
warnings.warn("The variable_name parameter has been deprecated from planet.Auth.from_env().", DeprecationWarning)
- pl_authlib_context = PLAuth.initialize_from_env()
+ pl_authlib_context = planet_auth.Auth.initialize_from_env()
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -119,22 +118,28 @@ def from_login(email: str,
# TODO - update warning with directions on what to replace this with. (maybe from_user_oauth_login?)
warnings.warn("Auth.from_login will be deprecated.", PendingDeprecationWarning)
plauth_config = {
- **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
- "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
if base_url:
plauth_config["legacy_auth_endpoint"] = base_url
- pl_authlib_context = PLAuth.initialize_from_config_dict(client_config=plauth_config)
+ pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config)
pl_authlib_context.login(username=email, password=password, allow_tty_prompt=False)
return _PLAuthLibAuth(plauth=pl_authlib_context)
+ @staticmethod
+ def from_plauth(pl_authlib_context: planet_auth.Auth):
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
+
class _PLAuthLibAuth(Auth, AuthType):
- # PLAuth uses a "has a" AuthType authenticator pattern.
- # This library's Auth class employs a "is a" AuthType authenticator design pattern.
- # This class smooths over that design difference.
- def __init__(self, plauth: PLAuth):
+ # The Planet Auth Library uses a "has a" authenticator pattern for its Auth context.
+ # This library employs a "is a" authenticator design pattern for user's of
+ # its Auth context obtained from the constructors above.
+ # This class smooths over that design difference as we move to using
+ # the Planet Auth Library.
+ def __init__(self, plauth: planet_auth.Auth):
self._plauth = plauth
def auth_flow(self, r: httpx._models.Request):
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index a4f8b0f7..35980515 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -17,24 +17,26 @@
import warnings
import click
-from planet_auth import Auth as PLAuth
-from planet_auth import PlanetLegacyAuthClientConfig as PLAuth_PlanetLegacyAuthClientConfig
-from planet_auth import FileBackedPlanetLegacyApiKey as PLAuth_FileBackedPlanetLegacyApiKey
-from planet_auth_config import Production as PLAuthConf_Production
-import planet_auth_utils.commands.cli.planet_legacy_auth_cmd
+import planet_auth
+import planet_auth_config
+import planet_auth_utils.commands.cli.planet_legacy_auth_cmd # FIXME - Should be top level import
-from planet.constants import ENV_API_KEY, SECRET_FILE_PATH
+from planet.constants import SECRET_FILE_PATH
from .cmds import translate_exceptions
LOGGER = logging.getLogger(__name__)
+# FIXME: this may need to be expanded to cover all env vars in play
+# (PLAUTH has no equivalent warning, maybe it should if/when we add
+# some sort of select default profile functionality.)
+# FIXME: this warning encourages the use of API keys, that I want to deprecate.
def _api_key_env_warning():
- if os.getenv(ENV_API_KEY):
- click.echo(f'Warning - Environment variable {ENV_API_KEY} already '
+ if os.getenv(planet_auth.EnvironmentVariables.AUTH_API_KEY):
+ click.echo(f'Warning - Environment variable {planet_auth.EnvironmentVariables.AUTH_API_KEY} already '
'exists. To update, with the new value, use the '
'following:')
- click.echo(f'export {ENV_API_KEY}=$(planet auth value)')
+ click.echo(f'export {planet_auth.EnvironmentVariables.AUTH_API_KEY}=$(planet auth value)')
@click.group() # type: ignore
@@ -45,19 +47,22 @@ def _api_key_env_warning():
help='Assign custom base Auth API URL.')
def auth(ctx, base_url):
"""Commands for working with Planet authentication"""
- # TODO: should we deprecate this whole command in favor of the functionality of the embedded 'plauth'?
+ # TODO: should we deprecate this whole command in favor of the functionality of the embedded 'plauth'.
+ # TODO: plauth does not have, and maybe should, some sort of "select default" function
+ # so that it need not always have the user provide --auth-profile. This should be built into the plauth lib
+ # so that we can have nice default construction that follows the user's selection.
# warnings.warn("'auth' command will be deprecated. Please use 'plauth' to manage user credentials.", PendingDeprecationWarning)
# Override any newer style planet_auth library auth profiles and
# always wire up the legacy auth implementation to the planet library's
# preferred paths.
_plauth_config = {
- **PLAuthConf_Production.LEGACY_AUTH_AUTHORITY,
- "client_type": PLAuth_PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
+ "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
if base_url:
_plauth_config["legacy_auth_endpoint"] = base_url
- ctx.obj["AUTH"] = PLAuth.initialize_from_config_dict(client_config=_plauth_config, token_file=SECRET_FILE_PATH)
+ ctx.obj["AUTH"] = planet_auth.Auth.initialize_from_config_dict(client_config=_plauth_config, token_file=SECRET_FILE_PATH)
@auth.command() # type: ignore
@@ -91,7 +96,7 @@ def value(ctx):
@click.argument('key')
def store(ctx, key):
"""Store authentication information"""
- _token_file = PLAuth_FileBackedPlanetLegacyApiKey(api_key=key, api_key_file=ctx.obj["AUTH"].token_file_path())
+ _token_file = planet_auth.FileBackedPlanetLegacyApiKey(api_key=key, api_key_file=ctx.obj["AUTH"].token_file_path())
if click.confirm('This overrides the stored value. Continue?'):
_token_file.save()
click.echo('Updated')
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index c4d1355b..cf18b380 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -18,12 +18,7 @@
import click
-from planet_auth_utils import embedded_plauth_cmd_group
-from planet_auth_utils import initialize_auth_client_context
-from planet_auth_utils import opt_auth_profile
-from planet_auth_utils import opt_auth_client_config_file
-from planet_auth_utils import opt_token_file
-
+import planet_auth_utils
import planet
from . import auth, cmds, collect, data, orders, subscriptions
@@ -42,9 +37,9 @@
default="warning",
help=("Optional: set verbosity level to warning, info, or debug.\
Defaults to warning."))
-@opt_auth_profile
-# @opt_token_file # TODO - support this? Check compatibility with other commands or legacy file?
-# @opt_auth_client_config_file # TODO - support this? Limit it to make interface simpler?
+@planet_auth_utils.opt_auth_profile
+# @planet_auth_utils.opt_token_file # TODO - support this? Check compatibility with other commands or legacy file?
+# @planet_auth_utils.opt_auth_client_config_file # TODO - support this? Limit it to make interface simpler?
@cmds.translate_exceptions
def main(ctx, verbosity, quiet, auth_profile):
"""Planet SDK for Python CLI"""
@@ -54,12 +49,22 @@ def main(ctx, verbosity, quiet, auth_profile):
# by means other than the `if` block below)
ctx.ensure_object(dict)
ctx.obj['QUIET'] = quiet
- ctx.obj['AUTH'] = initialize_auth_client_context(
+
+ _configure_cli_auth_ctx(ctx, auth_profile)
+
+
+def _configure_cli_auth_ctx(ctx, auth_profile):
+ # planet-auth library Auth type
+ ctx.obj['AUTH'] = planet_auth_utils.initialize_auth_client_context(
auth_profile_opt=auth_profile,
token_file_opt=None, # TODO - support arg? token_file_opt=token_file
auth_client_config_file_opt=None, # TODO - support arg? auth_client_config_file_opt=auth_client_config_file
)
+ # planet SDK Auth type
+ ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(pl_authlib_context=ctx.obj['AUTH'])
+
+
def _configure_logging(verbosity):
"""configure logging via verbosity level, corresponding
to log levels warning, info and debug respectfully.
@@ -87,9 +92,9 @@ def _configure_logging(verbosity):
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-# main.add_command(cmd=embedded_plauth_cmd_group, name="auth") # type: ignore
-main.add_command(cmd=embedded_plauth_cmd_group, name="plauth") # type: ignore
-main.add_command(auth.auth) # type: ignore
+# main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="auth") # type: ignore
+main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="plauth") # type: ignore
+main.add_command(auth.auth) # type: ignore # TODO: deprecate entirely and use plauth
main.add_command(data.data) # type: ignore
main.add_command(orders.orders) # type: ignore
main.add_command(subscriptions.subscriptions) # type: ignore
diff --git a/planet/cli/cmds.py b/planet/cli/cmds.py
index 3cfba616..339a0224 100644
--- a/planet/cli/cmds.py
+++ b/planet/cli/cmds.py
@@ -17,7 +17,7 @@
import click
-from planet_auth import AuthException as PLAuth_AuthException
+import planet_auth
from planet import exceptions
@@ -57,8 +57,9 @@ def translate_exceptions(func):
def wrapper(*args, **kwargs):
try:
func(*args, **kwargs)
- except PLAuth_AuthException:
+ except planet_auth.AuthException as pla_ex:
raise click.ClickException(
+ f'{pla_ex}\n'
'Auth information does not exist or is corrupted. Initialize '
'with `planet auth init`.') # TODO: where do we want to steer users now? `planet plauth`?
except exceptions.PlanetError as ex:
diff --git a/planet/cli/data.py b/planet/cli/data.py
index 916598ea..05a816e5 100644
--- a/planet/cli/data.py
+++ b/planet/cli/data.py
@@ -44,7 +44,7 @@
@asynccontextmanager
async def data_client(ctx):
- async with CliSession() as sess:
+ async with CliSession(ctx) as sess:
cl = DataClient(sess, base_url=ctx.obj['BASE_URL'])
yield cl
diff --git a/planet/cli/orders.py b/planet/cli/orders.py
index db7734ec..b1e484f9 100644
--- a/planet/cli/orders.py
+++ b/planet/cli/orders.py
@@ -33,7 +33,7 @@
@asynccontextmanager
async def orders_client(ctx):
base_url = ctx.obj['BASE_URL']
- async with CliSession() as sess:
+ async with CliSession(ctx) as sess:
cl = OrdersClient(sess, base_url=base_url)
yield cl
diff --git a/planet/cli/session.py b/planet/cli/session.py
index a3b28b4d..58b699a4 100644
--- a/planet/cli/session.py
+++ b/planet/cli/session.py
@@ -7,6 +7,6 @@
class CliSession(Session):
"""Session with CLI-specific auth and identifying header"""
- def __init__(self):
- super().__init__(Auth.from_file())
+ def __init__(self, ctx):
+ super().__init__(ctx.obj['PLSDK_AUTH'])
self._client.headers.update({'X-Planet-App': 'python-cli'})
diff --git a/planet/cli/subscriptions.py b/planet/cli/subscriptions.py
index 8461e2b7..43619230 100644
--- a/planet/cli/subscriptions.py
+++ b/planet/cli/subscriptions.py
@@ -43,7 +43,7 @@ def check_item_type(ctx, param, item_type) -> Optional[List[dict]]:
@asynccontextmanager
async def subscriptions_client(ctx):
- async with CliSession() as sess:
+ async with CliSession(ctx) as sess:
cl = SubscriptionsClient(sess, base_url=ctx.obj['BASE_URL'])
yield cl
diff --git a/planet/constants.py b/planet/constants.py
index d1508eb6..d6610942 100644
--- a/planet/constants.py
+++ b/planet/constants.py
@@ -20,8 +20,6 @@
DATA_DIR = Path(os.path.dirname(__file__)) / 'data'
-ENV_API_KEY = 'PL_API_KEY' # TODO: belongs to plauth lib
-
PLANET_BASE_URL = 'https://api.planet.com'
-SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json' # TODO: deprecate
+SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json' # TODO: deprecate in favor of planet_auth library
diff --git a/setup.py b/setup.py
index dc3f0a29..a29bf71b 100644
--- a/setup.py
+++ b/setup.py
@@ -30,9 +30,9 @@
'jsonschema',
'tqdm>=4.56',
'typing-extensions',
- 'planet-auth>=1.5.2',
+ 'planet-auth>=2.0.0',
'planet-auth-util>=1.5.1',
- 'planet-auth-config>=0.3.2', # FIXME - This currently has internal endpoints, too.
+ 'planet-auth-config>=2.0.0', # FIXME - This currently has staging endpoints, too.
]
test_requires = ['pytest', 'anyio', 'pytest-cov', 'respx>=0.20']
From 25c2583a44b8b63eebfaadb6a326af0c7ab54e45 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Mon, 26 Aug 2024 13:09:39 -0700
Subject: [PATCH 04/81] update requirements
---
setup.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/setup.py b/setup.py
index a29bf71b..42cc564c 100644
--- a/setup.py
+++ b/setup.py
@@ -31,7 +31,7 @@
'tqdm>=4.56',
'typing-extensions',
'planet-auth>=2.0.0',
- 'planet-auth-util>=1.5.1',
+ 'planet-auth-util>=2.0.0',
'planet-auth-config>=2.0.0', # FIXME - This currently has staging endpoints, too.
]
From 971bac13104da0d7648493ed05112d792893e6a4 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Tue, 27 Aug 2024 09:00:01 -0700
Subject: [PATCH 05/81] WIP
---
Branch-Working-and-Release-Notes.txt | 11 +++++++++++
planet/cli/cli.py | 1 +
planet/cli/cmds.py | 4 ++--
3 files changed, 14 insertions(+), 2 deletions(-)
create mode 100644 Branch-Working-and-Release-Notes.txt
diff --git a/Branch-Working-and-Release-Notes.txt b/Branch-Working-and-Release-Notes.txt
new file mode 100644
index 00000000..97ecd463
--- /dev/null
+++ b/Branch-Working-and-Release-Notes.txt
@@ -0,0 +1,11 @@
+- TODO: Deprecated the legacy secret file. This will require a user migration. (todo : provide instructions for bootstrapping the new file)
+ Maybe I can jigger from_file to still do the old thing, and just steer new logins
+- TODO: deprecate the legacy auth command
+- TODO: migrate planet.Auth to planet_auth.Auth as much as possible
+- TODO: Don't forget env var behaviors
+- TODO: good handing for PL_CLIENT_ID and PL_CLIENT_SECRET
+
+# TODO: The old code would have a in-memory authenticator here. Verify behavior.
+# TODO: we do not have a good way to initialize M2M OAuth tokens from the env (I think? Maybe we do.) This really belongs to plauth
+# TODO: we need to allocate a client ID for the `planet` CLI. We are presently leaning on plauth's client ID. (maybe this is OK)
+# TODO: finalize message in translate_exceptions steering users to how to initialize auth.
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index cf18b380..500daa8c 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -92,6 +92,7 @@ def _configure_logging(verbosity):
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+# TODO - deprecate old auth command
# main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="auth") # type: ignore
main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="plauth") # type: ignore
main.add_command(auth.auth) # type: ignore # TODO: deprecate entirely and use plauth
diff --git a/planet/cli/cmds.py b/planet/cli/cmds.py
index 339a0224..aa165c62 100644
--- a/planet/cli/cmds.py
+++ b/planet/cli/cmds.py
@@ -61,8 +61,8 @@ def wrapper(*args, **kwargs):
raise click.ClickException(
f'{pla_ex}\n'
'Auth information does not exist or is corrupted. Initialize '
- 'with `planet auth init`.') # TODO: where do we want to steer users now? `planet plauth`?
- except exceptions.PlanetError as ex:
+ 'with `planet auth`.') # TODO/FIXME: finalize where we want to steer users now. `planet plauth`?
+ except (exceptions.PlanetError, FileNotFoundError) as ex:
raise click.ClickException(ex)
return wrapper
From 02c0562148c1061818679f0cdd14c83867c29c56 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Mon, 2 Sep 2024 21:14:26 -0700
Subject: [PATCH 06/81] WIP
---
planet/auth.py | 23 ++++++++---------------
planet/cli/cli.py | 16 +++++++++-------
2 files changed, 17 insertions(+), 22 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 3df61d5a..d6afb438 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -29,16 +29,9 @@
AuthType = httpx.Auth
-# TODO: planet_auth.Auth potentially entirely supersedes this class.
-# But, keeping this here for now for interface stability.
-# TODO: Add from_oauth_user_browser / no browser / service account?
-# Between confidential and non-confidential clients, user clients
-# and m2m clients, and clients with and without browsers and rich
-# user interaction, there are a wide variety of ways a customer's
-# client may need to obtain OAuth tokens. With time limited
-# access tokens and the need to manage refresh activity, the auth
-# service interaction model is also necessarily different than
-# what this Auth class models.
+# planet_auth and planet_auth_utils code more or less entirely
+# entirely supersedes this class. But, keeping this here for
+# now for interface stability to bridge with the rest of the SDK.
class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
@@ -134,11 +127,11 @@ def from_plauth(pl_authlib_context: planet_auth.Auth):
class _PLAuthLibAuth(Auth, AuthType):
- # The Planet Auth Library uses a "has a" authenticator pattern for its Auth context.
- # This library employs a "is a" authenticator design pattern for user's of
- # its Auth context obtained from the constructors above.
- # This class smooths over that design difference as we move to using
- # the Planet Auth Library.
+ # The Planet Auth Library uses a "has a" authenticator pattern for its
+ # planet_auth.Auth context class. This SDK library employs a "is a"
+ # authenticator design pattern for user's of its Auth context obtained
+ # from the constructors above. This class smooths over that design
+ # difference as we move to using the Planet Auth Library.
def __init__(self, plauth: planet_auth.Auth):
self._plauth = plauth
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 500daa8c..7b0610f6 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -38,10 +38,11 @@
help=("Optional: set verbosity level to warning, info, or debug.\
Defaults to warning."))
@planet_auth_utils.opt_auth_profile
+@planet_auth_utils.opt_auth_client_id
+@planet_auth_utils.opt_auth_client_secret
# @planet_auth_utils.opt_token_file # TODO - support this? Check compatibility with other commands or legacy file?
-# @planet_auth_utils.opt_auth_client_config_file # TODO - support this? Limit it to make interface simpler?
@cmds.translate_exceptions
-def main(ctx, verbosity, quiet, auth_profile):
+def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret):
"""Planet SDK for Python CLI"""
_configure_logging(verbosity)
@@ -50,15 +51,16 @@ def main(ctx, verbosity, quiet, auth_profile):
ctx.ensure_object(dict)
ctx.obj['QUIET'] = quiet
- _configure_cli_auth_ctx(ctx, auth_profile)
+ _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret)
-def _configure_cli_auth_ctx(ctx, auth_profile):
+def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret):
# planet-auth library Auth type
- ctx.obj['AUTH'] = planet_auth_utils.initialize_auth_client_context(
+ ctx.obj['AUTH'] = planet_auth_utils.ProfileManager.initialize_auth_client_context(
auth_profile_opt=auth_profile,
- token_file_opt=None, # TODO - support arg? token_file_opt=token_file
- auth_client_config_file_opt=None, # TODO - support arg? auth_client_config_file_opt=auth_client_config_file
+ token_file_opt=None, # TODO - support arg? token_file_opt=token_file,
+ auth_client_id_opt=auth_client_id,
+ auth_client_secret_opt=auth_client_secret,
)
# planet SDK Auth type
From d4063b50f993c0b7cd6c807693d554a8835322b4 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Tue, 3 Sep 2024 21:22:44 -0700
Subject: [PATCH 07/81] some better handling of options for the plauth lib
---
planet/cli/cli.py | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 7b0610f6..f7b36690 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -40,9 +40,9 @@
@planet_auth_utils.opt_auth_profile
@planet_auth_utils.opt_auth_client_id
@planet_auth_utils.opt_auth_client_secret
-# @planet_auth_utils.opt_token_file # TODO - support this? Check compatibility with other commands or legacy file?
+@planet_auth_utils.opt_auth_api_key
@cmds.translate_exceptions
-def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret):
+def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
"""Planet SDK for Python CLI"""
_configure_logging(verbosity)
@@ -51,16 +51,17 @@ def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret
ctx.ensure_object(dict)
ctx.obj['QUIET'] = quiet
- _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret)
+ _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret, auth_api_key)
-def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret):
+def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
# planet-auth library Auth type
ctx.obj['AUTH'] = planet_auth_utils.ProfileManager.initialize_auth_client_context(
auth_profile_opt=auth_profile,
token_file_opt=None, # TODO - support arg? token_file_opt=token_file,
auth_client_id_opt=auth_client_id,
auth_client_secret_opt=auth_client_secret,
+ auth_api_key_opt=auth_api_key,
)
# planet SDK Auth type
From c7ed86c61ccd5b84d36f68adafe993b34e46b359 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Wed, 4 Sep 2024 16:01:38 -0700
Subject: [PATCH 08/81] more plauth lib work
---
planet/auth.py | 56 +++++++++++++-----------
planet/cli/auth.py | 103 ---------------------------------------------
planet/cli/cli.py | 8 +---
planet/cli/cmds.py | 2 +-
4 files changed, 34 insertions(+), 135 deletions(-)
delete mode 100644 planet/cli/auth.py
diff --git a/planet/auth.py b/planet/auth.py
index d6afb438..a2d4ad56 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -15,6 +15,7 @@
"""Manage authentication with Planet APIs"""
from __future__ import annotations # https://stackoverflow.com/a/33533514
import abc
+import os
import pathlib
import typing
import warnings
@@ -22,6 +23,7 @@
import planet_auth
import planet_auth_config
+import planet_auth_utils
from .constants import SECRET_FILE_PATH
@@ -42,14 +44,14 @@ def from_key(key: str) -> AuthType:
Parameters:
key: Planet API key
"""
- # TODO : document preferred new method in the warning. User OAuth flows should be favored
- # for user API access. M2M OAuth flows for other use cases.
- warnings.warn("Auth.from_key() will be deprecated.", PendingDeprecationWarning)
- plauth_config = {
- "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
- "api_key": key,
- }
- pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config)
+ warnings.warn("Planet API keys will be deprecated at some point."
+ " Initialize an OAuth client, or create an OAuth service account."
+ " Proceeding for now.", PendingDeprecationWarning)
+ pl_authlib_context = planet_auth_utils.ProfileManager.initialize_auth_client_context(
+ auth_profile_opt=planet_auth_utils.Profiles.BUILTIN_PROFILE_NAME_LEGACY,
+ auth_api_key_opt=key,
+ save_token_file=False
+ )
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -65,8 +67,9 @@ def from_file(
filename: Alternate path for the planet secret file.
"""
- # TODO - Document preferred replacement. A token file from PLAuth's Legacy client
- # is formatted to be compatible with this library's .planet.json format files.
+ # There is no direct replacement for "from_file()", which held an API key.
+ # API keys will be deprecated, and user login will be different from service account
+ # login under OAuth.
warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
**planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
@@ -85,11 +88,13 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
Parameters:
variable_name: Alternate environment variable.
"""
- # TODO: document all the new ways the env can set things up for OAuth clients.
- if variable_name:
- warnings.warn("The variable_name parameter has been deprecated from planet.Auth.from_env().", DeprecationWarning)
- pl_authlib_context = planet_auth.Auth.initialize_from_env()
- return _PLAuthLibAuth(plauth=pl_authlib_context)
+ # There are just too many env vars and ways they interact and combine to continue to
+ # support this method with the planet auth lib in the future. Especially as we want
+ # to move away from API keys and towards OAuth methods.
+ warnings.warn("Auth.from_env() will be deprecated.", PendingDeprecationWarning)
+ variable_name = variable_name or planet_auth.EnvironmentVariables.AUTH_API_KEY
+ api_key = os.getenv(variable_name, None)
+ return Auth.from_key(api_key)
@staticmethod
def from_login(email: str,
@@ -106,23 +111,24 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- # TODO - PLAuth.login will save the credential if the file is set. Handle this case?
- # We need to conditionally set the token file in the initialize call.
- # TODO - update warning with directions on what to replace this with. (maybe from_user_oauth_login?)
- warnings.warn("Auth.from_login will be deprecated.", PendingDeprecationWarning)
- plauth_config = {
- **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
- "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
- }
+ warnings.warn("Auth.from_login() and password based user login will be deprecated.", PendingDeprecationWarning)
if base_url:
- plauth_config["legacy_auth_endpoint"] = base_url
+ warnings.warn("base_url is not longer a supported parameter to Auth.from_login()", DeprecationWarning)
- pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config)
+ pl_authlib_context = planet_auth_utils.ProfileManager.initialize_auth_client_context(
+ auth_profile_opt=planet_auth_utils.Profiles.BUILTIN_PROFILE_NAME_LEGACY
+ )
+ # Note: login() will save the resulting token
pl_authlib_context.login(username=email, password=password, allow_tty_prompt=False)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
def from_plauth(pl_authlib_context: planet_auth.Auth):
+ """
+ Create authentication from the provided Planet Auth Library Authentication Context.
+ Generally, applications will want to use one of the Auth Library helpers to
+ construct this context, such as the `initialize_auth_client_context()` method.
+ """
return _PLAuthLibAuth(plauth=pl_authlib_context)
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
deleted file mode 100644
index 35980515..00000000
--- a/planet/cli/auth.py
+++ /dev/null
@@ -1,103 +0,0 @@
-# Copyright 2022 Planet Labs PBC.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-"""Auth API CLI"""
-import logging
-import os
-import warnings
-import click
-
-import planet_auth
-import planet_auth_config
-import planet_auth_utils.commands.cli.planet_legacy_auth_cmd # FIXME - Should be top level import
-
-from planet.constants import SECRET_FILE_PATH
-from .cmds import translate_exceptions
-
-LOGGER = logging.getLogger(__name__)
-
-
-# FIXME: this may need to be expanded to cover all env vars in play
-# (PLAUTH has no equivalent warning, maybe it should if/when we add
-# some sort of select default profile functionality.)
-# FIXME: this warning encourages the use of API keys, that I want to deprecate.
-def _api_key_env_warning():
- if os.getenv(planet_auth.EnvironmentVariables.AUTH_API_KEY):
- click.echo(f'Warning - Environment variable {planet_auth.EnvironmentVariables.AUTH_API_KEY} already '
- 'exists. To update, with the new value, use the '
- 'following:')
- click.echo(f'export {planet_auth.EnvironmentVariables.AUTH_API_KEY}=$(planet auth value)')
-
-
-@click.group() # type: ignore
-@click.pass_context
-@click.option('-u',
- '--base-url',
- default=None,
- help='Assign custom base Auth API URL.')
-def auth(ctx, base_url):
- """Commands for working with Planet authentication"""
- # TODO: should we deprecate this whole command in favor of the functionality of the embedded 'plauth'.
- # TODO: plauth does not have, and maybe should, some sort of "select default" function
- # so that it need not always have the user provide --auth-profile. This should be built into the plauth lib
- # so that we can have nice default construction that follows the user's selection.
- # warnings.warn("'auth' command will be deprecated. Please use 'plauth' to manage user credentials.", PendingDeprecationWarning)
-
- # Override any newer style planet_auth library auth profiles and
- # always wire up the legacy auth implementation to the planet library's
- # preferred paths.
- _plauth_config = {
- **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
- "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
- }
- if base_url:
- _plauth_config["legacy_auth_endpoint"] = base_url
- ctx.obj["AUTH"] = planet_auth.Auth.initialize_from_config_dict(client_config=_plauth_config, token_file=SECRET_FILE_PATH)
-
-
-@auth.command() # type: ignore
-@click.pass_context
-@translate_exceptions
-@click.option(
- '--email',
- default=None,
- prompt=True,
- help=('The email address associated with your Planet credentials.'))
-@click.password_option('--password',
- confirmation_prompt=False,
- help=('Account password. Will not be saved.'))
-def init(ctx, email, password):
- """Obtain and store authentication information"""
- ctx.invoke(planet_auth_utils.commands.cli.planet_legacy_auth_cmd.pllegacy_do_login, username=email, password=password)
- click.echo('Initialized')
- _api_key_env_warning()
-
-@auth.command() # type: ignore
-@click.pass_context
-@translate_exceptions
-def value(ctx):
- """Print the stored authentication information"""
- ctx.forward(planet_auth_utils.commands.cli.planet_legacy_auth_cmd.do_print_api_key)
-
-
-@auth.command() # type: ignore
-@click.pass_context
-@translate_exceptions
-@click.argument('key')
-def store(ctx, key):
- """Store authentication information"""
- _token_file = planet_auth.FileBackedPlanetLegacyApiKey(api_key=key, api_key_file=ctx.obj["AUTH"].token_file_path())
- if click.confirm('This overrides the stored value. Continue?'):
- _token_file.save()
- click.echo('Updated')
- _api_key_env_warning()
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index f7b36690..3a666974 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -21,7 +21,7 @@
import planet_auth_utils
import planet
-from . import auth, cmds, collect, data, orders, subscriptions
+from . import cmds, collect, data, orders, subscriptions
LOGGER = logging.getLogger(__name__)
@@ -58,7 +58,6 @@ def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secre
# planet-auth library Auth type
ctx.obj['AUTH'] = planet_auth_utils.ProfileManager.initialize_auth_client_context(
auth_profile_opt=auth_profile,
- token_file_opt=None, # TODO - support arg? token_file_opt=token_file,
auth_client_id_opt=auth_client_id,
auth_client_secret_opt=auth_client_secret,
auth_api_key_opt=auth_api_key,
@@ -95,10 +94,7 @@ def _configure_logging(verbosity):
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-# TODO - deprecate old auth command
-# main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="auth") # type: ignore
-main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="plauth") # type: ignore
-main.add_command(auth.auth) # type: ignore # TODO: deprecate entirely and use plauth
+main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="auth") # type: ignore
main.add_command(data.data) # type: ignore
main.add_command(orders.orders) # type: ignore
main.add_command(subscriptions.subscriptions) # type: ignore
diff --git a/planet/cli/cmds.py b/planet/cli/cmds.py
index aa165c62..602e7688 100644
--- a/planet/cli/cmds.py
+++ b/planet/cli/cmds.py
@@ -61,7 +61,7 @@ def wrapper(*args, **kwargs):
raise click.ClickException(
f'{pla_ex}\n'
'Auth information does not exist or is corrupted. Initialize '
- 'with `planet auth`.') # TODO/FIXME: finalize where we want to steer users now. `planet plauth`?
+ 'with `planet auth`.')
except (exceptions.PlanetError, FileNotFoundError) as ex:
raise click.ClickException(ex)
From a9ff29439e82fb0bbc45b0fe27b4e35b18a5187d Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Wed, 4 Sep 2024 16:09:35 -0700
Subject: [PATCH 09/81] update notes
---
Branch-Working-and-Release-Notes.txt | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/Branch-Working-and-Release-Notes.txt b/Branch-Working-and-Release-Notes.txt
index 97ecd463..ed7d2da1 100644
--- a/Branch-Working-and-Release-Notes.txt
+++ b/Branch-Working-and-Release-Notes.txt
@@ -1,11 +1,8 @@
-- TODO: Deprecated the legacy secret file. This will require a user migration. (todo : provide instructions for bootstrapping the new file)
- Maybe I can jigger from_file to still do the old thing, and just steer new logins
-- TODO: deprecate the legacy auth command
-- TODO: migrate planet.Auth to planet_auth.Auth as much as possible
-- TODO: Don't forget env var behaviors
-- TODO: good handing for PL_CLIENT_ID and PL_CLIENT_SECRET
+- Replaced most user auth code with the planet auth library. This brings with it OAuth for user interactive and M2M flows.
+- Deprecated the old auth command. New auth command is implemented with the separate auth library
+ - TODO: link to lib
+ - planet auth init -> planet auth oauth login (or, planet --auth-profile legacy auth legacy login)
+ - planet auth value -> planet plauth oauth print-access-token (or planet --auth-profile legacy auth legacy print-api-key)
+- The legacy secret file has largely been deprecated. This will require a user migration.
-# TODO: The old code would have a in-memory authenticator here. Verify behavior.
-# TODO: we do not have a good way to initialize M2M OAuth tokens from the env (I think? Maybe we do.) This really belongs to plauth
# TODO: we need to allocate a client ID for the `planet` CLI. We are presently leaning on plauth's client ID. (maybe this is OK)
-# TODO: finalize message in translate_exceptions steering users to how to initialize auth.
From 7868a0fa1f8982a528a12088cb4840d0f1586e5f Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Fri, 4 Oct 2024 20:06:21 -0700
Subject: [PATCH 10/81] fix setup
---
setup.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/setup.py b/setup.py
index 42cc564c..f6d4a6de 100644
--- a/setup.py
+++ b/setup.py
@@ -31,7 +31,7 @@
'tqdm>=4.56',
'typing-extensions',
'planet-auth>=2.0.0',
- 'planet-auth-util>=2.0.0',
+ 'planet-auth-utils>=2.0.0',
'planet-auth-config>=2.0.0', # FIXME - This currently has staging endpoints, too.
]
From 40755ffd54cec5f855a45b9ea239fa12767689f5 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 30 Nov 2024 08:53:30 -0800
Subject: [PATCH 11/81] update to latest refactoring of auth libs
---
planet/auth.py | 53 ++++++++------
planet/auth_builtins.py | 154 ++++++++++++++++++++++++++++++++++++++++
planet/cli/cli.py | 6 +-
3 files changed, 188 insertions(+), 25 deletions(-)
create mode 100644 planet/auth_builtins.py
diff --git a/planet/auth.py b/planet/auth.py
index a2d4ad56..abeb3890 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -22,17 +22,16 @@
import httpx
import planet_auth
-import planet_auth_config
import planet_auth_utils
from .constants import SECRET_FILE_PATH
-
+from .auth_builtins import _ProductionEnv
AuthType = httpx.Auth
# planet_auth and planet_auth_utils code more or less entirely
-# entirely supersedes this class. But, keeping this here for
+# supersedes this class. But, keeping this here for
# now for interface stability to bridge with the rest of the SDK.
class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
@@ -47,10 +46,9 @@ def from_key(key: str) -> AuthType:
warnings.warn("Planet API keys will be deprecated at some point."
" Initialize an OAuth client, or create an OAuth service account."
" Proceeding for now.", PendingDeprecationWarning)
- pl_authlib_context = planet_auth_utils.ProfileManager.initialize_auth_client_context(
- auth_profile_opt=planet_auth_utils.Profiles.BUILTIN_PROFILE_NAME_LEGACY,
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_api_key_opt=key,
- save_token_file=False
+ save_token_file=False,
)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@@ -67,12 +65,14 @@ def from_file(
filename: Alternate path for the planet secret file.
"""
- # There is no direct replacement for "from_file()", which held an API key.
- # API keys will be deprecated, and user login will be different from service account
- # login under OAuth.
+ # There is no direct replacement for "from_file()", which expected the
+ # file to only hold an API key (planet_auth_utils now can use it for
+ # other things, too). API keys will be deprecated for most use cases,
+ # and user login will be different from service account login under
+ # OAuth.
warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
- **planet_auth_config.Production.LEGACY_AUTH_AUTHORITY,
+ **_ProductionEnv.LEGACY_AUTH_AUTHORITY,
"client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config,
@@ -88,10 +88,8 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
Parameters:
variable_name: Alternate environment variable.
"""
- # There are just too many env vars and ways they interact and combine to continue to
- # support this method with the planet auth lib in the future. Especially as we want
- # to move away from API keys and towards OAuth methods.
- warnings.warn("Auth.from_env() will be deprecated.", PendingDeprecationWarning)
+ # TODO: we should consider how we want to expose initialization
+ # from the ENV for OAuth M2M
variable_name = variable_name or planet_auth.EnvironmentVariables.AUTH_API_KEY
api_key = os.getenv(variable_name, None)
return Auth.from_key(api_key)
@@ -111,15 +109,26 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- warnings.warn("Auth.from_login() and password based user login will be deprecated.", PendingDeprecationWarning)
- if base_url:
- warnings.warn("base_url is not longer a supported parameter to Auth.from_login()", DeprecationWarning)
+ # TODO: Need to provide instructions on what an application should do.
+ # It would not be hard to add username/password support to the
+ # PlanetAuthFactory, but we should encourage an OAuth login.
+ # At a code level, we should provide "from_oauth_m2m" (Done) and something
+ # to use a user profile, that must be initialized interactively.
+ warnings.warn("Auth.from_login() has been deprecated.", DeprecationWarning)
+ raise DeprecationWarning("Auth.from_login() has been deprecated.")
+
+ @staticmethod
+ def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
+ """Create authentication from OAuth service account client ID and secret.
- pl_authlib_context = planet_auth_utils.ProfileManager.initialize_auth_client_context(
- auth_profile_opt=planet_auth_utils.Profiles.BUILTIN_PROFILE_NAME_LEGACY
+ Parameters:
+ client_id: Planet service account client ID.
+ client_secret: Planet service account client secret.
+ """
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_client_id_opt=client_id,
+ auth_client_secret_opt=client_secret,
)
- # Note: login() will save the resulting token
- pl_authlib_context.login(username=email, password=password, allow_tty_prompt=False)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -127,7 +136,7 @@ def from_plauth(pl_authlib_context: planet_auth.Auth):
"""
Create authentication from the provided Planet Auth Library Authentication Context.
Generally, applications will want to use one of the Auth Library helpers to
- construct this context, such as the `initialize_auth_client_context()` method.
+ construct this context (See the factory class).
"""
return _PLAuthLibAuth(plauth=pl_authlib_context)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
new file mode 100644
index 00000000..9487aefe
--- /dev/null
+++ b/planet/auth_builtins.py
@@ -0,0 +1,154 @@
+# Copyright 2024 Planet Labs PBC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+from typing import Dict, List, Optional
+from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
+
+# Needs to be set at runtime (not necessarily at import time) for dependency injection to planet_auth_util
+os.environ["PL_BUILTIN_AUTH_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+
+class _ProductionEnv:
+ PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0 = {
+ "_comment": "OIDC/OAuth server used by Planet Public API endpoints",
+ "auth_server": "https://login.planet.com/",
+ "audiences": ["https://api.planet.com/"]
+ }
+ PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB = {
+ "_comment": "OIDC/OAuth server used by Planet Public API endpoints",
+ "auth_server": "https://services.sentinel-hub.com/auth/realms/main",
+ "audiences": ["https://api.planet.com/"]
+ }
+ LEGACY_AUTH_AUTHORITY = {
+ "_comment": "Planet legacy JWT auth server used by Planet Public API endpoints",
+ "legacy_auth_endpoint": "https://api.planet.com/v0/auth/login"
+ }
+ PRIMARY_PUBLIC_OAUTH_AUTHORITIES = [
+ PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0,
+ PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB,
+ ]
+
+_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
+ # The well known OIDC client that is the Planet Python CLI.
+ # Developers should register their own clients so that users may
+ # manage grants for different applications. Registering applications
+ # also allows for application specific URLs or auth flow selection.
+ **_ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0,
+ "client_type": "oidc_device_code",
+ "client_id": "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees",
+ "scopes": ["planet", "offline_access", "openid", "profile", "email"],
+}
+
+_OIDC_AUTH_CLIENT_CONFIG__M2M_PROD = {
+ **_ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB,
+ "client_type": "oidc_client_credentials_secret",
+ "scopes": [],
+ # "client_id": "__MUST_BE_USER_SUPPLIED__",
+ # "client_secret": "__MUST_BE_USER_SUPPLIED__",
+ # "scopes": ["planet"],
+ # "audiences": [""]
+}
+
+_LEGACY_AUTH_CLIENT_CONFIG__PROD = {
+ **_ProductionEnv.LEGACY_AUTH_AUTHORITY,
+ "client_type": "planet_legacy",
+}
+
+_NOOP_AUTH_CLIENT_CONFIG = {
+ "client_type": "none",
+}
+
+
+class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
+ """
+ Concrete implementation of built-in client profiles for the planet_auth
+ library that pertain to the Planet Lab's cloud service.
+ """
+
+ # fmt: off
+ ##
+ ## OAuth production environment profiles
+ ##
+ # Real
+ BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
+ BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
+ # Aliases
+ # BUILTIN_PROFILE_NAME_PROD = "prod"
+ # BUILTIN_PROFILE_NAME_PROD_M2M = "prod-m2m"
+ # BUILTIN_PROFILE_NAME_PROD_AUTH0 = "prod-auth0"
+ # BUILTIN_PROFILE_NAME_PROD_SENTINEL_HUB = "prod-sentinel-hub"
+
+ ##
+ ## Profiles that use Planet's old (pre-OAuth) based auth protocol
+ ##
+ BUILTIN_PROFILE_NAME_LEGACY = "legacy"
+
+ ##
+ ## Misc auth profiles
+ ##
+ BUILTIN_PROFILE_NAME_NONE = "none"
+ BUILTIN_PROFILE_NAME_DEFAULT = "default"
+
+ ##
+ ## Default that should be used when no other selection has been made
+ ##
+ DEFAULT_PROFILE = BUILTIN_PROFILE_NAME_PLANET_USER
+
+ _builtin_profile_auth_client_configs = {
+ ## OAuth Client Configs
+ BUILTIN_PROFILE_NAME_PLANET_USER : _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
+ BUILTIN_PROFILE_NAME_PLANET_M2M : _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
+
+ # Planet Legacy Protocols
+ BUILTIN_PROFILE_NAME_LEGACY : _LEGACY_AUTH_CLIENT_CONFIG__PROD,
+
+ # Misc
+ BUILTIN_PROFILE_NAME_NONE : _NOOP_AUTH_CLIENT_CONFIG,
+ }
+
+ _builtin_profile_aliases = {
+ BUILTIN_PROFILE_NAME_DEFAULT : DEFAULT_PROFILE,
+ # BUILTIN_PROFILE_NAME_PROD : BUILTIN_PROFILE_NAME_PLANET_USER,
+ # BUILTIN_PROFILE_NAME_PROD_M2M : BUILTIN_PROFILE_NAME_PLANET_M2M,
+ # BUILTIN_PROFILE_NAME_PROD_AUTH0 : BUILTIN_PROFILE_NAME_PLANET_USER,
+ # BUILTIN_PROFILE_NAME_PROD_SENTINEL_HUB : BUILTIN_PROFILE_NAME_PLANET_M2M,
+ }
+ _builtin_profile_default_by_client_type = {
+ "oidc_device_code" : BUILTIN_PROFILE_NAME_PLANET_USER,
+ "oidc_auth_code" : BUILTIN_PROFILE_NAME_PLANET_USER,
+ "oidc_client_credentials_secret" : BUILTIN_PROFILE_NAME_PLANET_M2M,
+ "planet_legacy" : BUILTIN_PROFILE_NAME_LEGACY,
+ }
+ _builtin_trust_realms: Dict[str, Optional[List[dict]]] = {
+ "PRODUCTION": _ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITIES,
+ "CUSTOM": None,
+ }
+ # fmt: on
+
+ def builtin_client_authclient_config_dicts(self) -> Dict[str, dict]:
+ return self._builtin_profile_auth_client_configs
+
+ def builtin_client_profile_aliases(self) -> Dict[str, str]:
+ return self._builtin_profile_aliases
+
+ def builtin_default_profile_by_client_type(self) -> Dict[str, str]:
+ pass
+
+ def builtin_default_profile(self) -> str:
+ return self.BUILTIN_PROFILE_NAME_DEFAULT
+
+ def builtin_trust_environment_names(self) -> List[str]:
+ return list(_BuiltinConfigurationProvider._builtin_trust_realms.keys())
+
+ def builtin_trust_environments(self) -> Dict[str, Optional[List[dict]]]:
+ return _BuiltinConfigurationProvider._builtin_trust_realms
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 3a666974..15016fa8 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -55,15 +55,15 @@ def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret
def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
- # planet-auth library Auth type
- ctx.obj['AUTH'] = planet_auth_utils.ProfileManager.initialize_auth_client_context(
+ # planet-auth library Auth context type
+ ctx.obj['AUTH'] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_profile_opt=auth_profile,
auth_client_id_opt=auth_client_id,
auth_client_secret_opt=auth_client_secret,
auth_api_key_opt=auth_api_key,
)
- # planet SDK Auth type
+ # planet SDK Auth context type
ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(pl_authlib_context=ctx.obj['AUTH'])
From a9ddd358c4d11f81f5c436da6103085999966ba5 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 30 Nov 2024 09:05:31 -0800
Subject: [PATCH 12/81] update comments
---
planet/auth.py | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index abeb3890..06a69c83 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -69,7 +69,10 @@ def from_file(
# file to only hold an API key (planet_auth_utils now can use it for
# other things, too). API keys will be deprecated for most use cases,
# and user login will be different from service account login under
- # OAuth.
+ # OAuth. A user interactive OAuth client configuration that has been
+ # initialized with a refresh token should function similarly, but is
+ # different enough I do not think it should be shoehorned into this
+ # method.
warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
**_ProductionEnv.LEGACY_AUTH_AUTHORITY,
@@ -111,9 +114,16 @@ def from_login(email: str,
"""
# TODO: Need to provide instructions on what an application should do.
# It would not be hard to add username/password support to the
- # PlanetAuthFactory, but we should encourage an OAuth login.
- # At a code level, we should provide "from_oauth_m2m" (Done) and something
- # to use a user profile, that must be initialized interactively.
+ # PlanetAuthFactory and return Auth context initialized with
+ # the legacy protocol and API key, but we should encourage an
+ # OAuth login.
+ # At a code level, we should provide "from_oauth_m2m()" (Done)
+ # and something to use a user profile, which must be initialized
+ # interactively. from_oauth_user(profile_name) seems reasonable,
+ # leaving the question of how to create and initialize non-built-in
+ # profiles. (The plauth CLI and planet_auth library has code to
+ # do this, but I don't know if we should send users of the SDK
+ # to another SDK for the simple use cases.)
warnings.warn("Auth.from_login() has been deprecated.", DeprecationWarning)
raise DeprecationWarning("Auth.from_login() has been deprecated.")
From c6d6e74040b33ae745e7948b900d03e5fc443997 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 30 Nov 2024 09:07:06 -0800
Subject: [PATCH 13/81] update comments
---
planet/auth.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 06a69c83..6aa43263 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -121,9 +121,9 @@ def from_login(email: str,
# and something to use a user profile, which must be initialized
# interactively. from_oauth_user(profile_name) seems reasonable,
# leaving the question of how to create and initialize non-built-in
- # profiles. (The plauth CLI and planet_auth library has code to
+ # profiles. The plauth CLI and planet_auth library has code to
# do this, but I don't know if we should send users of the SDK
- # to another SDK for the simple use cases.)
+ # to another SDK for the simple use cases.
warnings.warn("Auth.from_login() has been deprecated.", DeprecationWarning)
raise DeprecationWarning("Auth.from_login() has been deprecated.")
From 834d9506864fe33db07699200b542b39827ed14d Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 30 Nov 2024 09:33:01 -0800
Subject: [PATCH 14/81] update comments
---
planet/auth.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/planet/auth.py b/planet/auth.py
index 6aa43263..4a7ad9fa 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -121,7 +121,8 @@ def from_login(email: str,
# and something to use a user profile, which must be initialized
# interactively. from_oauth_user(profile_name) seems reasonable,
# leaving the question of how to create and initialize non-built-in
- # profiles. The plauth CLI and planet_auth library has code to
+ # profiles. (Note: "profile" doesn't imply "OAuth user
+ # interactive".) The plauth CLI and planet_auth library has code to
# do this, but I don't know if we should send users of the SDK
# to another SDK for the simple use cases.
warnings.warn("Auth.from_login() has been deprecated.", DeprecationWarning)
From 6085d70e8ef4814a74ea3d0387591e50178d3bbd Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 3 Dec 2024 21:17:12 -0800
Subject: [PATCH 15/81] fix env vars
---
planet/auth_builtins.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 9487aefe..d4b656a0 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -16,7 +16,7 @@
from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
# Needs to be set at runtime (not necessarily at import time) for dependency injection to planet_auth_util
-os.environ["PL_BUILTIN_AUTH_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+os.environ["PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
class _ProductionEnv:
PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0 = {
From 947b103822f0de05b1263fe054cf1b4a7cfbd65a Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 4 Dec 2024 16:13:33 -0800
Subject: [PATCH 16/81] fix builtins
---
planet/auth_builtins.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index d4b656a0..688dd0ae 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -142,7 +142,7 @@ def builtin_client_profile_aliases(self) -> Dict[str, str]:
return self._builtin_profile_aliases
def builtin_default_profile_by_client_type(self) -> Dict[str, str]:
- pass
+ return self._builtin_profile_default_by_client_type
def builtin_default_profile(self) -> str:
return self.BUILTIN_PROFILE_NAME_DEFAULT
From f9ac78796491f97861807ce7449af0ee93ebbe08 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 4 Dec 2024 16:13:55 -0800
Subject: [PATCH 17/81] let cli.py be run as a module
---
planet/cli/cli.py | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 15016fa8..c3fe7ee0 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -99,3 +99,7 @@ def _configure_logging(verbosity):
main.add_command(orders.orders) # type: ignore
main.add_command(subscriptions.subscriptions) # type: ignore
main.add_command(collect.collect) # type: ignore
+
+
+if __name__ == "__main__":
+ main() # pylint: disable=E1120
From 19f2a445f17e731fcf83a9a6e49aa122794b58f3 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Sat, 21 Dec 2024 18:22:58 -0800
Subject: [PATCH 18/81] I don't think we need a profile literally named
'default'
---
planet/auth_builtins.py | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 688dd0ae..b96fcfb3 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -102,7 +102,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
##
## Default that should be used when no other selection has been made
##
- DEFAULT_PROFILE = BUILTIN_PROFILE_NAME_PLANET_USER
+ # DEFAULT_PROFILE = BUILTIN_PROFILE_NAME_PLANET_USER
_builtin_profile_auth_client_configs = {
## OAuth Client Configs
@@ -117,7 +117,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
}
_builtin_profile_aliases = {
- BUILTIN_PROFILE_NAME_DEFAULT : DEFAULT_PROFILE,
+ # BUILTIN_PROFILE_NAME_DEFAULT : DEFAULT_PROFILE,
# BUILTIN_PROFILE_NAME_PROD : BUILTIN_PROFILE_NAME_PLANET_USER,
# BUILTIN_PROFILE_NAME_PROD_M2M : BUILTIN_PROFILE_NAME_PLANET_M2M,
# BUILTIN_PROFILE_NAME_PROD_AUTH0 : BUILTIN_PROFILE_NAME_PLANET_USER,
@@ -145,7 +145,8 @@ def builtin_default_profile_by_client_type(self) -> Dict[str, str]:
return self._builtin_profile_default_by_client_type
def builtin_default_profile(self) -> str:
- return self.BUILTIN_PROFILE_NAME_DEFAULT
+ # return self.BUILTIN_PROFILE_NAME_DEFAULT
+ return self.BUILTIN_PROFILE_NAME_PLANET_USER
def builtin_trust_environment_names(self) -> List[str]:
return list(_BuiltinConfigurationProvider._builtin_trust_realms.keys())
From f08cdd8d976f360304cbbd8dd985034b7029d2d1 Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Tue, 31 Dec 2024 09:13:23 -0800
Subject: [PATCH 19/81] working on integration
---
Branch-Working-and-Release-Notes.txt | 2 +-
planet/auth.py | 174 ++++++++++++++++++---------
planet/auth_builtins.py | 6 +-
planet/cli/session.py | 13 +-
planet/constants.py | 2 +-
planet/http.py | 8 +-
pyproject.toml | 1 +
setup.cfg | 2 +-
tests/conftest.py | 16 ---
tests/integration/test_auth_api.py | 77 ------------
tests/integration/test_auth_cli.py | 123 -------------------
tests/pytest.ini | 4 -
tests/unit/test_auth.py | 107 ++++++++--------
tests/unit/test_cli_session.py | 40 ++----
14 files changed, 201 insertions(+), 374 deletions(-)
delete mode 100644 tests/integration/test_auth_api.py
delete mode 100644 tests/integration/test_auth_cli.py
delete mode 100644 tests/pytest.ini
diff --git a/Branch-Working-and-Release-Notes.txt b/Branch-Working-and-Release-Notes.txt
index ed7d2da1..1ac8a82f 100644
--- a/Branch-Working-and-Release-Notes.txt
+++ b/Branch-Working-and-Release-Notes.txt
@@ -4,5 +4,5 @@
- planet auth init -> planet auth oauth login (or, planet --auth-profile legacy auth legacy login)
- planet auth value -> planet plauth oauth print-access-token (or planet --auth-profile legacy auth legacy print-api-key)
- The legacy secret file has largely been deprecated. This will require a user migration.
-
+# TODO: hide command line options not needed for the SDK (Maybe bring back a simpler built-in auth command)
# TODO: we need to allocate a client ID for the `planet` CLI. We are presently leaning on plauth's client ID. (maybe this is OK)
diff --git a/planet/auth.py b/planet/auth.py
index 4a7ad9fa..a8a3947e 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -25,17 +25,80 @@
import planet_auth_utils
from .constants import SECRET_FILE_PATH
-from .auth_builtins import _ProductionEnv
+from .auth_builtins import _ProductionEnv, _BuiltinConfigurationProvider
+from .exceptions import PlanetError
AuthType = httpx.Auth
# planet_auth and planet_auth_utils code more or less entirely
# supersedes this class. But, keeping this here for
-# now for interface stability to bridge with the rest of the SDK.
+# now for interface stability and to bridge with the rest of the SDK.
class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
+ @staticmethod
+ def from_defaults():
+ """
+ Create authentication from defaults. Defaults are processed by the
+ underlying planet_auth and planet_auth_utils libraries, and take into
+ account environment variables (highest priority), configuration saved
+ to `~/.planet.json` (next priority), and built-in defaults (lowest
+ priority).
+
+ Environment Variables:
+ PL_AUTH_PROFILE: Specify a custom planet_auth auth client profile
+ (Advanced use cases)
+ PL_AUTH_CLIENT_ID: Specify an OAuth2 M2M client ID
+ PL_AUTH_CLIENT_SECRET: Specify an OAuth2 M2M client secret
+ PL_AUTH_API_KEY: Specify a legacy Planet API key
+
+ """
+ return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context())
+
+ @classmethod
+ def from_oauth_user_session(cls):
+ """
+ Create authentication for a user whose initialized login information
+ will be saved to `~/.planet.json` and `~/.planet/` user login.
+ A user should perform a login to initialize this session out-of-band
+ using the command `planet auth login`.
+
+ To initialize this session programmatically... TODO
+ """
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_PLANET_USER
+ )
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
+
+ @staticmethod
+ def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
+ """Create authentication from OAuth2 service account client ID and secret.
+
+ Parameters:
+ client_id: Planet service account client ID.
+ client_secret: Planet service account client secret.
+ """
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_client_id_opt=client_id,
+ auth_client_secret_opt=client_secret,
+ )
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
+
+ @staticmethod
+ def from_plauth(pl_authlib_context: planet_auth.Auth):
+ """
+ Create authentication from the provided Planet Auth Library
+ Authentication Context. Generally, applications will want to use one
+ of the Auth Library factory helpers to construct this context (See the
+ factory class).
+
+ This method is intended for advanced use cases where the developer
+ as their own client ID registered. (A feature of the Planet Platform
+ not yet released to the public as of January 2025.)
+ """
+ return _PLAuthLibAuth(plauth=pl_authlib_context)
+
@staticmethod
def from_key(key: str) -> AuthType:
"""Obtain authentication from api key.
@@ -43,9 +106,12 @@ def from_key(key: str) -> AuthType:
Parameters:
key: Planet API key
"""
- warnings.warn("Planet API keys will be deprecated at some point."
+ warnings.warn("Planet API keys will be deprecated for most use cases."
" Initialize an OAuth client, or create an OAuth service account."
" Proceeding for now.", PendingDeprecationWarning)
+ if not key:
+ raise APIKeyAuthException('API key cannot be empty.')
+
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_api_key_opt=key,
save_token_file=False,
@@ -57,43 +123,60 @@ def from_file(
filename: typing.Optional[typing.Union[str, pathlib.Path]] = None) -> AuthType:
"""Create authentication from secret file.
- The secret file is named `.planet.json` and is stored in the user
+ The default secret file is named `.planet.json` and is stored in the user
directory. The file has a special format and should have been created
with `Auth.write()`.
+ Pending deprecation:
+ OAuth2, which should replace API keys in most cases does not have
+ a direct replacement for "from_file()" in many cases.
+ The format of the `.planet.json file` is changing with the
+ migration of Planet APIs to OAuth2. With that, this method is
+ also being deprecated as a means to bootstrap auth configuration
+ with a simple API key. For the time being this method will still
+ be supported, but this method will fail if the file is present
+ with only new configuration fields, and lacks the legacy API key
+ field.
+
Parameters:
filename: Alternate path for the planet secret file.
"""
- # There is no direct replacement for "from_file()", which expected the
- # file to only hold an API key (planet_auth_utils now can use it for
- # other things, too). API keys will be deprecated for most use cases,
- # and user login will be different from service account login under
- # OAuth. A user interactive OAuth client configuration that has been
- # initialized with a refresh token should function similarly, but is
- # different enough I do not think it should be shoehorned into this
- # method.
- warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
+ warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
**_ProductionEnv.LEGACY_AUTH_AUTHORITY,
"client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config,
token_file=filename or SECRET_FILE_PATH)
+ #planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ # auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
+ # token_file_opt=filename or SECRET_FILE_PATH
+ #)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
- """Create authentication from environment variable.
+ """Create authentication from environment variables.
Reads the `PL_API_KEY` environment variable
+ Pending Deprecation:
+ This method is pending deprecation. The method `from_defaults()`
+ considers environment variables and configuration files through
+ the planet_auth and planet_auth_utils libraries, and works with
+ legacy API keys, OAuth2 M2M clients, OAuth2 interactive profiles.
+ This method should be used in most cases as a replacement.
+
Parameters:
variable_name: Alternate environment variable.
"""
- # TODO: we should consider how we want to expose initialization
- # from the ENV for OAuth M2M
- variable_name = variable_name or planet_auth.EnvironmentVariables.AUTH_API_KEY
+ warnings.warn(
+ "from_env() will be deprecated. Use from_defaults() in most"
+ " cases, which will consider environment variables.",
+ PendingDeprecationWarning
+ )
+ variable_name = variable_name or planet_auth_utils.EnvironmentVariables.AUTH_API_KEY
api_key = os.getenv(variable_name, None)
return Auth.from_key(api_key)
@@ -112,52 +195,35 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- # TODO: Need to provide instructions on what an application should do.
- # It would not be hard to add username/password support to the
- # PlanetAuthFactory and return Auth context initialized with
- # the legacy protocol and API key, but we should encourage an
- # OAuth login.
- # At a code level, we should provide "from_oauth_m2m()" (Done)
- # and something to use a user profile, which must be initialized
- # interactively. from_oauth_user(profile_name) seems reasonable,
- # leaving the question of how to create and initialize non-built-in
- # profiles. (Note: "profile" doesn't imply "OAuth user
- # interactive".) The plauth CLI and planet_auth library has code to
- # do this, but I don't know if we should send users of the SDK
- # to another SDK for the simple use cases.
- warnings.warn("Auth.from_login() has been deprecated.", DeprecationWarning)
- raise DeprecationWarning("Auth.from_login() has been deprecated.")
+ warnings.warn("Auth.from_login() has been deprecated. Use Auth.from_user_session().", DeprecationWarning)
+ raise DeprecationWarning("Auth.from_login() has been deprecated. Use Auth.from_user_session().")
- @staticmethod
- def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
- """Create authentication from OAuth service account client ID and secret.
+ @classmethod
+ def from_dict(cls, data: dict) -> AuthType:
+ raise DeprecationWarning("Auth.from_dict() has been deprecated.")
- Parameters:
- client_id: Planet service account client ID.
- client_secret: Planet service account client secret.
- """
- pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_client_id_opt=client_id,
- auth_client_secret_opt=client_secret,
- )
- return _PLAuthLibAuth(plauth=pl_authlib_context)
+ def to_dict(self) -> dict:
+ raise DeprecationWarning("Auth.to_dict() has been deprecated.")
- @staticmethod
- def from_plauth(pl_authlib_context: planet_auth.Auth):
- """
- Create authentication from the provided Planet Auth Library Authentication Context.
- Generally, applications will want to use one of the Auth Library helpers to
- construct this context (See the factory class).
- """
- return _PLAuthLibAuth(plauth=pl_authlib_context)
+ def store(self, filename: typing.Optional[typing.Union[str, pathlib.Path]] = None):
+ warnings.warn("Auth.store() has been deprecated.", DeprecationWarning)
+ raise DeprecationWarning("Auth.store() has been deprecated.")
+
+ @property
+ def value(self):
+ raise DeprecationWarning("Auth.value has been deprecated.")
+
+class APIKeyAuthException(PlanetError):
+ """exceptions thrown by APIKeyAuth"""
+ pass
class _PLAuthLibAuth(Auth, AuthType):
# The Planet Auth Library uses a "has a" authenticator pattern for its
# planet_auth.Auth context class. This SDK library employs a "is a"
# authenticator design pattern for user's of its Auth context obtained
- # from the constructors above. This class smooths over that design
- # difference as we move to using the Planet Auth Library.
+ # from the constructors above. This class partially smooths over that
+ # design difference as we move to using the Planet Auth Library.
def __init__(self, plauth: planet_auth.Auth):
self._plauth = plauth
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index b96fcfb3..4cc87ee8 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -96,8 +96,8 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
##
## Misc auth profiles
##
- BUILTIN_PROFILE_NAME_NONE = "none"
- BUILTIN_PROFILE_NAME_DEFAULT = "default"
+ # BUILTIN_PROFILE_NAME_NONE = "none"
+ # BUILTIN_PROFILE_NAME_DEFAULT = "default"
##
## Default that should be used when no other selection has been made
@@ -113,7 +113,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_LEGACY : _LEGACY_AUTH_CLIENT_CONFIG__PROD,
# Misc
- BUILTIN_PROFILE_NAME_NONE : _NOOP_AUTH_CLIENT_CONFIG,
+ # BUILTIN_PROFILE_NAME_NONE : _NOOP_AUTH_CLIENT_CONFIG,
}
_builtin_profile_aliases = {
diff --git a/planet/cli/session.py b/planet/cli/session.py
index 58b699a4..8c1d3f6f 100644
--- a/planet/cli/session.py
+++ b/planet/cli/session.py
@@ -1,12 +1,19 @@
"""CLI HTTP/auth sessions."""
-from planet.auth import Auth
from planet.http import Session
class CliSession(Session):
"""Session with CLI-specific auth and identifying header"""
- def __init__(self, ctx):
- super().__init__(ctx.obj['PLSDK_AUTH'])
+ def __init__(self, click_ctx=None, plsdk_auth=None):
+ if click_ctx:
+ _plsdk_auth = click_ctx.obj['PLSDK_AUTH']
+ else:
+ _plsdk_auth = None
+
+ if plsdk_auth:
+ _plsdk_auth = plsdk_auth
+
+ super().__init__(_plsdk_auth)
self._client.headers.update({'X-Planet-App': 'python-cli'})
diff --git a/planet/constants.py b/planet/constants.py
index d6610942..67c0029a 100644
--- a/planet/constants.py
+++ b/planet/constants.py
@@ -22,4 +22,4 @@
PLANET_BASE_URL = 'https://api.planet.com'
-SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json' # TODO: deprecate in favor of planet_auth library
+SECRET_FILE_PATH = Path(os.path.expanduser('~')) / '.planet.json'
diff --git a/planet/http.py b/planet/http.py
index f16e8cda..fdcac045 100644
--- a/planet/http.py
+++ b/planet/http.py
@@ -238,13 +238,7 @@ def __init__(self, auth: Optional[AuthType] = None):
auth: Planet server authentication.
"""
if auth is None:
- # Try getting credentials from environment before checking
- # in the secret file, this is the conventional order (AWS
- # CLI, for example.)
- try:
- auth = Auth.from_env()
- except exceptions.PlanetError:
- auth = Auth.from_file()
+ auth = Auth.from_defaults()
LOGGER.info(f'Session read timeout set to {READ_TIMEOUT}.')
timeout = httpx.Timeout(10.0, read=READ_TIMEOUT)
diff --git a/pyproject.toml b/pyproject.toml
index 3ea30205..dd79388c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,6 +38,7 @@ test = [
"anyio",
"pytest-cov",
"respx>=0.20",
+ "coverage[toml]"
]
lint = [
"flake8",
diff --git a/setup.cfg b/setup.cfg
index 1b13c075..b44843d0 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -9,7 +9,7 @@ exclude = examples, tests
[tool:pytest]
addopts =
- -rxXs
+ -v -rxXs --cov --cov-report=term
[coverage:run]
source = planet, tests
diff --git a/tests/conftest.py b/tests/conftest.py
index 028cb17d..7ab488ce 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -18,26 +18,10 @@
import pytest
-from planet.auth import _SecretFile
-
_here = Path(os.path.abspath(os.path.dirname(__file__)))
_test_data_path = _here / 'data'
-@pytest.fixture(autouse=True, scope='module')
-def test_secretfile_read():
- """Returns valid auth results as if reading a secret file"""
-
- def mockreturn(self):
- return {'key': 'testkey'}
-
- # monkeypatch fixture is not available above a function scope
- # usage: https://docs.pytest.org/en/6.2.x/reference.html#pytest.MonkeyPatch
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(_SecretFile, 'read', mockreturn)
- yield
-
-
@pytest.fixture
def open_test_img():
img_path = _test_data_path / 'test_sm.tif'
diff --git a/tests/integration/test_auth_api.py b/tests/integration/test_auth_api.py
deleted file mode 100644
index ee8be11b..00000000
--- a/tests/integration/test_auth_api.py
+++ /dev/null
@@ -1,77 +0,0 @@
-# Copyright 2021 Planet Labs PBC.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not
-# use this file except in compliance with the License. You may obtain a copy of
-# the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations under
-# the License.
-from http import HTTPStatus
-import logging
-
-import httpx
-import jwt
-import pytest
-import respx
-
-from planet import exceptions
-from planet.auth import AuthClient
-
-TEST_URL = 'http://MockNotRealURL/api/path'
-TEST_LOGIN_URL = f'{TEST_URL}/login'
-
-LOGGER = logging.getLogger(__name__)
-
-
-@respx.mock
-def test_AuthClient_success():
- payload = {'api_key': 'iamakey'}
- resp = {'token': jwt.encode(payload, 'key')}
- mock_resp = httpx.Response(HTTPStatus.OK, json=resp)
- respx.post(TEST_LOGIN_URL).return_value = mock_resp
-
- cl = AuthClient(base_url=TEST_URL)
- auth_data = cl.login('email', 'password')
-
- assert auth_data == payload
-
-
-@respx.mock
-def test_AuthClient_invalid_email():
- resp = {
- "errors": {
- "email": ["Not a valid email address."]
- },
- "message": "error validating request against UserAuthenticationSchema",
- "status": 400,
- "success": False
- }
- mock_resp = httpx.Response(400, json=resp)
- respx.post(TEST_LOGIN_URL).return_value = mock_resp
-
- cl = AuthClient(base_url=TEST_URL)
- with pytest.raises(exceptions.APIError,
- match='Not a valid email address.'):
- _ = cl.login('email', 'password')
-
-
-@respx.mock
-def test_AuthClient_invalid_password():
- resp = {
- "errors": None,
- "message": "Invalid email or password",
- "status": 401,
- "success": False
- }
- mock_resp = httpx.Response(401, json=resp)
- respx.post(TEST_LOGIN_URL).return_value = mock_resp
-
- cl = AuthClient(base_url=TEST_URL)
- with pytest.raises(exceptions.APIError,
- match='Incorrect email or password.'):
- _ = cl.login('email', 'password')
diff --git a/tests/integration/test_auth_cli.py b/tests/integration/test_auth_cli.py
deleted file mode 100644
index 62fbd356..00000000
--- a/tests/integration/test_auth_cli.py
+++ /dev/null
@@ -1,123 +0,0 @@
-# Copyright 2022 Planet Labs PBC.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not
-# use this file except in compliance with the License. You may obtain a copy of
-# the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations under
-# the License.
-from http import HTTPStatus
-import json
-import os
-
-from click.testing import CliRunner
-import httpx
-import jwt
-import pytest
-import respx
-
-from planet.cli import cli
-
-TEST_URL = 'http://MockNotRealURL/api/path'
-TEST_LOGIN_URL = f'{TEST_URL}/login'
-
-
-# skip the global mock of _SecretFile.read
-# for this module
-@pytest.fixture(autouse=True, scope='module')
-def test_secretfile_read():
- return
-
-
-@pytest.fixture
-def redirect_secretfile(tmp_path):
- """patch the cli so it works with a temporary secretfile
-
- this is to avoid collisions with the actual planet secretfile
- """
- secretfile_path = tmp_path / 'secret.json'
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(cli.auth.planet.auth, 'SECRET_FILE_PATH', secretfile_path)
- yield secretfile_path
-
-
-@respx.mock
-def test_cli_auth_init_success(redirect_secretfile):
- """Test the successful auth init path
-
- Also tests the base-url command, since we will get an exception
- if the base url is not changed to the mocked url
- """
- payload = {'api_key': 'test_cli_auth_init_success_key'}
- resp = {'token': jwt.encode(payload, 'key')}
- mock_resp = httpx.Response(HTTPStatus.OK, json=resp)
- respx.post(TEST_LOGIN_URL).return_value = mock_resp
-
- result = CliRunner().invoke(cli.main,
- args=['auth', '--base-url', TEST_URL, 'init'],
- input='email\npw\n')
-
- # we would get a 'url not mocked' exception if the base url wasn't
- # changed to the mocked url
- assert not result.exception
-
- assert 'Initialized' in result.output
-
-
-@respx.mock
-def test_cli_auth_init_bad_pw(redirect_secretfile):
- resp = {
- "errors": None,
- "message": "Invalid email or password",
- "status": 401,
- "success": False
- }
- mock_resp = httpx.Response(401, json=resp)
- respx.post(TEST_LOGIN_URL).return_value = mock_resp
-
- result = CliRunner().invoke(cli.main,
- args=['auth', '--base-url', TEST_URL, 'init'],
- input='email\npw\n')
-
- assert result.exception
- assert 'Error: Incorrect email or password.\n' in result.output
-
-
-def test_cli_auth_value_success(redirect_secretfile):
- key = 'test_cli_auth_value_success_key'
- content = {'key': key}
- with open(redirect_secretfile, 'w') as f:
- json.dump(content, f)
-
- result = CliRunner().invoke(cli.main, ['auth', 'value'])
- assert not result.exception
- assert result.output == f'{key}\n'
-
-
-def test_cli_auth_value_failure(redirect_secretfile):
- result = CliRunner().invoke(cli.main, ['auth', 'value'])
- 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'}
diff --git a/tests/pytest.ini b/tests/pytest.ini
deleted file mode 100644
index cd8c265e..00000000
--- a/tests/pytest.ini
+++ /dev/null
@@ -1,4 +0,0 @@
-[pytest]
-log_cli = True
-log_format = %(asctime)s %(levelname)s %(message)s
-log_date_format = %Y-%m-%d %H:%M:%S
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 51ce8f41..1250807f 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -18,6 +18,7 @@
import pytest
from planet import auth
+import planet_auth
LOGGER = logging.getLogger(__name__)
@@ -37,8 +38,11 @@ def secret_path(monkeypatch, tmp_path):
def test_Auth_from_key():
- test_auth_env1 = auth.Auth.from_key('testkey')
- assert test_auth_env1.value == 'testkey'
+ test_auth_env1 = auth.Auth.from_key('testkey_from_key')
+ # We know that planet_auth instantiates an in memory "static API key" auth client.
+ # test_api_key = test_auth_env1._plauth.request_authenticator().credential().legacy_api_key()
+ test_api_key = test_auth_env1._plauth.request_authenticator().credential().api_key()
+ assert test_api_key == 'testkey_from_key'
def test_Auth_from_key_empty():
@@ -48,43 +52,50 @@ def test_Auth_from_key_empty():
def test_Auth_from_file(secret_path):
with open(secret_path, 'w') as fp:
- fp.write('{"key": "testvar"}')
+ fp.write('{"key": "testvar_from_file"}')
test_auth = auth.Auth.from_file()
- assert test_auth.value == 'testvar'
+ # We know that planet_auth instantiates a "Legacy" auth client.
+ test_api_key = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ # test_api_key = test_auth._plauth.request_authenticator().credential().api_key()
+ assert test_api_key == 'testvar_from_file'
def test_Auth_from_file_doesnotexist(secret_path):
- with pytest.raises(auth.AuthException):
- _ = auth.Auth.from_file(secret_path)
-
+ test_auth = auth.Auth.from_file(secret_path)
+ with pytest.raises(FileNotFoundError):
+ _ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
def test_Auth_from_file_wrongformat(secret_path):
with open(secret_path, 'w') as fp:
- fp.write('{"notkey": "testvar"}')
+ fp.write('{"notkey": "testvar_wrong_format"}')
+ test_auth = auth.Auth.from_file(secret_path)
+ with pytest.raises(planet_auth.InvalidDataException):
+ _ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
- with pytest.raises(auth.AuthException):
- _ = auth.Auth.from_file(secret_path)
def test_Auth_from_file_alternate(tmp_path):
secret_path = str(tmp_path / '.test')
with open(secret_path, 'w') as fp:
- fp.write('{"key": "testvar"}')
+ fp.write('{"key": "testvar_alt_path"}')
test_auth = auth.Auth.from_file(secret_path)
- assert test_auth.value == 'testvar'
+ test_api_key = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ assert test_api_key == 'testvar_alt_path'
def test_Auth_from_env(monkeypatch):
- monkeypatch.setenv('PL_API_KEY', 'testkey')
+ monkeypatch.setenv('PL_API_KEY', 'testkey_env')
test_auth_env = auth.Auth.from_env()
- assert test_auth_env.value == 'testkey'
+ # TODO: that I short cicuit between legacy and API key auth impls makes this weird.
+ test_api_key = test_auth_env._plauth.request_authenticator().credential().api_key()
+ assert test_api_key == 'testkey_env'
def test_Auth_from_env_failure(monkeypatch):
monkeypatch.delenv('PL_API_KEY', raising=False)
- with pytest.raises(auth.AuthException):
+ with pytest.raises(auth.APIKeyAuthException):
_ = auth.Auth.from_env()
@@ -94,7 +105,9 @@ def test_Auth_from_env_alternate_success(monkeypatch):
monkeypatch.delenv('PL_API_KEY', raising=False)
test_auth_env = auth.Auth.from_env(alternate)
- assert test_auth_env.value == 'testkey'
+ test_api_key = test_auth_env._plauth.request_authenticator().credential().api_key()
+
+ assert test_api_key == 'testkey'
def test_Auth_from_env_alternate_doesnotexist(monkeypatch):
@@ -102,55 +115,41 @@ def test_Auth_from_env_alternate_doesnotexist(monkeypatch):
monkeypatch.delenv(alternate, raising=False)
monkeypatch.delenv('PL_API_KEY', raising=False)
- with pytest.raises(auth.AuthException):
+ with pytest.raises(auth.APIKeyAuthException):
_ = auth.Auth.from_env(alternate)
def test_Auth_from_login(monkeypatch):
auth_data = 'authdata'
- def login(*args, **kwargs):
- return {'api_key': auth_data}
-
- monkeypatch.setattr(auth.AuthClient, 'login', login)
-
- test_auth = auth.Auth.from_login('email', 'pw')
- assert test_auth.value == auth_data
-
+ # auth.AuthClient has been completely removed
+ # in the conversion to planet_auth
+ # def login(*args, **kwargs):
+ # return {'api_key': auth_data}
+ #
+ # monkeypatch.setattr(auth.AuthClient, 'login', login)
+ with pytest.raises(DeprecationWarning):
+ test_auth = auth.Auth.from_login('email', 'pw')
-def test_Auth_store_doesnotexist(tmp_path):
- test_auth = auth.Auth.from_key('test')
- secret_path = str(tmp_path / '.test')
- test_auth.store(secret_path)
-
- with open(secret_path, 'r') as fp:
- assert json.loads(fp.read()) == {"key": "test"}
+def test_auth_value_deprecated():
+ with pytest.raises(DeprecationWarning):
+ test_auth = auth.Auth.from_key("test_deprecated_key")
+ _ = test_auth.value
-def test_Auth_store_exists(tmp_path):
- secret_path = str(tmp_path / '.test')
-
- with open(secret_path, 'w') as fp:
- fp.write('{"existing": "exists"}')
- test_auth = auth.Auth.from_key('test')
- test_auth.store(secret_path)
+def test_auth_store_deprecated():
+ with pytest.raises(DeprecationWarning):
+ test_auth = auth.Auth.from_key("test_deprecated_key")
+ test_auth.store()
- with open(secret_path, 'r') as fp:
- assert json.loads(fp.read()) == {"key": "test", "existing": "exists"}
+def test_auth_to_dict_deprecated():
+ with pytest.raises(DeprecationWarning):
+ test_auth = auth.Auth.from_key("test_deprecated_key")
+ _ = test_auth.to_dict()
-def test__SecretFile_permissions_doesnotexist(secret_path):
- """No exception is raised if the file doesn't exist"""
- auth._SecretFile(secret_path)
-
-
-def test__SecretFile_permissions_incorrect(secret_path):
- """Incorrect permissions are fixed"""
- with open(secret_path, 'w') as fp:
- fp.write('{"existing": "exists"}')
-
- secret_path.chmod(0o666)
- auth._SecretFile(secret_path)
- assert secret_path.stat().st_mode & 0o777 == 0o600
+def test_auth_from_dict_deprecated():
+ with pytest.raises(DeprecationWarning):
+ _ = auth.Auth.from_dict({})
diff --git a/tests/unit/test_cli_session.py b/tests/unit/test_cli_session.py
index c4e95f23..2ac756eb 100644
--- a/tests/unit/test_cli_session.py
+++ b/tests/unit/test_cli_session.py
@@ -11,7 +11,6 @@
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.
-import base64
from http import HTTPStatus
import json
@@ -23,7 +22,6 @@
# from planet.auth import _SecretFile
from planet import auth
from planet.cli import session
-from planet.exceptions import AuthException
TEST_URL = 'mock://mock.com'
@@ -63,7 +61,8 @@ async def test_CliSession_headers(test_valid_secretfile):
@respx.mock
@pytest.mark.anyio
async def test_CliSession_auth_valid(test_valid_secretfile):
- async with session.CliSession() as sess:
+ # The default auth
+ async with session.CliSession(plsdk_auth=auth.Auth.from_key("clisessiontest")) as sess:
route = respx.get(TEST_URL)
route.return_value = httpx.Response(HTTPStatus.OK)
@@ -71,30 +70,11 @@ async def test_CliSession_auth_valid(test_valid_secretfile):
# the proper headers are included and they have the expected values
received_request = route.calls.last.request
- credentials = received_request.headers['authorization'].strip(
- 'Authorization: Basic ')
- assert base64.b64decode(credentials) == b'clisessiontest:'
-
-
-@respx.mock
-@pytest.mark.anyio
-async def test_CliSession_auth_invalid(tmp_path, monkeypatch):
- # write invalid secret file
- secret_path = f'{tmp_path}/secret.test'
- monkeypatch.setattr(auth, 'SECRET_FILE_PATH', secret_path)
- with open(secret_path, 'w') as fp:
- json.dump({'invalidkey': 'clisessiontest'}, fp)
-
- with pytest.raises(AuthException):
- session.CliSession()
-
-
-@respx.mock
-@pytest.mark.anyio
-async def test_CliSession_auth_nofile(tmp_path, monkeypatch):
- # point to non-existant file
- secret_path = f'{tmp_path}/doesnotexist.test'
- monkeypatch.setattr(auth, 'SECRET_FILE_PATH', secret_path)
-
- with pytest.raises(AuthException):
- session.CliSession()
+ # The planet_auth library sends the api key as bearer token.
+ # The older Planet SDK sent it as HTTP basic.
+ # Most Planet APIs accept either (and API keys are being deprecated.)
+ # credentials = received_request.headers['authorization'].strip(
+ # 'Authorization: Basic ')
+ # assert base64.b64decode(credentials) == b'clisessiontest:'
+ credentials = received_request.headers['authorization']
+ assert credentials == 'api-key clisessiontest'
From 2a96d01605d0ca0791ea7b71e7c40335c6d9f7fb Mon Sep 17 00:00:00 2001
From: carl-adams-planet <carl.adams@planet.com>
Date: Mon, 6 Jan 2025 08:30:16 -0800
Subject: [PATCH 20/81] holiday work
---
planet/auth.py | 15 +++++++++++++--
planet/auth_builtins.py | 34 ++++++++++++----------------------
2 files changed, 25 insertions(+), 24 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index a8a3947e..65ebb23c 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -57,14 +57,25 @@ def from_defaults():
return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context())
@classmethod
- def from_oauth_user_session(cls):
+ def from_oauth_user_session(cls): # TODO: take client ID? Rename to be CLI session specific?
"""
Create authentication for a user whose initialized login information
will be saved to `~/.planet.json` and `~/.planet/` user login.
A user should perform a login to initialize this session out-of-band
using the command `planet auth login`.
- To initialize this session programmatically... TODO
+ To initialize this session programmatically, you must complete an
+ OAuth2 user login flow. This involves initiating a request to the
+ authorization server, the user completing authentication using a
+ web browser out of process, and finalizing the authentication and
+ authorization in process and saving the session information that will
+ be used to make API requests.
+
+ Most properly, this process uses IDs that are specific to the
+ application. The exact process that should be used to complete
+ login is specific to the particulars of the application.
+
+ # TODO: double check app IDs registered to the CLI
"""
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_PLANET_USER
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 4cc87ee8..8ba9480d 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -38,6 +38,8 @@ class _ProductionEnv:
PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB,
]
+_SDK_CLIENT_ID_PROD = "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees"
+
_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
# The well known OIDC client that is the Planet Python CLI.
# Developers should register their own clients so that users may
@@ -45,7 +47,7 @@ class _ProductionEnv:
# also allows for application specific URLs or auth flow selection.
**_ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0,
"client_type": "oidc_device_code",
- "client_id": "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees",
+ "client_id": _SDK_CLIENT_ID_PROD,
"scopes": ["planet", "offline_access", "openid", "profile", "email"],
}
@@ -80,32 +82,24 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
## OAuth production environment profiles
##
# Real
+ # Using the client ID as a profile name is tricky...
+ # We normalize directory paths to lower case. The auth implementation uses
+ # mixed case ID strings. The odds of case normalized IDs colliding is low,
+ # but there is a bit of an off smell.
+ # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID = _SDK_CLIENT_ID_PROD
BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
# Aliases
- # BUILTIN_PROFILE_NAME_PROD = "prod"
- # BUILTIN_PROFILE_NAME_PROD_M2M = "prod-m2m"
- # BUILTIN_PROFILE_NAME_PROD_AUTH0 = "prod-auth0"
- # BUILTIN_PROFILE_NAME_PROD_SENTINEL_HUB = "prod-sentinel-hub"
+ # BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
##
## Profiles that use Planet's old (pre-OAuth) based auth protocol
##
- BUILTIN_PROFILE_NAME_LEGACY = "legacy"
-
- ##
- ## Misc auth profiles
- ##
- # BUILTIN_PROFILE_NAME_NONE = "none"
- # BUILTIN_PROFILE_NAME_DEFAULT = "default"
-
- ##
- ## Default that should be used when no other selection has been made
- ##
- # DEFAULT_PROFILE = BUILTIN_PROFILE_NAME_PLANET_USER
+ BUILTIN_PROFILE_NAME_LEGACY = "legacy"
_builtin_profile_auth_client_configs = {
## OAuth Client Configs
+ # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID : _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_USER : _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_M2M : _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
@@ -117,11 +111,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
}
_builtin_profile_aliases = {
- # BUILTIN_PROFILE_NAME_DEFAULT : DEFAULT_PROFILE,
- # BUILTIN_PROFILE_NAME_PROD : BUILTIN_PROFILE_NAME_PLANET_USER,
- # BUILTIN_PROFILE_NAME_PROD_M2M : BUILTIN_PROFILE_NAME_PLANET_M2M,
- # BUILTIN_PROFILE_NAME_PROD_AUTH0 : BUILTIN_PROFILE_NAME_PLANET_USER,
- # BUILTIN_PROFILE_NAME_PROD_SENTINEL_HUB : BUILTIN_PROFILE_NAME_PLANET_M2M,
+ # BUILTIN_PROFILE_ALIAS_PLANET_USER : BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID,
}
_builtin_profile_default_by_client_type = {
"oidc_device_code" : BUILTIN_PROFILE_NAME_PLANET_USER,
From 5ff942afb5f6434888aadb91d2e2f6fe906fcba3 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Thu, 9 Jan 2025 21:21:18 -0800
Subject: [PATCH 21/81] reviving auth command
---
planet/cli/auth.py | 86 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 86 insertions(+)
create mode 100644 planet/cli/auth.py
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
new file mode 100644
index 00000000..bb99d625
--- /dev/null
+++ b/planet/cli/auth.py
@@ -0,0 +1,86 @@
+# Copyright 2022 Planet Labs PBC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Auth API CLI"""
+import logging
+import os
+
+import click
+
+import planet_auth_utils
+
+import planet
+from .cmds import translate_exceptions
+
+ENV_API_KEY = "XXX"
+LOGGER = logging.getLogger(__name__)
+
+
+@click.group() # type: ignore
+@click.pass_context
+@click.option('-u',
+ '--base-url',
+ default=None,
+ help='Assign custom base Auth API URL.')
+def auth(ctx, base_url):
+ """Commands for working with Planet authentication"""
+ ctx.obj['BASE_URL'] = base_url
+
+
+@auth.command() # type: ignore
+@click.pass_context
+@translate_exceptions
+@click.option(
+ '--email',
+ default=None,
+ prompt=True,
+ help=('The email address associated with your Planet credentials.'))
+@click.password_option('--password',
+ confirmation_prompt=False,
+ help=('Account password. Will not be saved.'))
+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.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() # type: ignore
+@translate_exceptions
+def value():
+ """Print the stored authentication information"""
+ click.echo(planet.Auth.from_file().value)
+
+
+@auth.command() # type: ignore
+@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)')
+
+
+auth.add_command(name="print-api-key", cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
From 7a5c10bc385c3c7f6b73690189a902facd3c3d66 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 13 Jan 2025 23:00:42 -0800
Subject: [PATCH 22/81] depend on dev repo
---
pyproject.toml | 1 +
1 file changed, 1 insertion(+)
diff --git a/pyproject.toml b/pyproject.toml
index dd79388c..013afd0f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,6 +14,7 @@ dependencies = [
"pyjwt>=2.1",
"tqdm>=4.56",
"typing-extensions",
+ "planet-auth @ https://github.com/planetlabs/planet-auth-python/archive/refs/heads/carl/sdk-integration-work.zip"
]
readme = "README.md"
requires-python = ">=3.9"
From ea16e9f80e2fd1177d8cd26c06d7703a3bc9a27e Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Fri, 17 Jan 2025 16:54:21 -0800
Subject: [PATCH 23/81] working on plauth integration planet auth cli
---
.github/workflows/publish-pypi.yml | 2 +-
OAuth-Reviewer-and-Release-Notes.md | 54 ++++++++++++++
planet/cli/auth.py | 106 +++++++++++++++-------------
planet/cli/cli.py | 19 +++--
4 files changed, 125 insertions(+), 56 deletions(-)
create mode 100644 OAuth-Reviewer-and-Release-Notes.md
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
index 982b1ad6..32bec3e0 100644
--- a/.github/workflows/publish-pypi.yml
+++ b/.github/workflows/publish-pypi.yml
@@ -24,7 +24,7 @@ jobs:
restore-keys: |
${{ runner.os }}-pip
- - name: Build, verify, and upload to TestPyPI
+ - name: Build, verify, and upload to PyPI
run: |
pip install --upgrade nox
nox -s build publish_pypi
diff --git a/OAuth-Reviewer-and-Release-Notes.md b/OAuth-Reviewer-and-Release-Notes.md
new file mode 100644
index 00000000..b5180bc6
--- /dev/null
+++ b/OAuth-Reviewer-and-Release-Notes.md
@@ -0,0 +1,54 @@
+# Overview
+* Auth functions are now implemented by the `planet_auth` and
+ `planet_auth_utils` libraries
+* The use of API keys and Planet's legacy username/password based
+ authentication protocol is being phased out in favor of OAuth2 based
+ mechanisms. These legacy mechanisms remain in place for the time being,
+ but clients are encouraged to start adopting OAuth2.
+
+# Changes to the `planet auth` CLI command
+* Deprecated:
+ * The `planet auth init` command has been marked as deprecated, and will be
+ removed in a future release. The `planet auth init` command operates using
+ Planet's proprietary username/password based authentication protocol and
+ durable API keys. This protocol will be phased out in favor of OAuth2.
+ Use of durable API keys are discouraged in favor of time limited OAuth2
+ access tokens.
+ * The `planet auth store` command has been marked as deprecated, and will be
+ removed in a future release.
+ * The `planet auth value` command has been marked as deprecated, and will be
+ removed in a future release.
+* Replacements:
+ * The `planet auth login` command should replace both `planet auth init` for
+ initializing authentication for interactive CLI use, and `planet auth store`
+ for initializing authentication for other use cases. This command will
+ store OAuth2 access and refresh tokens and perform any other necessary
+ configuration.
+ * The `planet auth print-access-token` command provides a similar function
+ for obtaining current access tokens that can be used in scripted cases.
+* Additions:
+ * _Auth profiles_
+ * Auth profiles are a new addition to the Planet Client SDK, and come from
+ the underlying `planet_auth` library. Profiles encapsulate a number of
+ related auth concerns, and can be used to manage multiple client sessions
+ with separate identities or underlying protocol configurations.
+ * The Planet CLI provides a number of commands for manipulating profiles
+ geared for Planet CLI users and use cases:
+ * `planet auth profile-show`
+ * `planet auth profile-list`
+ * `planet auth profile-set`
+ * `plauth` - The `planet_auth_utils` library provides a separate, lower level
+ `plauth` command line utility for expert use cases.
+
+# Library API changes
+*
+
+# On-disk interface changes
+
+# Misc Notes
+* The interfaces for the `planet_auth` and `planet_auth_utils` libraries are
+ not currently considered to be as stable as the `planet` library.
+
+# Release Sequencing & Requirements
+* Planet APIs need to accept SH M2M tokens.
+* Users/Admins need a good way to register/manage M2M clients.
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index bb99d625..d5fdc777 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -13,74 +13,82 @@
# limitations under the License.
"""Auth API CLI"""
import logging
-import os
import click
+import planet_auth
import planet_auth_utils
import planet
from .cmds import translate_exceptions
+from ..auth_builtins import _BuiltinConfigurationProvider
-ENV_API_KEY = "XXX"
LOGGER = logging.getLogger(__name__)
@click.group() # type: ignore
@click.pass_context
-@click.option('-u',
- '--base-url',
- default=None,
- help='Assign custom base Auth API URL.')
-def auth(ctx, base_url):
+def auth(ctx):
"""Commands for working with Planet authentication"""
- ctx.obj['BASE_URL'] = base_url
+ # Override the default current_auth_context stored in ctx.obj["AUTH"]
+ # for legacy auth sub-commands. The planet_auth_utils library provides very
+ # generic utility commands, and the click commands it provides do not know
+ # about specific deployments. This library is specifically geared
+ # for the customer facing Planet Insights Platform, and provides
+ # built-in configurations for the public API surface area.
+ #
+ # We also employ bit of hackery to maintain old behavior - point
+ # FileBackedPlanetLegacyApiKey (the "Credential" or "token_file") to the
+ # ~/.planet.json file nominally used by PlanetAuthUserConfig. A common
+ # base class is used to model these separate use cases, and plays well
+ # with merged key sets. planet_auth_utils uses this file for more than
+ # just storing the API key, and nominally stores legacy API keys in a
+ # different location(s). This planet SDK historically only stored an
+ # API key in this file.
+ if (ctx.invoked_subcommand == "init"
+ or ctx.invoked_subcommand == "value"
+ or ctx.invoked_subcommand == "store"
+ ):
+ # click.echo("Overriding Auth Profile with legacy auth profile.")
+ ctx.obj["AUTH"] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
+ token_file_opt=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file()
+ )
-
-@auth.command() # type: ignore
-@click.pass_context
-@translate_exceptions
-@click.option(
- '--email',
- default=None,
- prompt=True,
- help=('The email address associated with your Planet credentials.'))
-@click.password_option('--password',
- confirmation_prompt=False,
- help=('Account password. Will not be saved.'))
-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.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() # type: ignore
-@translate_exceptions
-def value():
- """Print the stored authentication information"""
- click.echo(planet.Auth.from_file().value)
-
-
-@auth.command() # type: ignore
+@auth.command(name="store", deprecated=True) # type: ignore
@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)')
+ # See above. A bit of hackery around the token_file to maintain old interface.
+ token_file = planet_auth.FileBackedJsonObject(file_path=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file())
+ try :
+ token_file.load()
+ conf_data = token_file.data()
+ except FileNotFoundError:
+ conf_data = {}
+
+ conf_data["key"] = key
+ token_file.set_data(conf_data)
+ token_file.save()
+
+
+# We implement the "planet auth" sub-command in terms of the planet_auth_utils
+# click commands as much as we can.
+
+auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
+auth.add_command(name="print-access-token", cmd=planet_auth_utils.cmd_oauth_print_access_token)
+auth.add_command(name="profile-list", cmd=planet_auth_utils.cmd_profile_list)
+auth.add_command(name="profile-show", cmd=planet_auth_utils.cmd_profile_show)
+auth.add_command(name="profile-set", cmd=planet_auth_utils.cmd_profile_set)
+
+planet_auth_utils.cmd_pllegacy_login.name="init"
+planet_auth_utils.cmd_pllegacy_login.deprecated = True
+auth.add_command(name="init", cmd=planet_auth_utils.cmd_pllegacy_login)
+planet_auth_utils.cmd_pllegacy_print_api_key.name = "value"
+planet_auth_utils.cmd_pllegacy_print_api_key.deprecated = True
+auth.add_command(name="value", cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
-auth.add_command(name="print-api-key", cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
+# TODO: what do we want to expose to Planet SDK and CLI users around auth profiles?
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index c3fe7ee0..8bdd159d 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -21,7 +21,7 @@
import planet_auth_utils
import planet
-from . import cmds, collect, data, orders, subscriptions
+from . import auth, cmds, collect, data, orders, subscriptions
LOGGER = logging.getLogger(__name__)
@@ -37,10 +37,10 @@
default="warning",
help=("Optional: set verbosity level to warning, info, or debug.\
Defaults to warning."))
-@planet_auth_utils.opt_auth_profile
-@planet_auth_utils.opt_auth_client_id
-@planet_auth_utils.opt_auth_client_secret
-@planet_auth_utils.opt_auth_api_key
+@planet_auth_utils.opt_profile
+@planet_auth_utils.opt_client_id
+@planet_auth_utils.opt_client_secret
+@planet_auth_utils.opt_api_key
@cmds.translate_exceptions
def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
"""Planet SDK for Python CLI"""
@@ -93,8 +93,15 @@ def _configure_logging(verbosity):
level=log_level,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+# Hide the embedded util from help. It has many options and use cases that
+# may not be directly the most relevant or user-friendly for the specific
+# case of working against Planet Platform Services.
+# The interface we want to support for the SDK CLI is a specialized
+# subset defined by auth.py.
+planet_auth_utils.cmd_plauth_embedded.hidden=True
+main.add_command(cmd=planet_auth_utils.cmd_plauth_embedded, name="plauth") # type: ignore
-main.add_command(cmd=planet_auth_utils.embedded_plauth_cmd_group, name="auth") # type: ignore
+main.add_command(auth.auth) # type: ignore
main.add_command(data.data) # type: ignore
main.add_command(orders.orders) # type: ignore
main.add_command(subscriptions.subscriptions) # type: ignore
From 262db0c8c97429fdd53d0578b86f930599a78711 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 18 Jan 2025 09:12:46 -0800
Subject: [PATCH 24/81] formatting
---
planet/auth.py | 16 ++++++----
planet/auth_builtins.py | 69 ++++++++++++++++++-----------------------
planet/cli/auth.py | 13 +++-----
planet/cli/cli.py | 3 +-
tests/unit/test_auth.py | 7 ++---
5 files changed, 49 insertions(+), 59 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 65ebb23c..d190a228 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -131,7 +131,8 @@ def from_key(key: str) -> AuthType:
@staticmethod
def from_file(
- filename: typing.Optional[typing.Union[str, pathlib.Path]] = None) -> AuthType:
+ filename: typing.Optional[typing.Union[str, pathlib.Path]] = None
+ ) -> AuthType:
"""Create authentication from secret file.
The default secret file is named `.planet.json` and is stored in the user
@@ -153,17 +154,19 @@ def from_file(
filename: Alternate path for the planet secret file.
"""
- warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
+ warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
plauth_config = {
**_ProductionEnv.LEGACY_AUTH_AUTHORITY,
"client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
- pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(client_config=plauth_config,
- token_file=filename or SECRET_FILE_PATH)
- #planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(
+ client_config=plauth_config,
+ token_file=filename or SECRET_FILE_PATH
+ )
+ # planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
# auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
# token_file_opt=filename or SECRET_FILE_PATH
- #)
+ # )
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -224,6 +227,7 @@ def store(self, filename: typing.Optional[typing.Union[str, pathlib.Path]] = Non
def value(self):
raise DeprecationWarning("Auth.value has been deprecated.")
+
class APIKeyAuthException(PlanetError):
"""exceptions thrown by APIKeyAuth"""
pass
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 8ba9480d..9442c124 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -18,13 +18,14 @@
# Needs to be set at runtime (not necessarily at import time) for dependency injection to planet_auth_util
os.environ["PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+
class _ProductionEnv:
- PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0 = {
+ OAUTH_AUTHORITY_USER = {
"_comment": "OIDC/OAuth server used by Planet Public API endpoints",
"auth_server": "https://login.planet.com/",
"audiences": ["https://api.planet.com/"]
}
- PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB = {
+ OAUTH_AUTHORITY_M2M = {
"_comment": "OIDC/OAuth server used by Planet Public API endpoints",
"auth_server": "https://services.sentinel-hub.com/auth/realms/main",
"audiences": ["https://api.planet.com/"]
@@ -33,26 +34,29 @@ class _ProductionEnv:
"_comment": "Planet legacy JWT auth server used by Planet Public API endpoints",
"legacy_auth_endpoint": "https://api.planet.com/v0/auth/login"
}
- PRIMARY_PUBLIC_OAUTH_AUTHORITIES = [
- PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0,
- PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB,
+ PUBLIC_OAUTH_AUTHORITIES = [
+ OAUTH_AUTHORITY_USER,
+ OAUTH_AUTHORITY_M2M,
]
+
_SDK_CLIENT_ID_PROD = "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees"
+
_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
# The well known OIDC client that is the Planet Python CLI.
# Developers should register their own clients so that users may
# manage grants for different applications. Registering applications
# also allows for application specific URLs or auth flow selection.
- **_ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITY_AUTH0,
+ **_ProductionEnv.OAUTH_AUTHORITY_USER,
"client_type": "oidc_device_code",
"client_id": _SDK_CLIENT_ID_PROD,
"scopes": ["planet", "offline_access", "openid", "profile", "email"],
}
+
_OIDC_AUTH_CLIENT_CONFIG__M2M_PROD = {
- **_ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITY_SENTINELHUB,
+ **_ProductionEnv.OAUTH_AUTHORITY_M2M,
"client_type": "oidc_client_credentials_secret",
"scopes": [],
# "client_id": "__MUST_BE_USER_SUPPLIED__",
@@ -77,53 +81,42 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
library that pertain to the Planet Lab's cloud service.
"""
- # fmt: off
- ##
- ## OAuth production environment profiles
- ##
# Real
- # Using the client ID as a profile name is tricky...
+ # Using the client ID as a profile name might be nice, but is tricky...
# We normalize directory paths to lower case. The auth implementation uses
# mixed case ID strings. The odds of case normalized IDs colliding is low,
# but there is a bit of an off smell.
- # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID = _SDK_CLIENT_ID_PROD
- BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
- BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
- # Aliases
- # BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
+ # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID = _SDK_CLIENT_ID_PROD
+ BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
+ BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
+ BUILTIN_PROFILE_NAME_LEGACY = "legacy"
- ##
- ## Profiles that use Planet's old (pre-OAuth) based auth protocol
- ##
- BUILTIN_PROFILE_NAME_LEGACY = "legacy"
+ # Aliases
+ # BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
_builtin_profile_auth_client_configs = {
- ## OAuth Client Configs
- # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID : _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
- BUILTIN_PROFILE_NAME_PLANET_USER : _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
- BUILTIN_PROFILE_NAME_PLANET_M2M : _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
-
- # Planet Legacy Protocols
- BUILTIN_PROFILE_NAME_LEGACY : _LEGACY_AUTH_CLIENT_CONFIG__PROD,
-
- # Misc
- # BUILTIN_PROFILE_NAME_NONE : _NOOP_AUTH_CLIENT_CONFIG,
+ # BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
+ BUILTIN_PROFILE_NAME_PLANET_USER: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
+ BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
+ BUILTIN_PROFILE_NAME_LEGACY: _LEGACY_AUTH_CLIENT_CONFIG__PROD,
+ # BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
}
_builtin_profile_aliases = {
- # BUILTIN_PROFILE_ALIAS_PLANET_USER : BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID,
+ # BUILTIN_PROFILE_ALIAS_PLANET_USER: BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID,
}
+
_builtin_profile_default_by_client_type = {
- "oidc_device_code" : BUILTIN_PROFILE_NAME_PLANET_USER,
- "oidc_auth_code" : BUILTIN_PROFILE_NAME_PLANET_USER,
- "oidc_client_credentials_secret" : BUILTIN_PROFILE_NAME_PLANET_M2M,
- "planet_legacy" : BUILTIN_PROFILE_NAME_LEGACY,
+ "oidc_device_code": BUILTIN_PROFILE_NAME_PLANET_USER,
+ "oidc_auth_code": BUILTIN_PROFILE_NAME_PLANET_USER,
+ "oidc_client_credentials_secret": BUILTIN_PROFILE_NAME_PLANET_M2M,
+ "planet_legacy": BUILTIN_PROFILE_NAME_LEGACY,
}
+
_builtin_trust_realms: Dict[str, Optional[List[dict]]] = {
- "PRODUCTION": _ProductionEnv.PRIMARY_PUBLIC_OAUTH_AUTHORITIES,
+ "PRODUCTION": _ProductionEnv.PUBLIC_OAUTH_AUTHORITIES,
"CUSTOM": None,
}
- # fmt: on
def builtin_client_authclient_config_dicts(self) -> Dict[str, dict]:
return self._builtin_profile_auth_client_configs
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index d5fdc777..5814a50d 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -19,7 +19,6 @@
import planet_auth
import planet_auth_utils
-import planet
from .cmds import translate_exceptions
from ..auth_builtins import _BuiltinConfigurationProvider
@@ -45,16 +44,14 @@ def auth(ctx):
# just storing the API key, and nominally stores legacy API keys in a
# different location(s). This planet SDK historically only stored an
# API key in this file.
- if (ctx.invoked_subcommand == "init"
- or ctx.invoked_subcommand == "value"
- or ctx.invoked_subcommand == "store"
- ):
+ if (ctx.invoked_subcommand == "init" or ctx.invoked_subcommand == "value" or ctx.invoked_subcommand == "store"):
# click.echo("Overriding Auth Profile with legacy auth profile.")
ctx.obj["AUTH"] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
token_file_opt=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file()
)
+
@auth.command(name="store", deprecated=True) # type: ignore
@translate_exceptions
@click.argument('key')
@@ -63,7 +60,7 @@ def store(key):
if click.confirm('This overrides the stored value. Continue?'):
# See above. A bit of hackery around the token_file to maintain old interface.
token_file = planet_auth.FileBackedJsonObject(file_path=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file())
- try :
+ try:
token_file.load()
conf_data = token_file.data()
except FileNotFoundError:
@@ -83,12 +80,10 @@ def store(key):
auth.add_command(name="profile-show", cmd=planet_auth_utils.cmd_profile_show)
auth.add_command(name="profile-set", cmd=planet_auth_utils.cmd_profile_set)
-planet_auth_utils.cmd_pllegacy_login.name="init"
+planet_auth_utils.cmd_pllegacy_login.name = "init"
planet_auth_utils.cmd_pllegacy_login.deprecated = True
auth.add_command(name="init", cmd=planet_auth_utils.cmd_pllegacy_login)
planet_auth_utils.cmd_pllegacy_print_api_key.name = "value"
planet_auth_utils.cmd_pllegacy_print_api_key.deprecated = True
auth.add_command(name="value", cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
-
-# TODO: what do we want to expose to Planet SDK and CLI users around auth profiles?
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 8bdd159d..467ae5c1 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -93,12 +93,13 @@ def _configure_logging(verbosity):
level=log_level,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
# Hide the embedded util from help. It has many options and use cases that
# may not be directly the most relevant or user-friendly for the specific
# case of working against Planet Platform Services.
# The interface we want to support for the SDK CLI is a specialized
# subset defined by auth.py.
-planet_auth_utils.cmd_plauth_embedded.hidden=True
+planet_auth_utils.cmd_plauth_embedded.hidden = True
main.add_command(cmd=planet_auth_utils.cmd_plauth_embedded, name="plauth") # type: ignore
main.add_command(auth.auth) # type: ignore
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 1250807f..27f6bc51 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -12,7 +12,6 @@
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-import json
import logging
import pytest
@@ -66,6 +65,7 @@ def test_Auth_from_file_doesnotexist(secret_path):
with pytest.raises(FileNotFoundError):
_ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+
def test_Auth_from_file_wrongformat(secret_path):
with open(secret_path, 'w') as fp:
fp.write('{"notkey": "testvar_wrong_format"}')
@@ -74,7 +74,6 @@ def test_Auth_from_file_wrongformat(secret_path):
_ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
-
def test_Auth_from_file_alternate(tmp_path):
secret_path = str(tmp_path / '.test')
with open(secret_path, 'w') as fp:
@@ -120,8 +119,6 @@ def test_Auth_from_env_alternate_doesnotexist(monkeypatch):
def test_Auth_from_login(monkeypatch):
- auth_data = 'authdata'
-
# auth.AuthClient has been completely removed
# in the conversion to planet_auth
# def login(*args, **kwargs):
@@ -129,7 +126,7 @@ def test_Auth_from_login(monkeypatch):
#
# monkeypatch.setattr(auth.AuthClient, 'login', login)
with pytest.raises(DeprecationWarning):
- test_auth = auth.Auth.from_login('email', 'pw')
+ _ = auth.Auth.from_login('email', 'pw')
def test_auth_value_deprecated():
From 179d4495e7ffa8b2f7638f7ea9b930e3a14178e6 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 18 Jan 2025 09:17:04 -0800
Subject: [PATCH 25/81] yapf formatting
---
planet/auth.py | 42 +++++++++++++++++++++-------------
planet/auth_builtins.py | 8 +++----
planet/cli/auth.py | 23 ++++++++++++-------
planet/cli/cli.py | 40 ++++++++++++++++++++++----------
tests/unit/test_auth.py | 21 +++++++++++------
tests/unit/test_cli_session.py | 3 ++-
6 files changed, 89 insertions(+), 48 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index d190a228..27d6a3e7 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -54,10 +54,12 @@ def from_defaults():
PL_AUTH_API_KEY: Specify a legacy Planet API key
"""
- return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context())
+ return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.
+ initialize_auth_client_context())
@classmethod
- def from_oauth_user_session(cls): # TODO: take client ID? Rename to be CLI session specific?
+ def from_oauth_user_session(
+ cls): # TODO: take client ID? Rename to be CLI session specific?
"""
Create authentication for a user whose initialized login information
will be saved to `~/.planet.json` and `~/.planet/` user login.
@@ -78,8 +80,8 @@ def from_oauth_user_session(cls): # TODO: take client ID? Rename to be CLI ses
# TODO: double check app IDs registered to the CLI
"""
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_PLANET_USER
- )
+ auth_profile_opt=_BuiltinConfigurationProvider.
+ BUILTIN_PROFILE_NAME_PLANET_USER)
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
@@ -117,9 +119,11 @@ def from_key(key: str) -> AuthType:
Parameters:
key: Planet API key
"""
- warnings.warn("Planet API keys will be deprecated for most use cases."
- " Initialize an OAuth client, or create an OAuth service account."
- " Proceeding for now.", PendingDeprecationWarning)
+ warnings.warn(
+ "Planet API keys will be deprecated for most use cases."
+ " Initialize an OAuth client, or create an OAuth service account."
+ " Proceeding for now.",
+ PendingDeprecationWarning)
if not key:
raise APIKeyAuthException('API key cannot be empty.')
@@ -154,15 +158,16 @@ def from_file(
filename: Alternate path for the planet secret file.
"""
- warnings.warn("Auth.from_file() will be deprecated.", PendingDeprecationWarning)
+ warnings.warn("Auth.from_file() will be deprecated.",
+ PendingDeprecationWarning)
plauth_config = {
**_ProductionEnv.LEGACY_AUTH_AUTHORITY,
- "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ "client_type":
+ planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
}
pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(
client_config=plauth_config,
- token_file=filename or SECRET_FILE_PATH
- )
+ token_file=filename or SECRET_FILE_PATH)
# planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
# auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
# token_file_opt=filename or SECRET_FILE_PATH
@@ -188,8 +193,7 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
warnings.warn(
"from_env() will be deprecated. Use from_defaults() in most"
" cases, which will consider environment variables.",
- PendingDeprecationWarning
- )
+ PendingDeprecationWarning)
variable_name = variable_name or planet_auth_utils.EnvironmentVariables.AUTH_API_KEY
api_key = os.getenv(variable_name, None)
return Auth.from_key(api_key)
@@ -209,8 +213,12 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- warnings.warn("Auth.from_login() has been deprecated. Use Auth.from_user_session().", DeprecationWarning)
- raise DeprecationWarning("Auth.from_login() has been deprecated. Use Auth.from_user_session().")
+ warnings.warn(
+ "Auth.from_login() has been deprecated. Use Auth.from_user_session().",
+ DeprecationWarning)
+ raise DeprecationWarning(
+ "Auth.from_login() has been deprecated. Use Auth.from_user_session()."
+ )
@classmethod
def from_dict(cls, data: dict) -> AuthType:
@@ -219,7 +227,9 @@ def from_dict(cls, data: dict) -> AuthType:
def to_dict(self) -> dict:
raise DeprecationWarning("Auth.to_dict() has been deprecated.")
- def store(self, filename: typing.Optional[typing.Union[str, pathlib.Path]] = None):
+ def store(self,
+ filename: typing.Optional[typing.Union[str,
+ pathlib.Path]] = None):
warnings.warn("Auth.store() has been deprecated.", DeprecationWarning)
raise DeprecationWarning("Auth.store() has been deprecated.")
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 9442c124..4ad8ce84 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -16,7 +16,8 @@
from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
# Needs to be set at runtime (not necessarily at import time) for dependency injection to planet_auth_util
-os.environ["PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+os.environ[
+ "PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
class _ProductionEnv:
@@ -31,7 +32,8 @@ class _ProductionEnv:
"audiences": ["https://api.planet.com/"]
}
LEGACY_AUTH_AUTHORITY = {
- "_comment": "Planet legacy JWT auth server used by Planet Public API endpoints",
+ "_comment":
+ "Planet legacy JWT auth server used by Planet Public API endpoints",
"legacy_auth_endpoint": "https://api.planet.com/v0/auth/login"
}
PUBLIC_OAUTH_AUTHORITIES = [
@@ -42,7 +44,6 @@ class _ProductionEnv:
_SDK_CLIENT_ID_PROD = "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees"
-
_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
# The well known OIDC client that is the Planet Python CLI.
# Developers should register their own clients so that users may
@@ -54,7 +55,6 @@ class _ProductionEnv:
"scopes": ["planet", "offline_access", "openid", "profile", "email"],
}
-
_OIDC_AUTH_CLIENT_CONFIG__M2M_PROD = {
**_ProductionEnv.OAUTH_AUTHORITY_M2M,
"client_type": "oidc_client_credentials_secret",
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index 5814a50d..979dfb1f 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -44,12 +44,15 @@ def auth(ctx):
# just storing the API key, and nominally stores legacy API keys in a
# different location(s). This planet SDK historically only stored an
# API key in this file.
- if (ctx.invoked_subcommand == "init" or ctx.invoked_subcommand == "value" or ctx.invoked_subcommand == "store"):
+ if (ctx.invoked_subcommand == "init" or ctx.invoked_subcommand == "value"
+ or ctx.invoked_subcommand == "store"):
# click.echo("Overriding Auth Profile with legacy auth profile.")
- ctx.obj["AUTH"] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_LEGACY,
- token_file_opt=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file()
- )
+ ctx.obj[
+ "AUTH"] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_profile_opt=_BuiltinConfigurationProvider.
+ BUILTIN_PROFILE_NAME_LEGACY,
+ token_file_opt=planet_auth_utils.PlanetAuthUserConfig.
+ default_user_config_file())
@auth.command(name="store", deprecated=True) # type: ignore
@@ -59,7 +62,9 @@ def store(key):
"""Store authentication information"""
if click.confirm('This overrides the stored value. Continue?'):
# See above. A bit of hackery around the token_file to maintain old interface.
- token_file = planet_auth.FileBackedJsonObject(file_path=planet_auth_utils.PlanetAuthUserConfig.default_user_config_file())
+ token_file = planet_auth.FileBackedJsonObject(
+ file_path=planet_auth_utils.PlanetAuthUserConfig.
+ default_user_config_file())
try:
token_file.load()
conf_data = token_file.data()
@@ -75,7 +80,8 @@ def store(key):
# click commands as much as we can.
auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
-auth.add_command(name="print-access-token", cmd=planet_auth_utils.cmd_oauth_print_access_token)
+auth.add_command(name="print-access-token",
+ cmd=planet_auth_utils.cmd_oauth_print_access_token)
auth.add_command(name="profile-list", cmd=planet_auth_utils.cmd_profile_list)
auth.add_command(name="profile-show", cmd=planet_auth_utils.cmd_profile_show)
auth.add_command(name="profile-set", cmd=planet_auth_utils.cmd_profile_set)
@@ -86,4 +92,5 @@ def store(key):
planet_auth_utils.cmd_pllegacy_print_api_key.name = "value"
planet_auth_utils.cmd_pllegacy_print_api_key.deprecated = True
-auth.add_command(name="value", cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
+auth.add_command(name="value",
+ cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 467ae5c1..7fa75938 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -42,7 +42,13 @@
@planet_auth_utils.opt_client_secret
@planet_auth_utils.opt_api_key
@cmds.translate_exceptions
-def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
+def main(ctx,
+ verbosity,
+ quiet,
+ auth_profile,
+ auth_client_id,
+ auth_client_secret,
+ auth_api_key):
"""Planet SDK for Python CLI"""
_configure_logging(verbosity)
@@ -51,20 +57,30 @@ def main(ctx, verbosity, quiet, auth_profile, auth_client_id, auth_client_secret
ctx.ensure_object(dict)
ctx.obj['QUIET'] = quiet
- _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret, auth_api_key)
+ _configure_cli_auth_ctx(ctx,
+ auth_profile,
+ auth_client_id,
+ auth_client_secret,
+ auth_api_key)
-def _configure_cli_auth_ctx(ctx, auth_profile, auth_client_id, auth_client_secret, auth_api_key):
+def _configure_cli_auth_ctx(ctx,
+ auth_profile,
+ auth_client_id,
+ auth_client_secret,
+ auth_api_key):
# planet-auth library Auth context type
- ctx.obj['AUTH'] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_profile_opt=auth_profile,
- auth_client_id_opt=auth_client_id,
- auth_client_secret_opt=auth_client_secret,
- auth_api_key_opt=auth_api_key,
- )
+ ctx.obj[
+ 'AUTH'] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
+ auth_profile_opt=auth_profile,
+ auth_client_id_opt=auth_client_id,
+ auth_client_secret_opt=auth_client_secret,
+ auth_api_key_opt=auth_api_key,
+ )
# planet SDK Auth context type
- ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(pl_authlib_context=ctx.obj['AUTH'])
+ ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(
+ pl_authlib_context=ctx.obj['AUTH'])
def _configure_logging(verbosity):
@@ -100,7 +116,8 @@ def _configure_logging(verbosity):
# The interface we want to support for the SDK CLI is a specialized
# subset defined by auth.py.
planet_auth_utils.cmd_plauth_embedded.hidden = True
-main.add_command(cmd=planet_auth_utils.cmd_plauth_embedded, name="plauth") # type: ignore
+main.add_command(cmd=planet_auth_utils.cmd_plauth_embedded,
+ name="plauth") # type: ignore
main.add_command(auth.auth) # type: ignore
main.add_command(data.data) # type: ignore
@@ -108,6 +125,5 @@ def _configure_logging(verbosity):
main.add_command(subscriptions.subscriptions) # type: ignore
main.add_command(collect.collect) # type: ignore
-
if __name__ == "__main__":
main() # pylint: disable=E1120
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 27f6bc51..3427183c 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -40,7 +40,8 @@ def test_Auth_from_key():
test_auth_env1 = auth.Auth.from_key('testkey_from_key')
# We know that planet_auth instantiates an in memory "static API key" auth client.
# test_api_key = test_auth_env1._plauth.request_authenticator().credential().legacy_api_key()
- test_api_key = test_auth_env1._plauth.request_authenticator().credential().api_key()
+ test_api_key = test_auth_env1._plauth.request_authenticator().credential(
+ ).api_key()
assert test_api_key == 'testkey_from_key'
@@ -55,7 +56,8 @@ def test_Auth_from_file(secret_path):
test_auth = auth.Auth.from_file()
# We know that planet_auth instantiates a "Legacy" auth client.
- test_api_key = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ test_api_key = test_auth._plauth.request_authenticator().credential(
+ ).legacy_api_key()
# test_api_key = test_auth._plauth.request_authenticator().credential().api_key()
assert test_api_key == 'testvar_from_file'
@@ -63,7 +65,8 @@ def test_Auth_from_file(secret_path):
def test_Auth_from_file_doesnotexist(secret_path):
test_auth = auth.Auth.from_file(secret_path)
with pytest.raises(FileNotFoundError):
- _ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ _ = test_auth._plauth.request_authenticator().credential(
+ ).legacy_api_key()
def test_Auth_from_file_wrongformat(secret_path):
@@ -71,7 +74,8 @@ def test_Auth_from_file_wrongformat(secret_path):
fp.write('{"notkey": "testvar_wrong_format"}')
test_auth = auth.Auth.from_file(secret_path)
with pytest.raises(planet_auth.InvalidDataException):
- _ = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ _ = test_auth._plauth.request_authenticator().credential(
+ ).legacy_api_key()
def test_Auth_from_file_alternate(tmp_path):
@@ -80,7 +84,8 @@ def test_Auth_from_file_alternate(tmp_path):
fp.write('{"key": "testvar_alt_path"}')
test_auth = auth.Auth.from_file(secret_path)
- test_api_key = test_auth._plauth.request_authenticator().credential().legacy_api_key()
+ test_api_key = test_auth._plauth.request_authenticator().credential(
+ ).legacy_api_key()
assert test_api_key == 'testvar_alt_path'
@@ -88,7 +93,8 @@ def test_Auth_from_env(monkeypatch):
monkeypatch.setenv('PL_API_KEY', 'testkey_env')
test_auth_env = auth.Auth.from_env()
# TODO: that I short cicuit between legacy and API key auth impls makes this weird.
- test_api_key = test_auth_env._plauth.request_authenticator().credential().api_key()
+ test_api_key = test_auth_env._plauth.request_authenticator().credential(
+ ).api_key()
assert test_api_key == 'testkey_env'
@@ -104,7 +110,8 @@ def test_Auth_from_env_alternate_success(monkeypatch):
monkeypatch.delenv('PL_API_KEY', raising=False)
test_auth_env = auth.Auth.from_env(alternate)
- test_api_key = test_auth_env._plauth.request_authenticator().credential().api_key()
+ test_api_key = test_auth_env._plauth.request_authenticator().credential(
+ ).api_key()
assert test_api_key == 'testkey'
diff --git a/tests/unit/test_cli_session.py b/tests/unit/test_cli_session.py
index 2ac756eb..ed389f70 100644
--- a/tests/unit/test_cli_session.py
+++ b/tests/unit/test_cli_session.py
@@ -62,7 +62,8 @@ async def test_CliSession_headers(test_valid_secretfile):
@pytest.mark.anyio
async def test_CliSession_auth_valid(test_valid_secretfile):
# The default auth
- async with session.CliSession(plsdk_auth=auth.Auth.from_key("clisessiontest")) as sess:
+ async with session.CliSession(
+ plsdk_auth=auth.Auth.from_key("clisessiontest")) as sess:
route = respx.get(TEST_URL)
route.return_value = httpx.Response(HTTPStatus.OK)
From 324a1c4ab0e9615c72f9bc737152ffb4c1bd01cb Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 18 Jan 2025 09:18:51 -0800
Subject: [PATCH 26/81] harmonize flak8 and yapf
---
planet/cli/cli.py | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 7fa75938..04861cfe 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -75,8 +75,7 @@ def _configure_cli_auth_ctx(ctx,
auth_profile_opt=auth_profile,
auth_client_id_opt=auth_client_id,
auth_client_secret_opt=auth_client_secret,
- auth_api_key_opt=auth_api_key,
- )
+ auth_api_key_opt=auth_api_key)
# planet SDK Auth context type
ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(
From 441ecbfe4289ab95f85b580ce59ecd3c62c47336 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 12:11:41 -0800
Subject: [PATCH 27/81] ignore planet auth deprecation warnings.
---
noxfile.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/noxfile.py b/noxfile.py
index 620014b8..46b70b6a 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -55,6 +55,7 @@ def test(session):
'-v',
'-Werror',
'-Wignore::DeprecationWarning:tqdm.std',
+ '-Wignore::PendingDeprecationWarning:planet.auth',
*options)
From fbf0f375fd64942281a401f8c39939e09d1f7e9d Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 12:14:31 -0800
Subject: [PATCH 28/81] Make 'none' a valid built-in auth type
---
planet/auth_builtins.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 4ad8ce84..a71d5055 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -90,6 +90,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
BUILTIN_PROFILE_NAME_LEGACY = "legacy"
+ BUILTIN_PROFILE_NAME_NONE = "none"
# Aliases
# BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
@@ -99,7 +100,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_PLANET_USER: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
BUILTIN_PROFILE_NAME_LEGACY: _LEGACY_AUTH_CLIENT_CONFIG__PROD,
- # BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
+ BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
}
_builtin_profile_aliases = {
@@ -111,6 +112,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
"oidc_auth_code": BUILTIN_PROFILE_NAME_PLANET_USER,
"oidc_client_credentials_secret": BUILTIN_PROFILE_NAME_PLANET_M2M,
"planet_legacy": BUILTIN_PROFILE_NAME_LEGACY,
+ "none": BUILTIN_PROFILE_NAME_NONE,
}
_builtin_trust_realms: Dict[str, Optional[List[dict]]] = {
From b9542ab82652f31794cf296d9f1930f012334474 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 12:15:55 -0800
Subject: [PATCH 29/81] remove AuthSession from http.py
---
planet/http.py | 43 +------------------------------------------
1 file changed, 1 insertion(+), 42 deletions(-)
diff --git a/planet/http.py b/planet/http.py
index fdcac045..d0392856 100644
--- a/planet/http.py
+++ b/planet/http.py
@@ -238,7 +238,7 @@ def __init__(self, auth: Optional[AuthType] = None):
auth: Planet server authentication.
"""
if auth is None:
- auth = Auth.from_defaults()
+ auth = Auth.from_user_defaults()
LOGGER.info(f'Session read timeout set to {READ_TIMEOUT}.')
timeout = httpx.Timeout(10.0, read=READ_TIMEOUT)
@@ -453,44 +453,3 @@ def client(self,
return _client_directory[name](self, base_url=base_url)
except KeyError:
raise exceptions.ClientError("No such client.")
-
-
-class AuthSession(BaseSession):
- """Synchronous connection to the Planet Auth service."""
-
- def __init__(self):
- """Initialize an AuthSession.
- """
- self._client = httpx.Client(timeout=None)
- self._client.headers.update({'User-Agent': self._get_user_agent()})
- self._client.event_hooks['request'] = [self._log_request]
- self._client.event_hooks['response'] = [
- self._log_response, self._raise_for_status
- ]
-
- def request(self, method: str, url: str, json: dict):
- """Submit a request
-
- Parameters:
- method: HTTP request method.
- url: Location of the API endpoint.
- json: JSON to send.
-
- Returns:
- Server response.
-
- Raises:
- planet.exceptions.APIException: On API error.
- """
- request = self._client.build_request(method=method, url=url, json=json)
- http_resp = self._client.send(request)
- return models.Response(http_resp)
-
- @classmethod
- def _raise_for_status(cls, response):
- try:
- super()._raise_for_status(response)
- except exceptions.BadQuery:
- raise exceptions.APIError('Not a valid email address.')
- except exceptions.InvalidAPIKey:
- raise exceptions.APIError('Incorrect email or password.')
From 67fd3a2db3023aebed8302a960b8dea1ee96cbb3 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 13:43:30 -0800
Subject: [PATCH 30/81] add skel auth config
---
planet/auth_builtins.py | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index a71d5055..0d47054e 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -44,6 +44,13 @@ class _ProductionEnv:
_SDK_CLIENT_ID_PROD = "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees"
+_OIDC_AUTH_CLIENT_CONFIG__SKEL = {
+ **_ProductionEnv.OAUTH_AUTHORITY_USER,
+ # "client_type": "oidc_device_code",
+ # "client_id": _SDK_CLIENT_ID_PROD,
+ "scopes": ["planet", "offline_access", "openid", "profile", "email"],
+}
+
_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
# The well known OIDC client that is the Planet Python CLI.
# Developers should register their own clients so that users may
From 88fa6ac943d7e6b94b7ac28decc8ba516c94d706 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 13:43:58 -0800
Subject: [PATCH 31/81] update main Auth() API
---
planet/auth.py | 76 +++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 59 insertions(+), 17 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 27d6a3e7..567ad474 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -20,12 +20,13 @@
import typing
import warnings
import httpx
+from typing import List
import planet_auth
import planet_auth_utils
from .constants import SECRET_FILE_PATH
-from .auth_builtins import _ProductionEnv, _BuiltinConfigurationProvider
+from .auth_builtins import _ProductionEnv, _BuiltinConfigurationProvider, _OIDC_AUTH_CLIENT_CONFIG__SKEL
from .exceptions import PlanetError
AuthType = httpx.Auth
@@ -38,31 +39,39 @@ class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
@staticmethod
- def from_defaults():
+ def from_user_defaults():
"""
- Create authentication from defaults. Defaults are processed by the
- underlying planet_auth and planet_auth_utils libraries, and take into
- account environment variables (highest priority), configuration saved
- to `~/.planet.json` (next priority), and built-in defaults (lowest
- priority).
+ Create authentication from user defaults. Defaults take into
+ account environment variables (highest priority), user configuration
+ saved to `~/.planet.json` (next priority), and built-in defaults
+ (lowest priority).
+
+ Users may use the `planet auth login` command to initialize
+ configuration files.
Environment Variables:
- PL_AUTH_PROFILE: Specify a custom planet_auth auth client profile
- (Advanced use cases)
+ PL_AUTH_PROFILE: Specify a custom planet_auth library auth
+ client profile (Advanced use cases)
PL_AUTH_CLIENT_ID: Specify an OAuth2 M2M client ID
PL_AUTH_CLIENT_SECRET: Specify an OAuth2 M2M client secret
PL_AUTH_API_KEY: Specify a legacy Planet API key
-
"""
return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.
initialize_auth_client_context())
- @classmethod
- def from_oauth_user_session(
- cls): # TODO: take client ID? Rename to be CLI session specific?
+ # TODO: It feels like we should accept an auth profile so a user
+ # can manage multiple identities. But that's also far broader than
+ # "OAuth user interactive" session, since the auth implementation
+ # configured by a profile could be anything.
+ # It also feels like we need a method that accepts client IDs
+ # managed by the developer so they can initialize the library
+ # to use the specified client ID of the larger application built
+ # on top of the library (e.g. QGIS)
+ @staticmethod
+ def from_oauth_user_session():
"""
Create authentication for a user whose initialized login information
- will be saved to `~/.planet.json` and `~/.planet/` user login.
+ has been saved to `~/.planet.json` and `~/.planet/`.
A user should perform a login to initialize this session out-of-band
using the command `planet auth login`.
@@ -76,17 +85,49 @@ def from_oauth_user_session(
Most properly, this process uses IDs that are specific to the
application. The exact process that should be used to complete
login is specific to the particulars of the application.
-
- # TODO: double check app IDs registered to the CLI
"""
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_profile_opt=_BuiltinConfigurationProvider.
BUILTIN_PROFILE_NAME_PLANET_USER)
return _PLAuthLibAuth(plauth=pl_authlib_context)
+ # TODO: I think we need something this for developers of user interactive
+ # applications (e.g. QGIS), but as of January 2025 we do not have a way
+ # for developers to register user interactive client on the platform,
+ # or a way for users of such applications to revoke such authorizations.
+ # Even without this, we may white glove client IDs for partners before
+ # it is a generally available feature.
+ #
+ @staticmethod
+ def from_oauth_client_config(client_id: str, requested_scopes: List[str], token_file_path: str):
+ """
+ Beta. Feature not yet supported for public use.
+ """
+ # raise NotImplementedError("Feature not implemented yet")
+
+ plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__SKEL
+ plauth_config_dict["client_id"] = client_id
+ ## plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
+ plauth_config_dict["scopes"] = requested_scopes
+ # TBD: How flexible will we be in terms of supported flows OAuth flows?
+ plauth_config_dict["client_type"] = "oidc_device_code"
+
+ pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(
+ client_config=plauth_config_dict,
+ # Set token_file to 'None' to operate in memory. Set to a path on disk to save
+ # refresh tokens. Paths on disk should conform to
+ # ~/.planet/<profile>/token.json[.sops] to play well with the CLI
+ # managing the same sessions.
+ token_file=token_file_path,
+ # profile_name="my_app_name"
+ )
+ return Auth.from_plauth(pl_authlib_context)
+
+
@staticmethod
def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
- """Create authentication from OAuth2 service account client ID and secret.
+ """Create authentication from the specified OAuth2 service account
+ client ID and secret.
Parameters:
client_id: Planet service account client ID.
@@ -95,6 +136,7 @@ def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
auth_client_id_opt=client_id,
auth_client_secret_opt=client_secret,
+ # auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_PLANET_M2M,
)
return _PLAuthLibAuth(plauth=pl_authlib_context)
From 3069baa0d21830c76ad90de56006318522374279 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 13:44:17 -0800
Subject: [PATCH 32/81] test updates
---
tests/pytest.ini.main | 4 ++++
tests/unit/test_auth.py | 16 ++++++++++++++++
tests/unit/test_http.py | 25 +++----------------------
3 files changed, 23 insertions(+), 22 deletions(-)
create mode 100644 tests/pytest.ini.main
diff --git a/tests/pytest.ini.main b/tests/pytest.ini.main
new file mode 100644
index 00000000..cd8c265e
--- /dev/null
+++ b/tests/pytest.ini.main
@@ -0,0 +1,4 @@
+[pytest]
+log_cli = True
+log_format = %(asctime)s %(levelname)s %(message)s
+log_date_format = %Y-%m-%d %H:%M:%S
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 3427183c..2c44c824 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -136,6 +136,22 @@ def test_Auth_from_login(monkeypatch):
_ = auth.Auth.from_login('email', 'pw')
+def test_Auth_from_user_defaults():
+ # The primary implementation is implemented and unit tested by the planet auth libraries.
+ under_test = auth.Auth.from_user_defaults()
+
+
+def test_Auth_from_oauth_m2m():
+ # TODO: assert that the specified M2M client is used,
+ # regardless of other user defaults.
+ under_test = auth.Auth.from_oauth_m2m("mock_client_id", "mock_client_secret")
+
+
+def test_Auth_from_oauth_user_session():
+ # TODO: assert that the user interactive session is used.
+ under_test = auth.Auth.from_oauth_user_session()
+
+
def test_auth_value_deprecated():
with pytest.raises(DeprecationWarning):
test_auth = auth.Auth.from_key("test_deprecated_key")
diff --git a/tests/unit/test_http.py b/tests/unit/test_http.py
index bc876a1c..8c74a391 100644
--- a/tests/unit/test_http.py
+++ b/tests/unit/test_http.py
@@ -20,10 +20,12 @@
from unittest.mock import patch
import httpx
+import planet_auth_utils
import respx
import pytest
+import planet
from planet import exceptions, http
TEST_URL = 'mock://fantastic.com'
@@ -195,6 +197,7 @@ async def test_session_contextmanager():
@pytest.mark.parametrize('data', (None, {'boo': 'baa'}))
async def test_session_request_success(data):
+ # async with http.Session(auth=planet.Auth.from_plauth(pl_authlib_context=planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(auth_profile_opt="none"))) as ps:
async with http.Session() as ps:
resp_json = {'foo': 'bar'}
route = respx.get(TEST_URL)
@@ -282,25 +285,3 @@ def test__calculate_wait():
# this doesn't really test the randomness but does test exponential
# and threshold
assert math.floor(wait) == expected
-
-
-@respx.mock
-@pytest.mark.anyio
-async def test_authsession_request():
- sess = http.AuthSession()
- resp_json = {'token': 'foobar'}
- mock_resp = httpx.Response(HTTPStatus.OK, json=resp_json)
- respx.get(TEST_URL).return_value = mock_resp
-
- resp = sess.request(method='GET', url=TEST_URL, json={'foo': 'bar'})
- assert resp.json() == resp_json
-
-
-def test_authsession__raise_for_status(mock_response):
- with pytest.raises(exceptions.APIError):
- http.AuthSession._raise_for_status(
- mock_response(HTTPStatus.BAD_REQUEST, json={}))
-
- with pytest.raises(exceptions.APIError):
- http.AuthSession._raise_for_status(
- mock_response(HTTPStatus.UNAUTHORIZED, json={}))
From a12ca4cea8ab485fbd4edc0e4193ea0b16a8a40a Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 13:45:36 -0800
Subject: [PATCH 33/81] update CLI guide with new login command
---
docs/cli/cli-guide.md | 36 +++++++++++++++---------------------
1 file changed, 15 insertions(+), 21 deletions(-)
diff --git a/docs/cli/cli-guide.md b/docs/cli/cli-guide.md
index dc501de4..f2fec6e8 100644
--- a/docs/cli/cli-guide.md
+++ b/docs/cli/cli-guide.md
@@ -55,46 +55,40 @@ To confirm your Planet account, or to get one if you don’t already have one, s
### Authenticate with the Planet server
-Just as you log in when you browse to https://account.planet.com, you’ll want to sign on to your account so you have access to your account and orders.
+Just as you log in when you browse to https://planet.com/account, you’ll want to sign on to your account so you have access to your account and orders.
At a terminal console, type the following Planet command:
```console
-$ planet auth init
+$ planet auth login
```
-You’ll be prompted for the email and password you use to access [your account](https://account.planet.com). When you type in your password, you won’t see any indication that the characters are being accepted. But when you hit enter, you’ll know that you’ve succeeded because you’ll see on the command line:
+A browser window should be opened, and you will be directed to login to your account. This
+command will wait for the browser login to complete, and should exit shortly afterwards.
+When this process succeeds you should see the following message on the console:
```console
-Initialized
+Login succeeded.
```
-### Get your API key
-
-Now that you’ve logged in, you can easily retrieve your API key that is being used for requests with the following command:
-
+If you are in an environment where the `planet` command line utility cannot open a browser (such
+as a remote shell on a cloud service provider), use the following command and follow the instructions:
```console
-planet auth value
+$ planet auth login --no-open-browser
```
-Many `planet` calls you make require an API key. This is a very convenient way to quickly grab your API key.
-
-#### Your API Key as an Environment Variable
+### Get your Access Token
-You can also set the value of your API Key as an environment variable in your terminal at the command line:
+Now that you’ve logged in, you can easily retrieve an Access Token that is being used for requests with the following command:
```console
-export PL_API_KEY=<your api key>
+planet auth print-access-token
```
-And you can see that the value was stored successfully as an environment variable with the following command:
-
-```console
-echo $PL_API_KEY
-```
+Many `planet` calls you make require an access token. This is a very convenient way to quickly grab the current access token.
-!!!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`.
+**Note** : As a security measure, access tokens are time limited. They have a relatively short lifespan, and must
+be refreshed. The `print-access-token` command takes care of this transparently for the user.
## Step 5: Search for Planet Imagery
From 261e1fe45a00e7eb26bdd30975e6f8d67fedcc80 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 14:17:18 -0800
Subject: [PATCH 34/81] lint fixes
---
planet/auth.py | 5 ++---
tests/unit/test_auth.py | 20 ++++++++++++++++----
tests/unit/test_http.py | 2 --
3 files changed, 18 insertions(+), 9 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 567ad474..bc86f031 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -103,11 +103,11 @@ def from_oauth_client_config(client_id: str, requested_scopes: List[str], token_
"""
Beta. Feature not yet supported for public use.
"""
- # raise NotImplementedError("Feature not implemented yet")
+ raise NotImplementedError("Feature not implemented yet")
plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__SKEL
plauth_config_dict["client_id"] = client_id
- ## plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
+ # plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
plauth_config_dict["scopes"] = requested_scopes
# TBD: How flexible will we be in terms of supported flows OAuth flows?
plauth_config_dict["client_type"] = "oidc_device_code"
@@ -123,7 +123,6 @@ def from_oauth_client_config(client_id: str, requested_scopes: List[str], token_
)
return Auth.from_plauth(pl_authlib_context)
-
@staticmethod
def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
"""Create authentication from the specified OAuth2 service account
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 2c44c824..f72c241a 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -16,9 +16,12 @@
import pytest
+import planet.auth
from planet import auth
import planet_auth
+import planet.auth_builtins
+
LOGGER = logging.getLogger(__name__)
@@ -138,18 +141,27 @@ def test_Auth_from_login(monkeypatch):
def test_Auth_from_user_defaults():
# The primary implementation is implemented and unit tested by the planet auth libraries.
- under_test = auth.Auth.from_user_defaults()
+ # This tests that it doesn't explode with an exception.
+ # CI/CD currently is run by configuring auth via PL_API_KEY env var.
+ # What this will actually do in an user env depends on a lot of variables.
+ _ = auth.Auth.from_user_defaults()
def test_Auth_from_oauth_m2m():
- # TODO: assert that the specified M2M client is used,
- # regardless of other user defaults.
under_test = auth.Auth.from_oauth_m2m("mock_client_id", "mock_client_secret")
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(), planet_auth.ClientCredentialsClientSecretAuthClient)
+ assert under_test._plauth.auth_client()._ccauth_client_config.client_id() == "mock_client_id"
+ assert under_test._plauth.auth_client()._ccauth_client_config.client_secret() == "mock_client_secret"
+ assert under_test._plauth.auth_client()._ccauth_client_config.auth_server() == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
def test_Auth_from_oauth_user_session():
- # TODO: assert that the user interactive session is used.
under_test = auth.Auth.from_oauth_user_session()
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(), planet_auth.DeviceCodeAuthClient)
+ assert under_test._plauth.auth_client()._devicecode_client_config.client_id() == planet.auth_builtins._SDK_CLIENT_ID_PROD
+ assert under_test._plauth.auth_client()._devicecode_client_config.auth_server() == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER["auth_server"]
def test_auth_value_deprecated():
diff --git a/tests/unit/test_http.py b/tests/unit/test_http.py
index 8c74a391..e7fde153 100644
--- a/tests/unit/test_http.py
+++ b/tests/unit/test_http.py
@@ -20,12 +20,10 @@
from unittest.mock import patch
import httpx
-import planet_auth_utils
import respx
import pytest
-import planet
from planet import exceptions, http
TEST_URL = 'mock://fantastic.com'
From bc20fe9a372686b6d75863402662ecf06db28d31 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 14:19:22 -0800
Subject: [PATCH 35/81] yapf formatting
---
planet/auth.py | 7 ++++---
tests/unit/test_auth.py | 32 ++++++++++++++++++++++++--------
2 files changed, 28 insertions(+), 11 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index bc86f031..415f8cc5 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -99,7 +99,9 @@ def from_oauth_user_session():
# it is a generally available feature.
#
@staticmethod
- def from_oauth_client_config(client_id: str, requested_scopes: List[str], token_file_path: str):
+ def from_oauth_client_config(client_id: str,
+ requested_scopes: List[str],
+ token_file_path: str):
"""
Beta. Feature not yet supported for public use.
"""
@@ -118,8 +120,7 @@ def from_oauth_client_config(client_id: str, requested_scopes: List[str], token_
# refresh tokens. Paths on disk should conform to
# ~/.planet/<profile>/token.json[.sops] to play well with the CLI
# managing the same sessions.
- token_file=token_file_path,
- # profile_name="my_app_name"
+ token_file=token_file_path, # profile_name="my_app_name"
)
return Auth.from_plauth(pl_authlib_context)
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index f72c241a..ca335df3 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -148,20 +148,36 @@ def test_Auth_from_user_defaults():
def test_Auth_from_oauth_m2m():
- under_test = auth.Auth.from_oauth_m2m("mock_client_id", "mock_client_secret")
+ under_test = auth.Auth.from_oauth_m2m("mock_client_id",
+ "mock_client_secret")
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
- assert isinstance(under_test._plauth.auth_client(), planet_auth.ClientCredentialsClientSecretAuthClient)
- assert under_test._plauth.auth_client()._ccauth_client_config.client_id() == "mock_client_id"
- assert under_test._plauth.auth_client()._ccauth_client_config.client_secret() == "mock_client_secret"
- assert under_test._plauth.auth_client()._ccauth_client_config.auth_server() == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.ClientCredentialsClientSecretAuthClient)
+
+ assert under_test._plauth.auth_client()._ccauth_client_config.client_id(
+ ) == "mock_client_id"
+
+ assert under_test._plauth.auth_client(
+ )._ccauth_client_config.client_secret() == "mock_client_secret"
+
+ assert under_test._plauth.auth_client()._ccauth_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
def test_Auth_from_oauth_user_session():
under_test = auth.Auth.from_oauth_user_session()
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
- assert isinstance(under_test._plauth.auth_client(), planet_auth.DeviceCodeAuthClient)
- assert under_test._plauth.auth_client()._devicecode_client_config.client_id() == planet.auth_builtins._SDK_CLIENT_ID_PROD
- assert under_test._plauth.auth_client()._devicecode_client_config.auth_server() == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER["auth_server"]
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.DeviceCodeAuthClient)
+
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.client_id(
+ ) == planet.auth_builtins._SDK_CLIENT_ID_PROD
+
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
+ "auth_server"]
def test_auth_value_deprecated():
From bdcc0bed24ce993385981f853f64a67d9c88fe2f Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 16:27:12 -0800
Subject: [PATCH 36/81] linting fixes
---
planet/auth.py | 2 +-
planet/auth_builtins.py | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 415f8cc5..58f314f0 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -155,7 +155,7 @@ def from_plauth(pl_authlib_context: planet_auth.Auth):
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
- def from_key(key: str) -> AuthType:
+ def from_key(key: typing.Optional[str]) -> AuthType:
"""Obtain authentication from api key.
Parameters:
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 0d47054e..ced6f084 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -102,7 +102,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
# Aliases
# BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
- _builtin_profile_auth_client_configs = {
+ _builtin_profile_auth_client_configs: Dict[str, dict] = {
# BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_USER: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
@@ -110,7 +110,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
}
- _builtin_profile_aliases = {
+ _builtin_profile_aliases: dict[str, str] = {
# BUILTIN_PROFILE_ALIAS_PLANET_USER: BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID,
}
From b9f90845628f2437d3b61b383a951ebe1586552a Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 17:45:07 -0800
Subject: [PATCH 37/81] disable cache for branch work.
---
.github/workflows/test.yml | 70 +++++++++++++++++++-------------------
1 file changed, 35 insertions(+), 35 deletions(-)
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 0e195388..c03b1e2d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,13 +13,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v2
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ #- name: Pip cache
+ # uses: actions/cache@v2
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -35,13 +35,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v2
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ #- name: Pip cache
+ # uses: actions/cache@v2
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -63,13 +63,13 @@ jobs:
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- - name: Pip cache
- uses: actions/cache@v2
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ #- name: Pip cache
+ # uses: actions/cache@v2
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Test
run: |
pip install --upgrade nox
@@ -85,13 +85,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v2
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ #- name: Pip cache
+ # uses: actions/cache@v2
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Coverage run and report
run: |
pip install --upgrade nox
@@ -107,13 +107,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v2
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ #- name: Pip cache
+ # uses: actions/cache@v2
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Build Docs
run: |
pip install --upgrade nox
From d99d89bf4ff917a4a231f7263213ec6e01667e0c Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 20:28:43 -0800
Subject: [PATCH 38/81] WIP
---
planet/__init__.py | 2 ++
planet/auth.py | 57 +++++++++++++++++++++++++++++------------
planet/auth_builtins.py | 30 ++++++++++++++++++----
tests/unit/test_auth.py | 38 ++++++++++++++++++++++-----
4 files changed, 98 insertions(+), 29 deletions(-)
diff --git a/planet/__init__.py b/planet/__init__.py
index cb410160..d57e68fb 100644
--- a/planet/__init__.py
+++ b/planet/__init__.py
@@ -16,12 +16,14 @@
from . import data_filter, order_request, reporting, subscription_request
from .__version__ import __version__ # NOQA
from .auth import Auth
+from .auth_builtins import PlanetOAuthScopes
from .clients import DataClient, OrdersClient, SubscriptionsClient # NOQA
from .io import collect
from .sync import Planet
__all__ = [
'Auth',
+ 'PlanetOAuthScopes',
'collect',
'DataClient',
'data_filter',
diff --git a/planet/auth.py b/planet/auth.py
index 58f314f0..76956c7f 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -39,7 +39,7 @@ class Auth(metaclass=abc.ABCMeta):
"""Handle authentication information for use with Planet APIs."""
@staticmethod
- def from_user_defaults():
+ def from_user_defaults() -> AuthType:
"""
Create authentication from user defaults. Defaults take into
account environment variables (highest priority), user configuration
@@ -91,37 +91,60 @@ def from_oauth_user_session():
BUILTIN_PROFILE_NAME_PLANET_USER)
return _PLAuthLibAuth(plauth=pl_authlib_context)
- # TODO: I think we need something this for developers of user interactive
+ # TODO:
+ # I think we need something like this for developers of user interactive
# applications (e.g. QGIS), but as of January 2025 we do not have a way
# for developers to register user interactive client on the platform,
# or a way for users of such applications to revoke such authorizations.
# Even without this, we may white glove client IDs for partners before
# it is a generally available feature.
- #
+ # TODO:
+ # This works to initialize the library auth client, but DOES NOT
+ # establish a user session. If on disk storage can be used, that
+ # can be done out of band via the CLI. If in memory operations
+ # are desired, that will not work.
+ # In either case, what needs to happen is that
+ # planet.auth._PLAuthLibAuth._plauth.login() needs to be invoked.
+ # If disk storage is used, that only needs to happen once and the results
+ # will be picked up from disk by this Auth init method. If not,
+ # that needs to happen for every process invocation, since tokens
+ # will not be saved, and refresh cannot be performed.
+ # User experience is greatly served by being able to save to disk.
@staticmethod
- def from_oauth_client_config(client_id: str,
- requested_scopes: List[str],
- token_file_path: str):
+ def beta_from_oauth_client_config(
+ client_id: str,
+ requested_scopes: List[str],
+ save_token_file: bool = True) -> AuthType:
"""
Beta. Feature not yet supported for public use.
"""
- raise NotImplementedError("Feature not implemented yet")
-
plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__SKEL
plauth_config_dict["client_id"] = client_id
- # plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
plauth_config_dict["scopes"] = requested_scopes
# TBD: How flexible will we be in terms of supported flows OAuth flows?
plauth_config_dict["client_type"] = "oidc_device_code"
- pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(
+ # Other client types have other needs.
+ # Confidential clients need client secrets.
+ # Auth code clients need callback URLs.
+ # plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
+
+ # TODO
+ # This will not write the constructed config to the user's
+ # ~/.planet/ dir the way a conf constructed by a cli command like
+ # `planet auth login --client-id XXX --client-secret YYY` will.
+ # The intent of doing it through the planet_auth_utils factory is so we
+ # play well with tooling like the CLI. This maybe does not quite achieve
+ # the desired result. We are saving tokens in the right place, but not
+ # giving the CLI all it needs to co-manage said tokens with whatever app
+ # is being build on the library. Those are perhaps separate decisions,
+ # anyway.
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_with_config(
client_config=plauth_config_dict,
- # Set token_file to 'None' to operate in memory. Set to a path on disk to save
- # refresh tokens. Paths on disk should conform to
- # ~/.planet/<profile>/token.json[.sops] to play well with the CLI
- # managing the same sessions.
- token_file=token_file_path, # profile_name="my_app_name"
- )
+ # TODO - Probably need a user friendly profile name
+ # We should also probably agree with what's registered in the Auth server.
+ profile_name=client_id.lower(),
+ save_token_file=save_token_file)
return Auth.from_plauth(pl_authlib_context)
@staticmethod
@@ -141,7 +164,7 @@ def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
- def from_plauth(pl_authlib_context: planet_auth.Auth):
+ def from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
"""
Create authentication from the provided Planet Auth Library
Authentication Context. Generally, applications will want to use one
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index ced6f084..a36ffdfe 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -12,6 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
import os
+from enum import StrEnum
from typing import Dict, List, Optional
from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
@@ -20,6 +21,17 @@
"PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+class PlanetOAuthScopes(StrEnum):
+ """
+ Planet OAuth2 Scopes
+ """
+ PLANET = "planet"
+ OFFLINE_ACCESS = "offline_access"
+ OPENID = "openid"
+ PROFILE = "profile"
+ EMAIL = "email"
+
+
class _ProductionEnv:
OAUTH_AUTHORITY_USER = {
"_comment": "OIDC/OAuth server used by Planet Public API endpoints",
@@ -46,9 +58,15 @@ class _ProductionEnv:
_OIDC_AUTH_CLIENT_CONFIG__SKEL = {
**_ProductionEnv.OAUTH_AUTHORITY_USER,
- # "client_type": "oidc_device_code",
- # "client_id": _SDK_CLIENT_ID_PROD,
- "scopes": ["planet", "offline_access", "openid", "profile", "email"],
+ "scopes": [
+ PlanetOAuthScopes.PLANET,
+ PlanetOAuthScopes.OFFLINE_ACCESS,
+ # PlanetOAuthScopes.OPENID,
+ # PlanetOAuthScopes.PROFILE,
+ # PlanetOAuthScopes.EMAIL
+ ],
+ # "client_type": "oidc_device_code", # Must be provided when hydrating the SKEL
+ # "client_id": _SDK_CLIENT_ID_PROD, # Must be provided when hydrating the SKEL
}
_OIDC_AUTH_CLIENT_CONFIG__SDK_PROD = {
@@ -56,15 +74,17 @@ class _ProductionEnv:
# Developers should register their own clients so that users may
# manage grants for different applications. Registering applications
# also allows for application specific URLs or auth flow selection.
- **_ProductionEnv.OAUTH_AUTHORITY_USER,
+ **_OIDC_AUTH_CLIENT_CONFIG__SKEL,
"client_type": "oidc_device_code",
"client_id": _SDK_CLIENT_ID_PROD,
- "scopes": ["planet", "offline_access", "openid", "profile", "email"],
+ # FIXME: scopes currently from SKEL.
+ # It would be better to have per-client defaults and limits enforced by the auth server
}
_OIDC_AUTH_CLIENT_CONFIG__M2M_PROD = {
**_ProductionEnv.OAUTH_AUTHORITY_M2M,
"client_type": "oidc_client_credentials_secret",
+ # FIXME: we do not have scope or behavior parity between our M2M and our user OAuth authorities.
"scopes": [],
# "client_id": "__MUST_BE_USER_SUPPLIED__",
# "client_secret": "__MUST_BE_USER_SUPPLIED__",
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index ca335df3..2cc7bf73 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -21,6 +21,7 @@
import planet_auth
import planet.auth_builtins
+from planet.auth_builtins import PlanetOAuthScopes
LOGGER = logging.getLogger(__name__)
@@ -148,20 +149,21 @@ def test_Auth_from_user_defaults():
def test_Auth_from_oauth_m2m():
- under_test = auth.Auth.from_oauth_m2m("mock_client_id",
- "mock_client_secret")
+ under_test = auth.Auth.from_oauth_m2m(
+ "mock_client_id__from_oauth_m2m", "mock_client_secret__from_oauth_m2m")
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
assert isinstance(under_test._plauth.auth_client(),
planet_auth.ClientCredentialsClientSecretAuthClient)
+ assert under_test._plauth.auth_client()._ccauth_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
+
assert under_test._plauth.auth_client()._ccauth_client_config.client_id(
- ) == "mock_client_id"
+ ) == "mock_client_id__from_oauth_m2m"
assert under_test._plauth.auth_client(
- )._ccauth_client_config.client_secret() == "mock_client_secret"
-
- assert under_test._plauth.auth_client()._ccauth_client_config.auth_server(
- ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
+ )._ccauth_client_config.client_secret(
+ ) == "mock_client_secret__from_oauth_m2m"
def test_Auth_from_oauth_user_session():
@@ -170,15 +172,37 @@ def test_Auth_from_oauth_user_session():
assert isinstance(under_test._plauth.auth_client(),
planet_auth.DeviceCodeAuthClient)
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
+ "auth_server"]
+
assert under_test._plauth.auth_client(
)._devicecode_client_config.client_id(
) == planet.auth_builtins._SDK_CLIENT_ID_PROD
+
+def test_Auth_from_oauth_client_config():
+ under_test = auth.Auth.beta_from_oauth_client_config(
+ client_id="mock_client_id__from_oauth_config",
+ requested_scopes=[
+ PlanetOAuthScopes.PLANET, PlanetOAuthScopes.OFFLINE_ACCESS
+ ],
+ save_token_file=False)
+
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.DeviceCodeAuthClient)
+
assert under_test._plauth.auth_client(
)._devicecode_client_config.auth_server(
) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
"auth_server"]
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.client_id(
+ ) == "mock_client_id__from_oauth_config"
+
def test_auth_value_deprecated():
with pytest.raises(DeprecationWarning):
From 20f26e7cc626b062a647ac3c44c1300544fdc65b Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 21 Jan 2025 20:40:38 -0800
Subject: [PATCH 39/81] no StrEnum in lowest supported Py version.
---
planet/auth_builtins.py | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index a36ffdfe..26cd3908 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -12,7 +12,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
import os
-from enum import StrEnum
from typing import Dict, List, Optional
from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
@@ -21,7 +20,9 @@
"PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
-class PlanetOAuthScopes(StrEnum):
+# No StrEnum in our lowest supported Python version
+# class PlanetOAuthScopes(enum.StrEnum):
+class PlanetOAuthScopes:
"""
Planet OAuth2 Scopes
"""
From b5081b2356e878d5bf6a8fcde5e252affd8b3b95 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 22 Jan 2025 11:05:40 -0800
Subject: [PATCH 40/81] cleanup
---
Branch-Working-and-Release-Notes.txt | 8 --------
OAuth-Reviewer-and-Release-Notes.md | 12 ++++++++++--
docs/cli/cli-guide.md | 10 +++++-----
planet/auth_builtins.py | 2 +-
4 files changed, 16 insertions(+), 16 deletions(-)
delete mode 100644 Branch-Working-and-Release-Notes.txt
diff --git a/Branch-Working-and-Release-Notes.txt b/Branch-Working-and-Release-Notes.txt
deleted file mode 100644
index 1ac8a82f..00000000
--- a/Branch-Working-and-Release-Notes.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-- Replaced most user auth code with the planet auth library. This brings with it OAuth for user interactive and M2M flows.
-- Deprecated the old auth command. New auth command is implemented with the separate auth library
- - TODO: link to lib
- - planet auth init -> planet auth oauth login (or, planet --auth-profile legacy auth legacy login)
- - planet auth value -> planet plauth oauth print-access-token (or planet --auth-profile legacy auth legacy print-api-key)
-- The legacy secret file has largely been deprecated. This will require a user migration.
-# TODO: hide command line options not needed for the SDK (Maybe bring back a simpler built-in auth command)
-# TODO: we need to allocate a client ID for the `planet` CLI. We are presently leaning on plauth's client ID. (maybe this is OK)
diff --git a/OAuth-Reviewer-and-Release-Notes.md b/OAuth-Reviewer-and-Release-Notes.md
index b5180bc6..48d850fa 100644
--- a/OAuth-Reviewer-and-Release-Notes.md
+++ b/OAuth-Reviewer-and-Release-Notes.md
@@ -1,6 +1,6 @@
# Overview
* Auth functions are now implemented by the `planet_auth` and
- `planet_auth_utils` libraries
+ `planet_auth_utils` libraries.
* The use of API keys and Planet's legacy username/password based
authentication protocol is being phased out in favor of OAuth2 based
mechanisms. These legacy mechanisms remain in place for the time being,
@@ -41,9 +41,10 @@
`plauth` command line utility for expert use cases.
# Library API changes
-*
+* TODO - Document
# On-disk interface changes
+* TODO - Document
# Misc Notes
* The interfaces for the `planet_auth` and `planet_auth_utils` libraries are
@@ -52,3 +53,10 @@
# Release Sequencing & Requirements
* Planet APIs need to accept SH M2M tokens.
* Users/Admins need a good way to register/manage M2M clients.
+
+
+# Branch TODO
+- I think this bumps to version 3
+- update API docs
+- Update example docs
+- Update new dev center docs
diff --git a/docs/cli/cli-guide.md b/docs/cli/cli-guide.md
index f2fec6e8..090d1478 100644
--- a/docs/cli/cli-guide.md
+++ b/docs/cli/cli-guide.md
@@ -34,13 +34,13 @@ Yes. Even if you’re not writing code—and only using the "no code" CLI part o
Install the Planet SDK for Python using [pip](https://pip.pypa.io):
```console
-$ pip install planet
+pip install planet
```
## Step 3: Check the Planet SDK for Python version
```console
-$ planet --version
+planet --version
```
You should be on some version 2 of the Planet SDK for Python.
@@ -60,12 +60,12 @@ Just as you log in when you browse to https://planet.com/account, you’ll want
At a terminal console, type the following Planet command:
```console
-$ planet auth login
+planet auth login
```
A browser window should be opened, and you will be directed to login to your account. This
command will wait for the browser login to complete, and should exit shortly afterwards.
-When this process succeeds you should see the following message on the console:
+When this process succeeds, you will see the following message on the console:
```console
Login succeeded.
@@ -74,7 +74,7 @@ Login succeeded.
If you are in an environment where the `planet` command line utility cannot open a browser (such
as a remote shell on a cloud service provider), use the following command and follow the instructions:
```console
-$ planet auth login --no-open-browser
+planet auth login --no-open-browser
```
### Get your Access Token
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 26cd3908..0d960f2c 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
From c8350f7be02ed107cbdb0acea012407b64872200 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 27 Jan 2025 10:48:37 +0100
Subject: [PATCH 41/81] implement suggestions from the team
---
planet/cli/auth.py | 100 ++++++++++++---------------------------------
planet/cli/cli.py | 2 +-
2 files changed, 27 insertions(+), 75 deletions(-)
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index 979dfb1f..7f8d67a0 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -1,4 +1,4 @@
-# Copyright 2022 Planet Labs PBC.
+# Copyright 2022-2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -13,84 +13,36 @@
# limitations under the License.
"""Auth API CLI"""
import logging
-
import click
-
-import planet_auth
import planet_auth_utils
-from .cmds import translate_exceptions
-from ..auth_builtins import _BuiltinConfigurationProvider
LOGGER = logging.getLogger(__name__)
-@click.group() # type: ignore
+@click.group("auth") # type: ignore
@click.pass_context
-def auth(ctx):
- """Commands for working with Planet authentication"""
- # Override the default current_auth_context stored in ctx.obj["AUTH"]
- # for legacy auth sub-commands. The planet_auth_utils library provides very
- # generic utility commands, and the click commands it provides do not know
- # about specific deployments. This library is specifically geared
- # for the customer facing Planet Insights Platform, and provides
- # built-in configurations for the public API surface area.
- #
- # We also employ bit of hackery to maintain old behavior - point
- # FileBackedPlanetLegacyApiKey (the "Credential" or "token_file") to the
- # ~/.planet.json file nominally used by PlanetAuthUserConfig. A common
- # base class is used to model these separate use cases, and plays well
- # with merged key sets. planet_auth_utils uses this file for more than
- # just storing the API key, and nominally stores legacy API keys in a
- # different location(s). This planet SDK historically only stored an
- # API key in this file.
- if (ctx.invoked_subcommand == "init" or ctx.invoked_subcommand == "value"
- or ctx.invoked_subcommand == "store"):
- # click.echo("Overriding Auth Profile with legacy auth profile.")
- ctx.obj[
- "AUTH"] = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_profile_opt=_BuiltinConfigurationProvider.
- BUILTIN_PROFILE_NAME_LEGACY,
- token_file_opt=planet_auth_utils.PlanetAuthUserConfig.
- default_user_config_file())
-
-
-@auth.command(name="store", deprecated=True) # type: ignore
-@translate_exceptions
-@click.argument('key')
-def store(key):
- """Store authentication information"""
- if click.confirm('This overrides the stored value. Continue?'):
- # See above. A bit of hackery around the token_file to maintain old interface.
- token_file = planet_auth.FileBackedJsonObject(
- file_path=planet_auth_utils.PlanetAuthUserConfig.
- default_user_config_file())
- try:
- token_file.load()
- conf_data = token_file.data()
- except FileNotFoundError:
- conf_data = {}
-
- conf_data["key"] = key
- token_file.set_data(conf_data)
- token_file.save()
-
-
-# We implement the "planet auth" sub-command in terms of the planet_auth_utils
-# click commands as much as we can.
-
-auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
-auth.add_command(name="print-access-token",
- cmd=planet_auth_utils.cmd_oauth_print_access_token)
-auth.add_command(name="profile-list", cmd=planet_auth_utils.cmd_profile_list)
-auth.add_command(name="profile-show", cmd=planet_auth_utils.cmd_profile_show)
-auth.add_command(name="profile-set", cmd=planet_auth_utils.cmd_profile_set)
-
-planet_auth_utils.cmd_pllegacy_login.name = "init"
-planet_auth_utils.cmd_pllegacy_login.deprecated = True
-auth.add_command(name="init", cmd=planet_auth_utils.cmd_pllegacy_login)
-
-planet_auth_utils.cmd_pllegacy_print_api_key.name = "value"
-planet_auth_utils.cmd_pllegacy_print_api_key.deprecated = True
-auth.add_command(name="value",
- cmd=planet_auth_utils.cmd_pllegacy_print_api_key)
+def cmd_auth(ctx):
+ """
+ Commands for working with Planet authentication.
+ """
+
+cmd_auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
+cmd_auth.add_command(name="print-access-token",
+ cmd=planet_auth_utils.cmd_oauth_print_access_token)
+cmd_auth.add_command(name="refresh",
+ cmd=planet_auth_utils.cmd_oauth_refresh)
+
+# We are only plumbing a sub-set of the util lib's "profile" command,
+# which is why we shadow it.
+@click.group("profile")
+@click.pass_context
+def cmd_auth_profile(ctx):
+ """
+ Manage auth profiles.
+ """
+
+cmd_auth_profile.add_command(name="list", cmd=planet_auth_utils.cmd_profile_list)
+cmd_auth_profile.add_command(name="show", cmd=planet_auth_utils.cmd_profile_show)
+cmd_auth_profile.add_command(name="set", cmd=planet_auth_utils.cmd_profile_set)
+cmd_auth.add_command(cmd_auth_profile)
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index 04861cfe..e43b2b88 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -118,7 +118,7 @@ def _configure_logging(verbosity):
main.add_command(cmd=planet_auth_utils.cmd_plauth_embedded,
name="plauth") # type: ignore
-main.add_command(auth.auth) # type: ignore
+main.add_command(auth.cmd_auth) # type: ignore
main.add_command(data.data) # type: ignore
main.add_command(orders.orders) # type: ignore
main.add_command(subscriptions.subscriptions) # type: ignore
From 158e29d9189869f9b32a34b556bff9c36a12ae3c Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 27 Jan 2025 10:50:51 +0100
Subject: [PATCH 42/81] linting fixes
---
planet/cli/auth.py | 3 +++
1 file changed, 3 insertions(+)
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index 7f8d67a0..4455733e 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -27,12 +27,14 @@ def cmd_auth(ctx):
Commands for working with Planet authentication.
"""
+
cmd_auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
cmd_auth.add_command(name="print-access-token",
cmd=planet_auth_utils.cmd_oauth_print_access_token)
cmd_auth.add_command(name="refresh",
cmd=planet_auth_utils.cmd_oauth_refresh)
+
# We are only plumbing a sub-set of the util lib's "profile" command,
# which is why we shadow it.
@click.group("profile")
@@ -42,6 +44,7 @@ def cmd_auth_profile(ctx):
Manage auth profiles.
"""
+
cmd_auth_profile.add_command(name="list", cmd=planet_auth_utils.cmd_profile_list)
cmd_auth_profile.add_command(name="show", cmd=planet_auth_utils.cmd_profile_show)
cmd_auth_profile.add_command(name="set", cmd=planet_auth_utils.cmd_profile_set)
From 3c374ac933a76a26bdc480c4c838fd15ef14791f Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 27 Jan 2025 10:53:29 +0100
Subject: [PATCH 43/81] yapf antidepressants
---
planet/cli/auth.py | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/planet/cli/auth.py b/planet/cli/auth.py
index 4455733e..470c6462 100644
--- a/planet/cli/auth.py
+++ b/planet/cli/auth.py
@@ -16,7 +16,6 @@
import click
import planet_auth_utils
-
LOGGER = logging.getLogger(__name__)
@@ -31,8 +30,7 @@ def cmd_auth(ctx):
cmd_auth.add_command(name="login", cmd=planet_auth_utils.cmd_plauth_login)
cmd_auth.add_command(name="print-access-token",
cmd=planet_auth_utils.cmd_oauth_print_access_token)
-cmd_auth.add_command(name="refresh",
- cmd=planet_auth_utils.cmd_oauth_refresh)
+cmd_auth.add_command(name="refresh", cmd=planet_auth_utils.cmd_oauth_refresh)
# We are only plumbing a sub-set of the util lib's "profile" command,
@@ -45,7 +43,9 @@ def cmd_auth_profile(ctx):
"""
-cmd_auth_profile.add_command(name="list", cmd=planet_auth_utils.cmd_profile_list)
-cmd_auth_profile.add_command(name="show", cmd=planet_auth_utils.cmd_profile_show)
+cmd_auth_profile.add_command(name="list",
+ cmd=planet_auth_utils.cmd_profile_list)
+cmd_auth_profile.add_command(name="show",
+ cmd=planet_auth_utils.cmd_profile_show)
cmd_auth_profile.add_command(name="set", cmd=planet_auth_utils.cmd_profile_set)
cmd_auth.add_command(cmd_auth_profile)
From 646324f4194d01059fd5a90a7972f012dab86c44 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 19 Feb 2025 14:09:20 -0800
Subject: [PATCH 44/81] Initial auth examples
---
docs/cli/cli-reference.md | 2 +
docs/get-started/quick-start-guide.md | 7 +-
docs/python/sdk-client-auth.md | 369 ++++++++++++++++++
docs/python/sdk-guide.md | 27 +-
...auth_state__app_custom_storage__api_key.py | 1 +
..._managed_auth_state__in_memory__api_key.py | 27 ++
...anaged_auth_state__in_memory__oauth_m2m.py | 31 ++
...mory__oauth_user_authcode__with_browser.py | 38 ++
...oauth_user_devicecode__external_browser.py | 78 ++++
...auth_state__on_disk_cli_shared__api_key.py | 1 +
...th_state__on_disk_cli_shared__oauth_m2m.py | 32 ++
...ared__oauth_user_authcode__with_browser.py | 38 ++
...oauth_user_devicecode__external_browser.py | 80 ++++
...ged_auth_state__on_disk_legacy__api_key.py | 26 ++
.../cli_managed_auth_state__explicit.py | 25 ++
.../cli_managed_auth_state__implicit.py | 21 +
...naged_auth_state__specific_auth_profile.py | 28 ++
.../legacy_api_key_file.json | 3 +
mkdocs.yml | 4 +
pyproject.toml | 1 +
20 files changed, 819 insertions(+), 20 deletions(-)
create mode 100644 docs/python/sdk-client-auth.md
create mode 100644 examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py
create mode 100644 examples/auth-session-management/cli_managed_auth_state__explicit.py
create mode 100644 examples/auth-session-management/cli_managed_auth_state__implicit.py
create mode 100644 examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
create mode 100644 examples/auth-session-management/legacy_api_key_file.json
diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md
index a3500cee..bf2107f6 100644
--- a/docs/cli/cli-reference.md
+++ b/docs/cli/cli-reference.md
@@ -4,8 +4,10 @@ title: CLI Reference
This page provides documentation for our command line tools.
+{% raw %}
::: mkdocs-click
:module: planet.cli.cli
:command: main
:prog_name: planet
:depth: 1
+{% endraw %}
diff --git a/docs/get-started/quick-start-guide.md b/docs/get-started/quick-start-guide.md
index 28abcf8d..795af000 100644
--- a/docs/get-started/quick-start-guide.md
+++ b/docs/get-started/quick-start-guide.md
@@ -27,10 +27,11 @@ pip install planet
### Authentication
-Use the `PL_API_KEY` environment variable to authenticate with the Planet API. For other authentication options, see the [SDK guide](../python/sdk-guide.md).
+Use the `planet auth` CLI command to establish a user login session that will be saved to the user's home directory.
+For other authentication options, see the [Client Authentication Guide](../python/sdk-client-auth.md).
```bash
-export PL_API_KEY=your_api_key
+planet auth login
```
### The Planet client
@@ -39,7 +40,7 @@ The `Planet` class is the main entry point for the Planet SDK. It provides acces
```python
from planet import Planet
-pl = Planet() # automatically detects PL_API_KEY
+pl = Planet() # automatically detects authentication configured by `planet auth login`
```
The Planet client has members `data`, `orders`, and `subscriptions`, which allow you to interact with the Data API, Orders API, and Subscriptions API. Usage examples for searching, ordering and creating subscriptions can be found in the [SDK guide](../python/sdk-guide.md).
diff --git a/docs/python/sdk-client-auth.md b/docs/python/sdk-client-auth.md
new file mode 100644
index 00000000..b52b1a82
--- /dev/null
+++ b/docs/python/sdk-client-auth.md
@@ -0,0 +1,369 @@
+# Client Authentication Guide
+
+[TOC]
+
+----
+
+## Introduction
+All calls to Planet APIs must be authenticated. Only authorized clients may
+use Planet Platform APIs.
+
+For general information on how to authenticate to Planet APIs, please see
+the [Authentication](https://docs.planet.com/develop/authentication) section of Planet's platform documentation.
+
+!!! warning
+ Some statements are forward-looking. OAuth2 M2M tokens are
+ currently only supported by `services.sentine-hub.com` and not supported
+ by `api.planet.com`. All APIs support interactive user OAuth2 access
+ tokens, but a process for developers to register and manage clients has
+ not yet been made public. We have also not yet release a way for end-users
+ of such applications to manage which applications have been authorized
+ to access the platform on their behalf.
+
+----
+## Authentication Protocols
+At the API protocol level underneath the SDK, there are several distinct
+ways a client may authenticate to the Planet APIs, depending on the use case:
+
+* **OAuth2 user access tokens** - API access as the end-user, using OAuth2
+user access tokens. This is the preferred way for user interactive
+applications to authenticate to Planet APIs. A web browser is required
+to initialize a session, but not required for continued operation.
+* **OAuth2 M2M access tokens** - API access as a service user, using OAuth2
+M2M access tokens. This is the preferred way for automated processes
+to authenticate to Planet APIs that must operate without a human user.
+No web browser is required, but this method carries some additional
+security considerations.
+* **Planet API keys** - API access as a planet end-user using a simple
+fixed string bearer key. This method is being targeted for deprecation.
+
+### OAuth2
+OAuth2 authentication requires that the client possesses an access token
+in order to make API calls. Access tokens are obtained by the client from
+the Planet authorization server that is separate from the API servers, and are
+presented by the client to API services to prove the client's right to make
+API calls.
+
+Unlike Planet API keys, access tokens do not last forever for a variety of
+reasons and must be regularly refreshed by the client before their expiration.
+However, clients should not refresh access tokens for every API call; clients
+that misbehave in this way will be throttled by the authorization service,
+potentially losing access to APIs.
+
+When using the Planet SDK, the many of the details of obtaining and refreshing
+OAuth2 access tokens will be taken care of for you.
+
+Planet OAuth2 access tokens will work for all Planet APIs underneath
+both the `api.planet.com` and `services.sentinel-hub.com` domains.
+
+Planet Access tokens conform to the JSON Web Token (JWT) specification.
+Tokens may be inspected to determine their expiration time, which will be
+in the `exp` claim.
+
+!!! note
+ Clients should generally treat the access tokens as opaque bearer tokens.
+ While JWTs are open for inspection, Planet does not guarantee the stability
+ of undocumented claims. Rely only on those documented here.
+
+More information regarding OAuth2 and JWTs may be found here:
+
+* [RFC 6749 - The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
+* [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628)
+* [RFC 7519 - JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
+* [RFC 9068 - JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068)
+
+#### OAuth2 Client Registration
+!!! TODO
+ * link to docs for this process
+ * discuss registering a interactive client (that will access Planet
+ as the user) vs registering a M2M client identity (which is really
+ more like creating a new user) vs registering a confidential client.
+ discuss native vs web clients.
+
+Developers of applications must register client applications with Planet, and
+will be issued a Client ID as part of that process. Developers should register
+a client for each distinct application so that end-users may discretely manage
+applications permitted to access Planet APIs on their behalf.
+
+### Planet API Keys
+Planet API keys are simple fixed strings that may be presented by the client
+to API services that assert the client's right to access APIs. API keys are
+obtained by the user from their account page, and provided to the client
+so that it may make API calls on the user's behalf.
+
+Planet API keys are simpler to use than OAuth2, but are considered less secure
+in many ways. Because of this, Planet API keys are targeted for eventual
+deprecation. Support for this method is maintained for continuity
+while OAuth2 based methods are being rolled out across all Planet APIs and
+clients.
+
+Planet API Keys will work for Planet APIs underneath `api.planet.com`, but
+will **NOT** work for APIs underneath `services.sentinel-hub.com`.
+
+----
+## Authentication with the SDK
+
+Before any calls can be made to a Planet API using the SDK, it is
+necessary for the user to login and establish an authentication session.
+Exactly how this should be done with the SDK depends on the
+application's complexity and needs.
+
+In simple cases, this may be managed external to the application
+by using the [`planet auth`](../../cli/cli-reference/#auth)
+command line utility.
+
+In more complex cases, an application may need to manage the
+stored session itself independent of utilities provided by the CLI. In such
+cases the application will be responsible for instantiating a `planet.Auth`
+object, initiating user login, and saving the session resulting information.
+Session information may contain sensitive information such as access and
+refresh tokens, and must be stored securely by the application. Session
+information will also be regularly updated during SDK operations, so the
+application must handle keeping the saved session information up-to-date.
+
+Regardless of which authentication protocol is used, the SDK encapsulates
+the details with
+[`planet.Auth`](../sdk-reference/#planet.auth.Auth) and
+[`planet.Session`](../sdk-reference/#planet.http.Session).
+
+#### Session State Storage
+
+Once a user login session is established using any method, the state should be
+saved to secure persistent storage to allow for continued access to the Planet
+platform without the need to perform the login repeatedly. If state cannot
+be persisted in the application environment, the application can operate in
+in-memory mode, and will be forced create a new login session every time the
+application is run. In some cases, this may result in throttling by the
+authorization service.
+
+The SDK provides a way to stave session state in the user's home directory in
+a way that is compatible with the CLI. The SDK also provides a way for the
+application to provide its own secure storage.
+
+!!! TODO
+ We have yet to document how to use application provided storage.
+
+### Using `planet auth` CLI Managed Auth Session
+For simple programs and scripts, it is easiest for the program to defer
+session management to the [`planet auth`](../../cli/cli-reference/#auth)
+CLI. This method will store session information in the user's home directory
+in the `~/.planet.json` file and `~/.planet/` directory. The python SDK will
+use the information saved in these locations to make API calls.
+
+When this approach is taken, the authentication session will be shared between
+actions taken by the `planet` utility, and those taken by the programs built
+using the SDK. Changes made by one will impact the behavior of the other.
+
+**Requirements and Limitations:**
+
+* The program must have read and write access to the user's home directory.
+* This method requires that the end-user has access to and understands
+ the `planet` CLI command needed to manage session authentication.
+* This approach should not be used on public terminals or in cases where the
+ user's home directory cannot be kept confidential.
+
+#### Initialize Session - Login
+Session login can be performed using the following command. This command can
+be used to initialize sessions using any of the authentication methods
+discussed above, and will default to creating an OAuth2 user session.
+Refer to the command's `--help` for more information.
+```shell title="Initialize session using planet CLI"
+planet auth login
+```
+
+#### Using Saved Session
+Using the CLI managed session is the default behavior for SDK functions.
+Developing an application that uses this session requires no additional
+action by the developer. When a developer chooses to create an application
+that behaves in this way, it will most often be done implicitly by relying
+on SDK default behavior, but it may also be done explicitly.
+
+```python linenums="1" title="Implicitly use CLI managed login sessions"
+{% include 'auth-session-management/cli_managed_auth_state__implicit.py' %}
+```
+
+```python linenums="1" title="Explicitly use CLI managed login sessions"
+{% include 'auth-session-management/cli_managed_auth_state__explicit.py' %}
+```
+
+```python linenums="1" title="Use a specific session that is shared with the CLI"
+{% include 'auth-session-management/cli_managed_auth_state__specific_auth_profile.py' %}
+
+```
+
+### Manually Creating a Session Using Library Functions
+If an application cannot or should not use a login session initiated by the
+`planet auth` CLI command, it will be responsible for managing the process on
+its own, persisting session state as needed.
+
+The process differs slightly for applications accessing Planet services on behalf
+of a human user verses accessing Planet services using a service account. Depending
+on the use case, applications may need to support one or the other or both (just
+as the `planet` CLI command supports both methods).
+
+#### OAuth2 Session for Users
+User session initialization inherently involves using a web browser to
+complete user authentication. This architecture allows for greater security
+by keeping the user's password from being directly exposed to the application
+code. This also allows for flexibility in user federation and multifactor
+authentication procedures without the complexity of these needing to
+be exposes to the application developer who is focused on geospatial
+operations using the Planet platform, and not the nuances of user
+authentication and authorization.
+
+##### With a Local Web Browser
+In environments where a local browser is available, the Planet SDK can manage
+the process of launching the browser locally, transferring control to the Planet
+authorization services for session initialization, and accepting a network
+callback from the browser to regain control once the authorization process is
+complete. At a network protocol level, this is establishing the user login
+session using the OAuth2 authorization code flow.
+
+To use this method using the SDK, the following requirements must be met:
+
+* The application must be able to launch a local web browser.
+* The web browse must be able to connect to Planet services.
+* The application must be able to listen on a network port that is accessible
+ to the browser.
+
+###### Examples - Authorization Code Flow
+```python linenums="1" title="Login as a user using a local browser with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py' %}
+```
+
+```python linenums="1" title="Login as a user using a local browser with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py' %}
+```
+
+```python linenums="1" title="Login as a user using a local browser with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py' %}
+```
+
+##### Without a Local Web Browser
+In environments where a local web browsers is not available the process above
+will not work. For example, a remote shell to a cloud environment is not likely
+to be able to open a browser on the user's desktop or receive network callbacks
+from the user's desktop browser. In these cases, a browser is
+still required. To login in such a case the SDK will generate a URL and a
+verification code that must be presented to the user. The user must visit the
+URL out of band to complete the login process while the application polls for
+the completion of the login process using the SDK. At a network protocol
+level, this is establishing the user login session using the OAuth2 device
+code flow.
+
+To use this method using the SDK, the following requirements must be met:
+
+* The application must be able to connect to Planet services.
+* The application must be able to display instructions to the user, directing
+ them to a web location to complete login.
+
+###### Examples - Device Code Flow
+```python linenums="1" title="Login as a user using an external browser with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py' %}
+```
+
+```python linenums="1" title="Login as a user using an external browser with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py' %}
+```
+
+```python linenums="1" title="Login as a user using an external browser with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py' %}
+```
+
+#### OAuth2 Session for Service Accounts
+Service account session initialization is simpler than user session
+initialization, and does not require a web browser.
+
+While preserving session state for user sessions was a concern driven
+in part by a concern for the user experience of using a web browser for
+initialization, for service account it remains a concern to avoid
+throttling by the authorization service.
+
+If applications are expected to run longer than the life of an access token
+(a few hours), then in memory operations are acceptable (for example: a long
+running data processing job). If application lifespan is short and frequent,
+than the application should still take steps to persist the session state (for
+example: a command line utility run from a shell with a short lifespan).
+
+Like session state, service account initialization parameters are
+sensitive, and it is the responsibility of the application to store them
+securely.
+
+At a network protocol level, OAuth2 service account sessions are implemented
+using the OAuth2 authorization code flow. This carries with it some additional
+security considerations, discussed in
+[RFC 6819 §4.4.4](https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.4).
+Because of these consideration, service accounts should ideally only be used
+for workflows that are independent of a controlling user.
+
+##### Examples - Client Credentials Flow
+```python linenums="1" title="Access APIs using a service account with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py' %}
+```
+
+```python linenums="1" title="Access APIs using a service account with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py' %}
+```
+
+```python linenums="1" title="Access APIs using a service account with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py' %}
+```
+
+#### Planet API Key Sessions
+Legacy applications that need to continue to support Planet API keys may do so
+until API keys are deprecated. This method should not be adopted for new
+development.
+
+##### Examples - Planet API Keys
+
+```python linenums="1" title="Access APIs using Planet API keys in memory"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__api_key.py' %}
+```
+
+```python linenums="1" title="Access APIs using Planet API keys using the on disk file format used by older versions of the SDK"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py' %}
+```
+
+```json linenums="1" title="Legacy API Key file"
+{% include 'auth-session-management/legacy_api_key_file.json' %}
+```
+
+```python linenums="1" title="Access APIs using Planet API keys with CLI managed shared state on disk"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py' %}
+```
+
+```python linenums="1" title="Access APIs using Planet API keys using legacy on disk persistance"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py' %}
+```
+
+## OAuth2 Scopes
+OAuth2 uses scopes to allow users to limit how much access clients have to the Planet
+service on their behalf.
+
+* **`planet`** - Use this scope to request access to Planet APIs.
+* **`offline_acess`** - Use this scope to request a refresh token. This may
+ only be requested by clients that access APIs on behalf of a user. M2M
+ clients may not request this scope.
+
+
+## Environment Variables
+When session information is not explicitly configured, the following environment variables
+will influence the library behavior when initialized to user default preferences.
+
+* **`PL_AUTH_PROFILE`** - Specify a custom CLI managed auth client profile by name.
+* **`PL_AUTH_CLIENT_ID`** - Specify an OAuth2 M2M client ID.
+* **`PL_AUTH_CLIENT_SECRET`** - Specify an OAuth2 M2M client secret.
+* **`PL_AUTH_API_KEY`** - Specify a legacy Planet API key.
+----
+
+
+## Web Services
+!!! TODO
+ All of the above really deals with native applications running in an
+ environment controlled by the end-user. The considerations
+ are different if the application being developed is a web service where
+ the end-user is not directly accessing Planet APIs. This involves
+ "Confidential" OAuth2 client configurations, and needs to be documented
+ here.
+
+----
diff --git a/docs/python/sdk-guide.md b/docs/python/sdk-guide.md
index 4c8f3791..c9366210 100644
--- a/docs/python/sdk-guide.md
+++ b/docs/python/sdk-guide.md
@@ -23,32 +23,26 @@ The `Planet` class is the main entry point for the Planet SDK. It provides acces
```python
from planet import Planet
-pl = Planet() # automatically detects PL_API_KEY
+pl = Planet() # automatically detects authentication configured by `planet auth login`
```
The Planet client has members `data`, `orders`, and `subscriptions`, which allow you to interact with the Data API, Orders API, and Subscriptions API.
### Authentication
-
-Use the `PL_API_KEY` environment variable to authenticate with the Planet API.
+To establish a user session that will be saved to the user's home directory
+and will be picked up by the SDK, execute the following command:
```bash
-export PL_API_KEY=your_api_key
+planet auth login
```
-These examples will assume you are using the `PL_API_KEY` environment variable. If you are, you can skip to the next section.
-
-#### Authenticate using the Session class
-
-Alternately, you can also authenticate using the `Session` class:
-
-```python
-from planet import Auth, Session, Auth
-from planet.auth import APIKeyAuth
-
-pl = Planet(session=Session(auth=APIKeyAuth(key='your_api_key')))
-```
+These examples will assume you have done this, and are using the SDK's default
+client authentication mechanisms. If you are not, please see the
+[Client Authentication Guide](sdk-client-auth.md) for a complete discussion of
+all authentication options provided by the SDK. This includes user
+authentication with a web browser, service account authentication for detached
+workloads, and support for legacy authentication mechanisms.
### Search
@@ -280,4 +274,3 @@ If there's something you're missing or are stuck, the development team would lov
- To report a bug or suggest a feature, [raise an issue on GitHub](https://github.com/planetlabs/planet-client-python/issues/new)
- To get in touch with the development team, email [developers@planet.com](mailto:developers@planet.com)
-
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
new file mode 100644
index 00000000..ccbb1b93
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
@@ -0,0 +1 @@
+# No example of this use case provided at this time
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
new file mode 100644
index 00000000..9e05f187
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
@@ -0,0 +1,27 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with the specified API key
+ plsdk_auth = planet.Auth.from_key(
+ key="__PLANET_API_KEY_MUST_BE_END_USER_SUPPLIED__"
+ )
+
+ # Explicit login is not required for API key use. The above sufficient.
+ # plsdk_auth.user_login()
+
+ # Create a Planet SDK object that uses the loaded auth session
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
new file mode 100644
index 00000000..c28d1c9b
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
@@ -0,0 +1,31 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_m2m(
+ client_id="__MUST_BE_END_USER_SUPPLIED__",
+ client_secret="__MUST_BE_END_USER_SUPPLIED__",
+ save_state_to_disk=False,
+ )
+
+ # Explicit login is not required for M2M client use. The above sufficient.
+ # plsdk_auth.user_login()
+
+ # Create a Planet SDK object that uses the loaded auth session/
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
new file mode 100644
index 00000000..2bcc44c8
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
@@ -0,0 +1,38 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_auth_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ callback_url="http://localhost:8080",
+ save_state_to_disk=False,
+ )
+
+ # An application with no persistent storage must
+ # initialize a login every time. This is not smooth user experience.
+ plsdk_auth.user_login(allow_open_browser=True)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
new file mode 100644
index 00000000..c35d0ea4
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
@@ -0,0 +1,78 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def initiate_user_session(plsdk_auth):
+ # Example of initiating a user session where the app is 100%
+ # responsible for the user experience.
+
+ # 1. Initiate the login
+ login_initialization_info = plsdk_auth.device_user_login_initiate()
+
+ # 2. Display necessary instructions to the user.
+ #
+ # "verification_uri" and "user_code" are required under RFC 8628.
+ # "verification_uri_complete" is optional under the RFC.
+ #
+ # If the user is expected to type in the URL, verification_uri will be
+ # shorter. If the URL may be presented in a clickable means (such as a
+ # link, button, or QR code) the verification_uri_complete may offer a
+ # better user experience.
+ verification_uri_complete = login_initialization_info.get("verification_uri_complete")
+ verification_uri = login_initialization_info.get("verification_uri")
+ user_code = login_initialization_info.get("user_code")
+
+ print("Please activate your client.")
+ if verification_uri_complete:
+ print(
+ f"Visit the activation site:\n"
+ f"\n\t{verification_uri_complete}\n"
+ f"\nand confirm the authorization code:\n"
+ f"\n\t{user_code}\n"
+ )
+ else:
+ print(
+ f"Visit the activation site:\n"
+ f"\n\t{verification_uri}\n"
+ f"\nand enter the authorization code:\n"
+ f"\n\t{user_code}\n"
+ )
+
+ # 3. Return control to the SDK. This will block until the user
+ # completes login.
+ plsdk_auth.device_user_login_complete(login_initialization_info)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_device_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ save_state_to_disk=False,
+ )
+
+ # An application with no persistent storage must initialize a login every
+ # time. This is not smooth user experience.
+ initiate_user_session(plsdk_auth)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
new file mode 100644
index 00000000..ccbb1b93
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
@@ -0,0 +1 @@
+# No example of this use case provided at this time
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
new file mode 100644
index 00000000..89fd221a
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
@@ -0,0 +1,32 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_m2m(
+ client_id="__MUST_BE_END_USER_SUPPLIED__",
+ client_secret="__MUST_BE_END_USER_SUPPLIED__",
+ profile_name="my-name-for-example-m2m-auth-profile",
+ save_state_to_disk=True,
+ )
+
+ # Explicit login is not required for M2M client use. The above sufficient.
+ # plsdk_auth.user_login()
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
new file mode 100644
index 00000000..9d05a7cb
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
@@ -0,0 +1,38 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_auth_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ callback_url="http://localhost:8080",
+ profile_name="my-name-for-example-user-interactive-app-with-local-browser",
+ save_state_to_disk=True,
+ )
+
+ if not plsdk_auth.is_initialized():
+ plsdk_auth.user_login(allow_open_browser=True)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
new file mode 100644
index 00000000..c002bc7e
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
@@ -0,0 +1,80 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def initiate_user_session(plsdk_auth):
+ # Example of initiating a user session where the app is 100%
+ # responsible for the user experience.
+
+ # 1. Initiate the login
+ login_initialization_info = plsdk_auth.device_user_login_initiate()
+
+ # 2. Display necessary instructions to the user.
+ #
+ # "verification_uri" and "user_code" are required under RFC 8628.
+ # "verification_uri_complete" is optional under the RFC.
+ #
+ # If the user is expected to type in the URL, verification_uri will be
+ # shorter. If the URL may be presented in a clickable means (such as a
+ # link, button, or QR code) the verification_uri_complete may offer a
+ # better user experience.
+ verification_uri_complete = login_initialization_info.get("verification_uri_complete")
+ verification_uri = login_initialization_info.get("verification_uri")
+ user_code = login_initialization_info.get("user_code")
+
+ print("Please activate your client.")
+ if verification_uri_complete:
+ print(
+ f"Visit the activation site:\n"
+ f"\n\t{verification_uri_complete}\n"
+ f"\nand confirm the authorization code:\n"
+ f"\n\t{user_code}\n"
+ )
+ else:
+ print(
+ f"Visit the activation site:\n"
+ f"\n\t{verification_uri}\n"
+ f"\nand enter the authorization code:\n"
+ f"\n\t{user_code}\n"
+ )
+
+ # 3. Return control to the SDK. This will block until the user
+ # completes login.
+ plsdk_auth.device_user_login_complete(login_initialization_info)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_device_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ profile_name="my-name-for-example-user-interactive-app-with-external-browser",
+ save_state_to_disk=True,
+ )
+
+ # An application with no persistent storage must initialize a login every
+ # time. This is not smooth user experience.
+ if not plsdk_auth.is_initialized():
+ initiate_user_session(plsdk_auth)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py b/examples/auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py
new file mode 100644
index 00000000..a1425759
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py
@@ -0,0 +1,26 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Create an auth context with a Planet API key loaded from the
+ # specified file that was created with older versions of the SDK
+ plsdk_auth = planet.Auth.from_file("legacy_api_key_file.json")
+
+ # Explicit login is not required for API key use. The above sufficient.
+ # plsdk_auth.user_login()
+
+ # Create a Planet SDK object that uses the loaded auth session
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/cli_managed_auth_state__explicit.py b/examples/auth-session-management/cli_managed_auth_state__explicit.py
new file mode 100644
index 00000000..aa40ffbb
--- /dev/null
+++ b/examples/auth-session-management/cli_managed_auth_state__explicit.py
@@ -0,0 +1,25 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Explicitly load the user's auth session from disk. The user must have
+ # invoked `planet auth login` before this program is run, or the API calls
+ # will fail. This will not initialize a new session.
+ plsdk_auth = planet.Auth.from_user_default_session()
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/cli_managed_auth_state__implicit.py b/examples/auth-session-management/cli_managed_auth_state__implicit.py
new file mode 100644
index 00000000..19b73f60
--- /dev/null
+++ b/examples/auth-session-management/cli_managed_auth_state__implicit.py
@@ -0,0 +1,21 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # By default, the Planet SDK will be instantiated with the default auth
+ # session configured by `planet auth` and saved to disk. This default
+ # initialization will also take information from environment variables.
+ pl = planet.Planet()
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
new file mode 100644
index 00000000..f392111b
--- /dev/null
+++ b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
@@ -0,0 +1,28 @@
+import json
+import logging
+import planet
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+def example_main():
+ # Explicitly load the user's auth session from disk for a specific
+ # authentication session ("profile"). The user must have invoked
+ # `planet auth login` before this program is run or the program
+ # must have performed a login() elsewhere prior to this example.
+ # If this has not been done, the API calls will fail. This example
+ # will not initialize a new session.
+ plsdk_auth = planet.Auth.from_profile(profile_name="my-cli-managed-profile")
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/legacy_api_key_file.json b/examples/auth-session-management/legacy_api_key_file.json
new file mode 100644
index 00000000..548a94c9
--- /dev/null
+++ b/examples/auth-session-management/legacy_api_key_file.json
@@ -0,0 +1,3 @@
+{
+ "key": "__PLANET_API_KEY_MUST_BE_END_USER_SUPPLIED__"
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index 2c38a976..bbb89a6b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -49,6 +49,9 @@ extra_css:
plugins:
- search
+ - macros:
+ include_dir: 'examples'
+ on_error_fail: true
- mkdocstrings:
handlers:
python:
@@ -80,6 +83,7 @@ nav:
- cli/cli-reference.md
- "Python":
- python/sdk-guide.md
+ - python/sdk-client-auth.md
- python/async-sdk-guide.md
- python/sdk-reference.md
- "Resources":
diff --git a/pyproject.toml b/pyproject.toml
index 536768f9..0a44cabd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,6 +52,7 @@ docs = [
"mkdocs-material==8.2.11",
"mkdocstrings==0.18.1",
"mkdocs_autorefs==1.0.1",
+ "mkdocs-macros-plugin==1.3.7"
]
dev = [
"planet[test, docs, lint]",
From 43cda55edfae7d1873e136a1158dc3de70135cfb Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 19 Feb 2025 14:35:35 -0800
Subject: [PATCH 45/81] linting and formatting
---
docs/get-started/quick-start-guide.md | 5 ++--
...oauth_user_devicecode__external_browser.py | 25 ++++++++-----------
...ared__oauth_user_authcode__with_browser.py | 2 +-
...oauth_user_devicecode__external_browser.py | 2 +-
4 files changed, 16 insertions(+), 18 deletions(-)
diff --git a/docs/get-started/quick-start-guide.md b/docs/get-started/quick-start-guide.md
index 795af000..a6ae82c4 100644
--- a/docs/get-started/quick-start-guide.md
+++ b/docs/get-started/quick-start-guide.md
@@ -27,8 +27,9 @@ pip install planet
### Authentication
-Use the `planet auth` CLI command to establish a user login session that will be saved to the user's home directory.
-For other authentication options, see the [Client Authentication Guide](../python/sdk-client-auth.md).
+Use the `planet auth` CLI command to establish a user login session that will
+be saved to the user's home directory. For other authentication options, see
+the [Client Authentication Guide](../python/sdk-client-auth.md).
```bash
planet auth login
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
index c35d0ea4..1802fe5e 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
@@ -21,25 +21,22 @@ def initiate_user_session(plsdk_auth):
# shorter. If the URL may be presented in a clickable means (such as a
# link, button, or QR code) the verification_uri_complete may offer a
# better user experience.
- verification_uri_complete = login_initialization_info.get("verification_uri_complete")
+ verification_uri_complete = login_initialization_info.get(
+ "verification_uri_complete")
verification_uri = login_initialization_info.get("verification_uri")
user_code = login_initialization_info.get("user_code")
print("Please activate your client.")
if verification_uri_complete:
- print(
- f"Visit the activation site:\n"
- f"\n\t{verification_uri_complete}\n"
- f"\nand confirm the authorization code:\n"
- f"\n\t{user_code}\n"
- )
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri_complete}\n"
+ f"\nand confirm the authorization code:\n"
+ f"\n\t{user_code}\n")
else:
- print(
- f"Visit the activation site:\n"
- f"\n\t{verification_uri}\n"
- f"\nand enter the authorization code:\n"
- f"\n\t{user_code}\n"
- )
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri}\n"
+ f"\nand enter the authorization code:\n"
+ f"\n\t{user_code}\n")
# 3. Return control to the SDK. This will block until the user
# completes login.
@@ -71,7 +68,7 @@ def example_main():
# Use the SDK to call Planet APIs.
# Refreshing access tokens will be managed automatically by the SDK.
for item in pl.data.list_searches():
- print(json.dumps(item, indent=2, sort_keys=True))
+ print(json.dumps(item, indent=2, sort_keys=True))
if __name__ == '__main__':
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
index 9d05a7cb..182b6473 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
@@ -17,7 +17,7 @@ def example_main():
planet.PlanetOAuthScopes.OFFLINE_ACCESS,
],
callback_url="http://localhost:8080",
- profile_name="my-name-for-example-user-interactive-app-with-local-browser",
+ profile_name="my-name-for-example-user-session-with-local-browser",
save_state_to_disk=True,
)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
index c002bc7e..89aafee5 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
@@ -73,7 +73,7 @@ def example_main():
# Use the SDK to call Planet APIs.
# Refreshing access tokens will be managed automatically by the SDK.
for item in pl.data.list_searches():
- print(json.dumps(item, indent=2, sort_keys=True))
+ print(json.dumps(item, indent=2, sort_keys=True))
if __name__ == '__main__':
From bc37b3dcb4748cf9b93c0ce35991efea97f1fbbc Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 19 Feb 2025 14:39:01 -0800
Subject: [PATCH 46/81] formatting and linting
---
..._managed_auth_state__in_memory__api_key.py | 3 +--
...oauth_user_devicecode__external_browser.py | 25 ++++++++-----------
...naged_auth_state__specific_auth_profile.py | 3 ++-
3 files changed, 14 insertions(+), 17 deletions(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
index 9e05f187..7efb7659 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py
@@ -8,8 +8,7 @@
def example_main():
# Create an auth context with the specified API key
plsdk_auth = planet.Auth.from_key(
- key="__PLANET_API_KEY_MUST_BE_END_USER_SUPPLIED__"
- )
+ key="__PLANET_API_KEY_MUST_BE_END_USER_SUPPLIED__")
# Explicit login is not required for API key use. The above sufficient.
# plsdk_auth.user_login()
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
index 89aafee5..e1f17d5f 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
@@ -21,25 +21,22 @@ def initiate_user_session(plsdk_auth):
# shorter. If the URL may be presented in a clickable means (such as a
# link, button, or QR code) the verification_uri_complete may offer a
# better user experience.
- verification_uri_complete = login_initialization_info.get("verification_uri_complete")
+ verification_uri_complete = login_initialization_info.get(
+ "verification_uri_complete")
verification_uri = login_initialization_info.get("verification_uri")
user_code = login_initialization_info.get("user_code")
print("Please activate your client.")
if verification_uri_complete:
- print(
- f"Visit the activation site:\n"
- f"\n\t{verification_uri_complete}\n"
- f"\nand confirm the authorization code:\n"
- f"\n\t{user_code}\n"
- )
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri_complete}\n"
+ f"\nand confirm the authorization code:\n"
+ f"\n\t{user_code}\n")
else:
- print(
- f"Visit the activation site:\n"
- f"\n\t{verification_uri}\n"
- f"\nand enter the authorization code:\n"
- f"\n\t{user_code}\n"
- )
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri}\n"
+ f"\nand enter the authorization code:\n"
+ f"\n\t{user_code}\n")
# 3. Return control to the SDK. This will block until the user
# completes login.
@@ -57,7 +54,7 @@ def example_main():
# Request a refresh token so repeated browser logins are not required
planet.PlanetOAuthScopes.OFFLINE_ACCESS,
],
- profile_name="my-name-for-example-user-interactive-app-with-external-browser",
+ profile_name="my-name-example-user-auth-with-external-browser",
save_state_to_disk=True,
)
diff --git a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
index f392111b..b9337840 100644
--- a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
+++ b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
@@ -12,7 +12,8 @@ def example_main():
# must have performed a login() elsewhere prior to this example.
# If this has not been done, the API calls will fail. This example
# will not initialize a new session.
- plsdk_auth = planet.Auth.from_profile(profile_name="my-cli-managed-profile")
+ plsdk_auth = planet.Auth.from_profile(
+ profile_name="my-cli-managed-profile")
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
From 10e8e572c606eb1e23d135920caff90217a719cc Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 19 Feb 2025 15:41:25 -0800
Subject: [PATCH 47/81] Minor renamings
---
planet/auth_builtins.py | 8 ++++----
planet/cli/cli.py | 4 ++--
planet/http.py | 4 ++--
tests/unit/test_auth.py | 4 ++--
4 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 0d960f2c..512ac3e0 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -57,7 +57,7 @@ class _ProductionEnv:
_SDK_CLIENT_ID_PROD = "49lHVBYlXCdfIYqE1B9zeXt0iFHSXees"
-_OIDC_AUTH_CLIENT_CONFIG__SKEL = {
+_OIDC_AUTH_CLIENT_CONFIG__USER_SKEL = {
**_ProductionEnv.OAUTH_AUTHORITY_USER,
"scopes": [
PlanetOAuthScopes.PLANET,
@@ -75,14 +75,14 @@ class _ProductionEnv:
# Developers should register their own clients so that users may
# manage grants for different applications. Registering applications
# also allows for application specific URLs or auth flow selection.
- **_OIDC_AUTH_CLIENT_CONFIG__SKEL,
+ **_OIDC_AUTH_CLIENT_CONFIG__USER_SKEL,
"client_type": "oidc_device_code",
"client_id": _SDK_CLIENT_ID_PROD,
# FIXME: scopes currently from SKEL.
# It would be better to have per-client defaults and limits enforced by the auth server
}
-_OIDC_AUTH_CLIENT_CONFIG__M2M_PROD = {
+_OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL = {
**_ProductionEnv.OAUTH_AUTHORITY_M2M,
"client_type": "oidc_client_credentials_secret",
# FIXME: we do not have scope or behavior parity between our M2M and our user OAuth authorities.
@@ -126,7 +126,7 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
_builtin_profile_auth_client_configs: Dict[str, dict] = {
# BUILTIN_PROFILE_NAME_SDKCLI_CLIENT_ID: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_USER: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
- BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_PROD,
+ BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL,
BUILTIN_PROFILE_NAME_LEGACY: _LEGACY_AUTH_CLIENT_CONFIG__PROD,
BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
}
diff --git a/planet/cli/cli.py b/planet/cli/cli.py
index e43b2b88..b42e4262 100644
--- a/planet/cli/cli.py
+++ b/planet/cli/cli.py
@@ -1,5 +1,5 @@
# Copyright 2017 Planet Labs, Inc.
-# Copyright 2022 Planet Labs PBC.
+# Copyright 2022, 2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -78,7 +78,7 @@ def _configure_cli_auth_ctx(ctx,
auth_api_key_opt=auth_api_key)
# planet SDK Auth context type
- ctx.obj['PLSDK_AUTH'] = planet.Auth.from_plauth(
+ ctx.obj['PLSDK_AUTH'] = planet.Auth._from_plauth(
pl_authlib_context=ctx.obj['AUTH'])
diff --git a/planet/http.py b/planet/http.py
index d0392856..9a6647cd 100644
--- a/planet/http.py
+++ b/planet/http.py
@@ -1,5 +1,5 @@
# Copyright 2020 Planet Labs, Inc.
-# Copyright 2022 Planet Labs PBC.
+# Copyright 2022, 2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
@@ -238,7 +238,7 @@ def __init__(self, auth: Optional[AuthType] = None):
auth: Planet server authentication.
"""
if auth is None:
- auth = Auth.from_user_defaults()
+ auth = Auth.from_user_default_session()
LOGGER.info(f'Session read timeout set to {READ_TIMEOUT}.')
timeout = httpx.Timeout(10.0, read=READ_TIMEOUT)
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 2cc7bf73..505a5767 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -1,5 +1,5 @@
# Copyright 2020 Planet Labs, Inc.
-# Copyright 2022 Planet Labs PBC.
+# Copyright 2022, 2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -145,7 +145,7 @@ def test_Auth_from_user_defaults():
# This tests that it doesn't explode with an exception.
# CI/CD currently is run by configuring auth via PL_API_KEY env var.
# What this will actually do in an user env depends on a lot of variables.
- _ = auth.Auth.from_user_defaults()
+ _ = auth.Auth.from_user_default_session()
def test_Auth_from_oauth_m2m():
From b863948433c029b39602b3de9ea500df1a6d3526 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:07:01 -0800
Subject: [PATCH 48/81] improve example
---
.../cli_managed_auth_state__specific_auth_profile.py | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
index b9337840..4f519ed6 100644
--- a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
+++ b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
@@ -1,6 +1,7 @@
import json
import logging
import planet
+import sys
logging.basicConfig(level=logging.CRITICAL)
@@ -11,10 +12,16 @@ def example_main():
# `planet auth login` before this program is run or the program
# must have performed a login() elsewhere prior to this example.
# If this has not been done, the API calls will fail. This example
- # will not initialize a new session.
+ # does not initialize a new session.
plsdk_auth = planet.Auth.from_profile(
profile_name="my-cli-managed-profile")
+ # If required, how to login depends on what is configured in the specific
+ # profile. See other examples for login calls.
+ if not plsdk_auth.is_initialized():
+ print(f"Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n")
+ sys.exit(99)
+
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
pl = planet.Planet(sess)
From 28c5e3aa559c574fc7024aad450a37f0c58bf407 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:09:25 -0800
Subject: [PATCH 49/81] improve example
---
.../cli_managed_auth_state__explicit.py | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/examples/auth-session-management/cli_managed_auth_state__explicit.py b/examples/auth-session-management/cli_managed_auth_state__explicit.py
index aa40ffbb..58ad75b5 100644
--- a/examples/auth-session-management/cli_managed_auth_state__explicit.py
+++ b/examples/auth-session-management/cli_managed_auth_state__explicit.py
@@ -1,6 +1,7 @@
import json
import logging
import planet
+import sys
logging.basicConfig(level=logging.CRITICAL)
@@ -11,6 +12,12 @@ def example_main():
# will fail. This will not initialize a new session.
plsdk_auth = planet.Auth.from_user_default_session()
+ # If required, how to login depends on what is configured in the specific
+ # profile. See other examples for login calls.
+ if not plsdk_auth.is_initialized():
+ print(f"Login required. Execute the following command:\n\n\tplanet auth login\n")
+ sys.exit(99)
+
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
pl = planet.Planet(sess)
From 93a98d92f2400e382b2ac7615f12005c8a72b905 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:18:37 -0800
Subject: [PATCH 50/81] update example
---
...k_cli_shared__oauth_user_devicecode__external_browser.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
index e1f17d5f..1f9986c3 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
@@ -55,11 +55,11 @@ def example_main():
planet.PlanetOAuthScopes.OFFLINE_ACCESS,
],
profile_name="my-name-example-user-auth-with-external-browser",
- save_state_to_disk=True,
+ save_state_to_storage=True,
)
- # An application with no persistent storage must initialize a login every
- # time. This is not smooth user experience.
+ # In contrast to an in-memory only application that must initialize a login every
+ # time, an app with persistent storage can skip this when it is not needed.
if not plsdk_auth.is_initialized():
initiate_user_session(plsdk_auth)
From f5ea87be360dbbe887170e720d800154cbdeb8e0 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:21:02 -0800
Subject: [PATCH 51/81] update example
---
...__on_disk_cli_shared__oauth_user_authcode__with_browser.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
index 182b6473..5be30978 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py
@@ -18,9 +18,11 @@ def example_main():
],
callback_url="http://localhost:8080",
profile_name="my-name-for-example-user-session-with-local-browser",
- save_state_to_disk=True,
+ save_state_to_storage=True,
)
+ # In contrast to an in-memory only application that must initialize a login every
+ # time, an app with persistent storage can skip this when it is not needed.
if not plsdk_auth.is_initialized():
plsdk_auth.user_login(allow_open_browser=True)
From 5b5a41c70c1c8611e1edf0885d830fb0f9502309 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:23:26 -0800
Subject: [PATCH 52/81] update example
---
.../app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
index 89fd221a..61d63198 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py
@@ -12,10 +12,10 @@ def example_main():
client_id="__MUST_BE_END_USER_SUPPLIED__",
client_secret="__MUST_BE_END_USER_SUPPLIED__",
profile_name="my-name-for-example-m2m-auth-profile",
- save_state_to_disk=True,
+ save_state_to_storage=True,
)
- # Explicit login is not required for M2M client use. The above sufficient.
+ # Explicit login is not required for M2M client use. The above is sufficient.
# plsdk_auth.user_login()
# Create a Planet SDK object that uses the loaded auth session.
From 4056c5e144d562c545401f7ce17edaf0014e1cef Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:24:44 -0800
Subject: [PATCH 53/81] update example
---
.../app_managed_auth_state__on_disk_cli_shared__api_key.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
index ccbb1b93..033a9e53 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py
@@ -1 +1,2 @@
-# No example of this use case provided at this time
+# No example of this use case provided at this time.
+# The use of M2M OAuth sessions is encouraged over the use of API keys.
From 31606a21d42458152c4df1489e528d0834f5d38e Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:56:30 -0800
Subject: [PATCH 54/81] example updates
---
.../app_managed_auth_state__in_memory__oauth_m2m.py | 4 ++--
...uth_state__in_memory__oauth_user_authcode__with_browser.py | 2 +-
...ate__in_memory__oauth_user_devicecode__external_browser.py | 2 +-
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
index c28d1c9b..517e186a 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py
@@ -11,10 +11,10 @@ def example_main():
plsdk_auth = planet.Auth.from_oauth_m2m(
client_id="__MUST_BE_END_USER_SUPPLIED__",
client_secret="__MUST_BE_END_USER_SUPPLIED__",
- save_state_to_disk=False,
+ save_state_to_storage=False,
)
- # Explicit login is not required for M2M client use. The above sufficient.
+ # Explicit login is not required for M2M client use. The above is sufficient.
# plsdk_auth.user_login()
# Create a Planet SDK object that uses the loaded auth session/
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
index 2bcc44c8..312d1136 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py
@@ -17,7 +17,7 @@ def example_main():
planet.PlanetOAuthScopes.OFFLINE_ACCESS,
],
callback_url="http://localhost:8080",
- save_state_to_disk=False,
+ save_state_to_storage=False,
)
# An application with no persistent storage must
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
index 1802fe5e..d2bd4d99 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
@@ -54,7 +54,7 @@ def example_main():
# Request a refresh token so repeated browser logins are not required
planet.PlanetOAuthScopes.OFFLINE_ACCESS,
],
- save_state_to_disk=False,
+ save_state_to_storage=False,
)
# An application with no persistent storage must initialize a login every
From 99f1d0becb391f62c6f18c2d8893da20c806e034 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 15:59:43 -0800
Subject: [PATCH 55/81] update example
---
.../app_managed_auth_state__app_custom_storage__api_key.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
index ccbb1b93..033a9e53 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py
@@ -1 +1,2 @@
-# No example of this use case provided at this time
+# No example of this use case provided at this time.
+# The use of M2M OAuth sessions is encouraged over the use of API keys.
From 9a6e5008f12cd6b02f56c56e45124bba66c4924d Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 17:12:15 -0800
Subject: [PATCH 56/81] examples using custom storage
---
...th_state__app_custom_storage__oauth_m2m.py | 89 ++++++++++++
...rage__oauth_user_authcode__with_browser.py | 97 +++++++++++++
...oauth_user_devicecode__external_browser.py | 135 ++++++++++++++++++
3 files changed, 321 insertions(+)
create mode 100644 examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
create mode 100644 examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
new file mode 100644
index 00000000..2415dcad
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
@@ -0,0 +1,89 @@
+import json
+import logging
+import os
+import pathlib
+import stat
+
+import planet
+
+from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
+
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+class DemoStorageProvider(ObjectStorageProvider):
+ """
+ Simple demo custom storage provider that uses
+ ~/.planet-demo as a storage home for saving object.
+
+ As a practical matter, ObjectStorageProvider_KeyType is defined
+ to be pathlib.Path, and we leverage that in this example.
+ But, storage providers are not required to use the local file
+ system to store objects.
+ """
+
+ def __init__(self):
+ self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+
+ def _demo_obj_filepath(self, obj_key):
+ if obj_key.is_absolute():
+ obj_path = self._demo_storage_root / obj_key.relative_to("/")
+ else:
+ obj_path = self._demo_storage_root / obj_key
+ return obj_path
+
+ @staticmethod
+ def _load_file(file_path: pathlib.Path) -> dict:
+ logging.debug(msg="Loading JSON data from file {}".format(file_path))
+ with open(file_path, mode="r", encoding="UTF-8") as file_r:
+ return json.load(file_r)
+
+ @staticmethod
+ def _save_file(file_path: pathlib.Path, data: dict):
+ file_path.parent.mkdir(parents=True, exist_ok=True)
+ logging.debug(msg="Writing JSON data to file {}".format(file_path))
+ with open(file_path, mode="w", encoding="UTF-8") as file_w:
+ os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
+ _no_none_data = {key: value for key, value in data.items() if value is not None}
+ file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
+
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_m2m(
+ client_id="__MUST_BE_END_USER_SUPPLIED__",
+ client_secret="__MUST_BE_END_USER_SUPPLIED__",
+ profile_name="my-example-name-m2m-with-custom-storage",
+ save_state_to_storage=True,
+ storage_provider=DemoStorageProvider(),
+ )
+
+ # Explicit login is not required for M2M client use. The above sufficient.
+ # plsdk_auth.user_login()
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
new file mode 100644
index 00000000..990ba796
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
@@ -0,0 +1,97 @@
+import json
+import logging
+import os
+import pathlib
+import stat
+
+import planet
+
+from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
+
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+class DemoStorageProvider(ObjectStorageProvider):
+ """
+ Simple demo custom storage provider that uses
+ ~/.planet-demo as a storage home for saving object.
+
+ As a practical matter, ObjectStorageProvider_KeyType is defined
+ to be pathlib.Path, and we leverage that in this example.
+ But, storage providers are not required to use the local file
+ system to store objects.
+ """
+
+ def __init__(self):
+ self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+
+ def _demo_obj_filepath(self, obj_key):
+ if obj_key.is_absolute():
+ obj_path = self._demo_storage_root / obj_key.relative_to("/")
+ else:
+ obj_path = self._demo_storage_root / obj_key
+ return obj_path
+
+ @staticmethod
+ def _load_file(file_path: pathlib.Path) -> dict:
+ logging.debug(msg="Loading JSON data from file {}".format(file_path))
+ with open(file_path, mode="r", encoding="UTF-8") as file_r:
+ return json.load(file_r)
+
+ @staticmethod
+ def _save_file(file_path: pathlib.Path, data: dict):
+ file_path.parent.mkdir(parents=True, exist_ok=True)
+ logging.debug(msg="Writing JSON data to file {}".format(file_path))
+ with open(file_path, mode="w", encoding="UTF-8") as file_w:
+ os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
+ _no_none_data = {key: value for key, value in data.items() if value is not None}
+ file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
+
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_auth_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ callback_url="http://localhost:8080",
+ profile_name="my-example-name-auth-code-with-custom-storage",
+ save_state_to_storage=True,
+ storage_provider=DemoStorageProvider(),
+ )
+
+ # In contrast to an in-memory only application that must initialize a login every
+ # time, an app with persistent storage can skip this when it is not needed.
+ if not plsdk_auth.is_initialized():
+ plsdk_auth.user_login(allow_open_browser=True)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
new file mode 100644
index 00000000..e43b03f6
--- /dev/null
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
@@ -0,0 +1,135 @@
+import json
+import logging
+import os
+import pathlib
+import stat
+
+import planet
+
+from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
+
+
+logging.basicConfig(level=logging.CRITICAL)
+
+
+class DemoStorageProvider(ObjectStorageProvider):
+ """
+ Simple demo custom storage provider that uses
+ ~/.planet-demo as a storage home for saving object.
+
+ As a practical matter, ObjectStorageProvider_KeyType is defined
+ to be pathlib.Path, and we leverage that in this example.
+ But, storage providers are not required to use the local file
+ system to store objects.
+ """
+
+ def __init__(self):
+ self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+
+ def _demo_obj_filepath(self, obj_key):
+ if obj_key.is_absolute():
+ obj_path = self._demo_storage_root / obj_key.relative_to("/")
+ else:
+ obj_path = self._demo_storage_root / obj_key
+ return obj_path
+
+ @staticmethod
+ def _load_file(file_path: pathlib.Path) -> dict:
+ logging.debug(msg="Loading JSON data from file {}".format(file_path))
+ with open(file_path, mode="r", encoding="UTF-8") as file_r:
+ return json.load(file_r)
+
+ @staticmethod
+ def _save_file(file_path: pathlib.Path, data: dict):
+ file_path.parent.mkdir(parents=True, exist_ok=True)
+ logging.debug(msg="Writing JSON data to file {}".format(file_path))
+ with open(file_path, mode="w", encoding="UTF-8") as file_w:
+ os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
+ _no_none_data = {key: value for key, value in data.items() if value is not None}
+ file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
+
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
+
+
+def initiate_user_session(plsdk_auth):
+ # Example of initiating a user session where the app is 100%
+ # responsible for the user experience.
+
+ # 1. Initiate the login
+ login_initialization_info = plsdk_auth.device_user_login_initiate()
+
+ # 2. Display necessary instructions to the user.
+ #
+ # "verification_uri" and "user_code" are required under RFC 8628.
+ # "verification_uri_complete" is optional under the RFC.
+ #
+ # If the user is expected to type in the URL, verification_uri will be
+ # shorter. If the URL may be presented in a clickable means (such as a
+ # link, button, or QR code) the verification_uri_complete may offer a
+ # better user experience.
+ verification_uri_complete = login_initialization_info.get(
+ "verification_uri_complete")
+ verification_uri = login_initialization_info.get("verification_uri")
+ user_code = login_initialization_info.get("user_code")
+
+ print("Please activate your client.")
+ if verification_uri_complete:
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri_complete}\n"
+ f"\nand confirm the authorization code:\n"
+ f"\n\t{user_code}\n")
+ else:
+ print(f"Visit the activation site:\n"
+ f"\n\t{verification_uri}\n"
+ f"\nand enter the authorization code:\n"
+ f"\n\t{user_code}\n")
+
+ # 3. Return control to the SDK. This will block until the user
+ # completes login.
+ plsdk_auth.device_user_login_complete(login_initialization_info)
+
+
+def example_main():
+ # Create an auth context with a client ID that
+ # is unique to this application.
+ plsdk_auth = planet.Auth.from_oauth_user_device_code(
+ client_id="__MUST_BE_APP_DEVELOPER_SUPPLIED__",
+ requested_scopes=[
+ # Request access to Planet APIs
+ planet.PlanetOAuthScopes.PLANET,
+ # Request a refresh token so repeated browser logins are not required
+ planet.PlanetOAuthScopes.OFFLINE_ACCESS,
+ ],
+ profile_name="my-example-name-device-code-with-custom-storage",
+ save_state_to_storage=True,
+ storage_provider=DemoStorageProvider(),
+ )
+
+ # In contrast to an in-memory only application that must initialize a login every
+ # time, an app with persistent storage can skip this when it is not needed.
+ if not plsdk_auth.is_initialized():
+ initiate_user_session(plsdk_auth)
+
+ # Create a Planet SDK object that uses the loaded auth session.
+ sess = planet.Session(plsdk_auth)
+ pl = planet.Planet(sess)
+
+ # Use the SDK to call Planet APIs.
+ # Refreshing access tokens will be managed automatically by the SDK.
+ for item in pl.data.list_searches():
+ print(json.dumps(item, indent=2, sort_keys=True))
+
+
+if __name__ == '__main__':
+ example_main()
From 78e02280508093982dc12ac8601099eb70ccf45e Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 17:42:57 -0800
Subject: [PATCH 57/81] update docs and examples
---
docs/python/sdk-client-auth.md | 35 ++++++++++---------
...th_state__app_custom_storage__oauth_m2m.py | 24 ++++++-------
...rage__oauth_user_authcode__with_browser.py | 24 ++++++-------
...oauth_user_devicecode__external_browser.py | 29 ++++++++-------
...oauth_user_devicecode__external_browser.py | 4 +--
...oauth_user_devicecode__external_browser.py | 4 +--
.../cli_managed_auth_state__explicit.py | 2 --
7 files changed, 61 insertions(+), 61 deletions(-)
diff --git a/docs/python/sdk-client-auth.md b/docs/python/sdk-client-auth.md
index b52b1a82..1bd5f3f9 100644
--- a/docs/python/sdk-client-auth.md
+++ b/docs/python/sdk-client-auth.md
@@ -136,12 +136,13 @@ in-memory mode, and will be forced create a new login session every time the
application is run. In some cases, this may result in throttling by the
authorization service.
-The SDK provides a way to stave session state in the user's home directory in
-a way that is compatible with the CLI. The SDK also provides a way for the
-application to provide its own secure storage.
-
-!!! TODO
- We have yet to document how to use application provided storage.
+By default, the SDK provides the option to save session state in the user's
+home directory in a way that is compatible with the CLI. The SDK also
+provides a way for the application to provide its own secure storage.
+Applications needing to use their own storage will do so by providing
+the `Auth` layer in the SDK with a custom implementation of the
+`planet_auth.ObjectStorageProvider` abstract base class. See examples
+below for more details.
### Using `planet auth` CLI Managed Auth Session
For simple programs and scripts, it is easiest for the program to defer
@@ -158,7 +159,8 @@ using the SDK. Changes made by one will impact the behavior of the other.
* The program must have read and write access to the user's home directory.
* This method requires that the end-user has access to and understands
- the `planet` CLI command needed to manage session authentication.
+ the [`planet`](../../cli/cli-reference) CLI command needed to manage session
+ authentication.
* This approach should not be used on public terminals or in cases where the
user's home directory cannot be kept confidential.
@@ -193,13 +195,14 @@ on SDK default behavior, but it may also be done explicitly.
### Manually Creating a Session Using Library Functions
If an application cannot or should not use a login session initiated by the
-`planet auth` CLI command, it will be responsible for managing the process on
-its own, persisting session state as needed.
+[`planet auth`](../../cli/cli-reference/#auth) CLI command, it will be
+responsible for managing the process on its own, persisting session state as
+needed.
The process differs slightly for applications accessing Planet services on behalf
of a human user verses accessing Planet services using a service account. Depending
on the use case, applications may need to support one or the other or both (just
-as the `planet` CLI command supports both methods).
+as the [`planet`](../../cli/cli-reference) CLI command supports both methods).
#### OAuth2 Session for Users
User session initialization inherently involves using a web browser to
@@ -215,9 +218,9 @@ authentication and authorization.
In environments where a local browser is available, the Planet SDK can manage
the process of launching the browser locally, transferring control to the Planet
authorization services for session initialization, and accepting a network
-callback from the browser to regain control once the authorization process is
-complete. At a network protocol level, this is establishing the user login
-session using the OAuth2 authorization code flow.
+callback from the local browser to regain control once the authorization
+process is complete. At a network protocol level, this is establishing the user
+login session using the OAuth2 authorization code flow.
To use this method using the SDK, the following requirements must be met:
@@ -285,7 +288,7 @@ running data processing job). If application lifespan is short and frequent,
than the application should still take steps to persist the session state (for
example: a command line utility run from a shell with a short lifespan).
-Like session state, service account initialization parameters are
+Like the session state itself, service account initialization parameters are
sensitive, and it is the responsibility of the application to store them
securely.
@@ -293,8 +296,8 @@ At a network protocol level, OAuth2 service account sessions are implemented
using the OAuth2 authorization code flow. This carries with it some additional
security considerations, discussed in
[RFC 6819 §4.4.4](https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.4).
-Because of these consideration, service accounts should ideally only be used
-for workflows that are independent of a controlling user.
+Because of these consideration, service accounts should only be used for
+workflows that are independent of a controlling user.
##### Examples - Client Credentials Flow
```python linenums="1" title="Access APIs using a service account with in memory only state persistance"
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
index 2415dcad..7e20c05f 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
@@ -26,6 +26,18 @@ class DemoStorageProvider(ObjectStorageProvider):
def __init__(self):
self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
def _demo_obj_filepath(self, obj_key):
if obj_key.is_absolute():
obj_path = self._demo_storage_root / obj_key.relative_to("/")
@@ -48,18 +60,6 @@ def _save_file(file_path: pathlib.Path, data: dict):
_no_none_data = {key: value for key, value in data.items() if value is not None}
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
- def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return self._load_file(file_path=demo_obj_filepath)
-
- def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
- demo_obj_filepath = self._demo_obj_filepath(key)
- self._save_file(file_path=demo_obj_filepath, data=data)
-
- def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return demo_obj_filepath.exists()
-
def example_main():
# Create an auth context with a client ID that
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
index 990ba796..83e18596 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
@@ -26,6 +26,18 @@ class DemoStorageProvider(ObjectStorageProvider):
def __init__(self):
self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
def _demo_obj_filepath(self, obj_key):
if obj_key.is_absolute():
obj_path = self._demo_storage_root / obj_key.relative_to("/")
@@ -48,18 +60,6 @@ def _save_file(file_path: pathlib.Path, data: dict):
_no_none_data = {key: value for key, value in data.items() if value is not None}
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
- def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return self._load_file(file_path=demo_obj_filepath)
-
- def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
- demo_obj_filepath = self._demo_obj_filepath(key)
- self._save_file(file_path=demo_obj_filepath, data=data)
-
- def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return demo_obj_filepath.exists()
-
def example_main():
# Create an auth context with a client ID that
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
index e43b03f6..e1b9bd37 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
@@ -26,6 +26,18 @@ class DemoStorageProvider(ObjectStorageProvider):
def __init__(self):
self._demo_storage_root = pathlib.Path.home() / ".planet-demo"
+ def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return self._load_file(file_path=demo_obj_filepath)
+
+ def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ self._save_file(file_path=demo_obj_filepath, data=data)
+
+ def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
+ demo_obj_filepath = self._demo_obj_filepath(key)
+ return demo_obj_filepath.exists()
+
def _demo_obj_filepath(self, obj_key):
if obj_key.is_absolute():
obj_path = self._demo_storage_root / obj_key.relative_to("/")
@@ -48,21 +60,8 @@ def _save_file(file_path: pathlib.Path, data: dict):
_no_none_data = {key: value for key, value in data.items() if value is not None}
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
- def load_obj(self, key: ObjectStorageProvider_KeyType) -> dict:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return self._load_file(file_path=demo_obj_filepath)
-
- def save_obj(self, key: ObjectStorageProvider_KeyType, data: dict) -> None:
- demo_obj_filepath = self._demo_obj_filepath(key)
- self._save_file(file_path=demo_obj_filepath, data=data)
-
- def obj_exists(self, key: ObjectStorageProvider_KeyType) -> bool:
- demo_obj_filepath = self._demo_obj_filepath(key)
- return demo_obj_filepath.exists()
-
-
-def initiate_user_session(plsdk_auth):
+def initialize_user_session(plsdk_auth):
# Example of initiating a user session where the app is 100%
# responsible for the user experience.
@@ -119,7 +118,7 @@ def example_main():
# In contrast to an in-memory only application that must initialize a login every
# time, an app with persistent storage can skip this when it is not needed.
if not plsdk_auth.is_initialized():
- initiate_user_session(plsdk_auth)
+ initialize_user_session(plsdk_auth)
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
index d2bd4d99..0f332cfa 100644
--- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py
@@ -5,7 +5,7 @@
logging.basicConfig(level=logging.CRITICAL)
-def initiate_user_session(plsdk_auth):
+def initialize_user_session(plsdk_auth):
# Example of initiating a user session where the app is 100%
# responsible for the user experience.
@@ -59,7 +59,7 @@ def example_main():
# An application with no persistent storage must initialize a login every
# time. This is not smooth user experience.
- initiate_user_session(plsdk_auth)
+ initialize_user_session(plsdk_auth)
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
index 1f9986c3..d0ca115a 100644
--- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py
@@ -5,7 +5,7 @@
logging.basicConfig(level=logging.CRITICAL)
-def initiate_user_session(plsdk_auth):
+def initialize_user_session(plsdk_auth):
# Example of initiating a user session where the app is 100%
# responsible for the user experience.
@@ -61,7 +61,7 @@ def example_main():
# In contrast to an in-memory only application that must initialize a login every
# time, an app with persistent storage can skip this when it is not needed.
if not plsdk_auth.is_initialized():
- initiate_user_session(plsdk_auth)
+ initialize_user_session(plsdk_auth)
# Create a Planet SDK object that uses the loaded auth session.
sess = planet.Session(plsdk_auth)
diff --git a/examples/auth-session-management/cli_managed_auth_state__explicit.py b/examples/auth-session-management/cli_managed_auth_state__explicit.py
index 58ad75b5..c512560a 100644
--- a/examples/auth-session-management/cli_managed_auth_state__explicit.py
+++ b/examples/auth-session-management/cli_managed_auth_state__explicit.py
@@ -12,8 +12,6 @@ def example_main():
# will fail. This will not initialize a new session.
plsdk_auth = planet.Auth.from_user_default_session()
- # If required, how to login depends on what is configured in the specific
- # profile. See other examples for login calls.
if not plsdk_auth.is_initialized():
print(f"Login required. Execute the following command:\n\n\tplanet auth login\n")
sys.exit(99)
From c3b43c1fb7e7dff858041ed592fe5dfa427641da Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 17:45:50 -0800
Subject: [PATCH 58/81] update auth.py
---
planet/auth.py | 366 ++++++++++++++++++++++++++++++++++++-------------
1 file changed, 267 insertions(+), 99 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 76956c7f..acc4ce75 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -1,5 +1,5 @@
# Copyright 2020 Planet Labs, Inc.
-# Copyright 2022, 2024 Planet Labs PBC.
+# Copyright 2022, 2024, 2025 Planet Labs PBC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -25,146 +25,293 @@
import planet_auth
import planet_auth_utils
+from planet_auth import ObjectStorageProvider
+
from .constants import SECRET_FILE_PATH
-from .auth_builtins import _ProductionEnv, _BuiltinConfigurationProvider, _OIDC_AUTH_CLIENT_CONFIG__SKEL
+from .auth_builtins import _ProductionEnv, _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL, _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL
from .exceptions import PlanetError
-AuthType = httpx.Auth
+
+class AuthType(abc.ABC, httpx.Auth):
+ @abc.abstractmethod
+ def user_login(
+ self,
+ allow_open_browser: typing.Optional[bool] = False,
+ allow_tty_prompt: typing.Optional[bool] = False,
+ ):
+ """
+ Perform an interactive login. User interaction will be via the TTY
+ and/or a local web browser, with the details dependent on the
+ client auth configuration.
+
+ :param allow_open_browser:
+ :param allow_tty_prompt:
+ """
+
+ @abc.abstractmethod
+ def device_user_login_initiate(self) -> dict:
+ """
+ Initiate a user login that uses the OAuth2 Device Code Flow for applications
+ that cannot operate a browser locally. The returned dictionary should be used
+ to prompt the user to complete the process, and will conform to RFC 8628.
+ """
+
+ @abc.abstractmethod
+ def device_user_login_complete(self, login_initialization_info: dict):
+ """
+ Complete a user login that uses the OAuth2 Device Code Flow for applications
+ that was initiated by a call to `device_user_login_initiate()`. The structure
+ that was returned from `device_user_login_initiate()` should be passed
+ to this function unaltered after it has been used to prompt the user.
+ """
+
+ @abc.abstractmethod
+ def is_initialized(self) -> bool:
+ """
+ Check whether the user session has been initialized. For OAuth2
+ user based sessions, this means that a login has been performed
+ or saved login session data has been located. For M2M and API Key
+ sessions, this should be true if keys or secrets have been
+ properly configured.
+ """
-# planet_auth and planet_auth_utils code more or less entirely
-# supersedes this class. But, keeping this here for
-# now for interface stability and to bridge with the rest of the SDK.
class Auth(metaclass=abc.ABCMeta):
- """Handle authentication information for use with Planet APIs."""
+ """
+ Handle authentication information for use with Planet APIs.
+ Static constructor methods should be used to create an auth context
+ that can be used by Planet API client modules to authenticate
+ requests made to the Planet service.
+ """
+
+ @staticmethod
+ def _normalize_profile_name(profile_name):
+ if not profile_name:
+ raise ValueError("Profile name must be set")
+ if profile_name.find(os.sep) != -1:
+ raise ValueError(f"Profile names cannot contain '{os.sep}'")
+ return profile_name.lower()
@staticmethod
- def from_user_defaults() -> AuthType:
+ def from_user_default_session() -> AuthType:
"""
- Create authentication from user defaults. Defaults take into
- account environment variables (highest priority), user configuration
- saved to `~/.planet.json` (next priority), and built-in defaults
- (lowest priority).
+ Create authentication from user defaults.
+
+ This method should be used when an application wants to defer
+ auth profile management to the user and the `planet auth` CLI
+ command entirely.
Users may use the `planet auth login` command to initialize
- configuration files.
+ and manage sessions.
+
+ Defaults take into account environment variables (highest priority),
+ user configuration saved to `~/.planet.json` and `~/.planet/
+ (next priority), and built-in defaults (lowest priority).
+
+ This method does not support the use a custom storage provider.
+ The session must be initialized entirely in memory (e.g. through
+ environment variables), or from on disk CLI managed settings.
Environment Variables:
- PL_AUTH_PROFILE: Specify a custom planet_auth library auth
- client profile (Advanced use cases)
PL_AUTH_CLIENT_ID: Specify an OAuth2 M2M client ID
PL_AUTH_CLIENT_SECRET: Specify an OAuth2 M2M client secret
PL_AUTH_API_KEY: Specify a legacy Planet API key
+ PL_AUTH_PROFILE: Specify a custom planet_auth library auth
+ client profile (Advanced use cases)
"""
return _PLAuthLibAuth(plauth=planet_auth_utils.PlanetAuthFactory.
initialize_auth_client_context())
- # TODO: It feels like we should accept an auth profile so a user
- # can manage multiple identities. But that's also far broader than
- # "OAuth user interactive" session, since the auth implementation
- # configured by a profile could be anything.
- # It also feels like we need a method that accepts client IDs
- # managed by the developer so they can initialize the library
- # to use the specified client ID of the larger application built
- # on top of the library (e.g. QGIS)
@staticmethod
- def from_oauth_user_session():
+ def from_profile(profile_name: str) -> AuthType:
"""
Create authentication for a user whose initialized login information
has been saved to `~/.planet.json` and `~/.planet/`.
+
A user should perform a login to initialize this session out-of-band
using the command `planet auth login`.
- To initialize this session programmatically, you must complete an
- OAuth2 user login flow. This involves initiating a request to the
- authorization server, the user completing authentication using a
- web browser out of process, and finalizing the authentication and
- authorization in process and saving the session information that will
- be used to make API requests.
+ To initialize this session programmatically without the CLI,
+ you must complete an OAuth2 user login flow with one of the login
+ methods.
- Most properly, this process uses IDs that are specific to the
- application. The exact process that should be used to complete
- login is specific to the particulars of the application.
+ This method does not support the use a custom storage provider.
"""
pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_profile_opt=_BuiltinConfigurationProvider.
- BUILTIN_PROFILE_NAME_PLANET_USER)
+ auth_profile_opt=profile_name)
return _PLAuthLibAuth(plauth=pl_authlib_context)
- # TODO:
- # I think we need something like this for developers of user interactive
- # applications (e.g. QGIS), but as of January 2025 we do not have a way
- # for developers to register user interactive client on the platform,
- # or a way for users of such applications to revoke such authorizations.
- # Even without this, we may white glove client IDs for partners before
- # it is a generally available feature.
- # TODO:
- # This works to initialize the library auth client, but DOES NOT
- # establish a user session. If on disk storage can be used, that
- # can be done out of band via the CLI. If in memory operations
- # are desired, that will not work.
- # In either case, what needs to happen is that
- # planet.auth._PLAuthLibAuth._plauth.login() needs to be invoked.
- # If disk storage is used, that only needs to happen once and the results
- # will be picked up from disk by this Auth init method. If not,
- # that needs to happen for every process invocation, since tokens
- # will not be saved, and refresh cannot be performed.
- # User experience is greatly served by being able to save to disk.
+ # TODO: add support for confidential clients
@staticmethod
- def beta_from_oauth_client_config(
- client_id: str,
- requested_scopes: List[str],
- save_token_file: bool = True) -> AuthType:
+ def from_oauth_user_auth_code(
+ client_id: str,
+ callback_url: str,
+ requested_scopes: typing.Optional[List[str]] = None,
+ save_state_to_storage: bool = True,
+ profile_name: typing.Optional[str] = None,
+ storage_provider: typing.Optional[ObjectStorageProvider] = None,
+ ) -> AuthType:
"""
- Beta. Feature not yet supported for public use.
+ Create authentication for the specified registered client
+ application.
+
+ Developers of applications must register clients with
+ Planet, and will be issued a Client ID as part of that process.
+ Developers should register a client for each distinct application so
+ that end-users may discretely manage applications permitted to access
+ Planet APIs on their behalf.
+
+ This method does not perform a user login to initialize a session.
+ If not initialized out of band using the CLI, sessions must be initialized
+ with the user_login() before API calls may be made.
+
+ Parameters:
+ client_id: Client ID
+ requested_scopes: List of requested OAuth2 scopes
+ callback_url: Client callback URL
+ profile_name: User friendly name to use when saving the configuration
+ to storage per the `save_state_to_storage` flag. The profile name
+ will be normalized to a file system compatible identifier,
+ regardless of storage provider.
+ save_state_to_storage: Boolean controlling whether login sessions
+ should be saved to storage. When the default storage provider is
+ used, they will be stored in a way that is compatible with
+ the `planet` CLI.
+ storage_provider: A custom storage provider to save session state
+ for the application.
"""
- plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__SKEL
+ plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL
+ plauth_config_dict["client_type"] = "oidc_auth_code"
plauth_config_dict["client_id"] = client_id
- plauth_config_dict["scopes"] = requested_scopes
- # TBD: How flexible will we be in terms of supported flows OAuth flows?
+ if requested_scopes:
+ plauth_config_dict["scopes"] = requested_scopes
+ plauth_config_dict["redirect_uri"] = callback_url
+
+ if not profile_name:
+ profile_name = client_id
+ normalized_profile_name = Auth._normalize_profile_name(profile_name)
+
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_from_custom_config(
+ client_config=plauth_config_dict,
+ initial_token_data={},
+ save_token_file=save_state_to_storage,
+ profile_name=normalized_profile_name,
+ save_profile_config=save_state_to_storage,
+ storage_provider=storage_provider,
+ )
+
+ return Auth._from_plauth(pl_authlib_context)
+
+ # TODO: add support for confidential clients
+ @staticmethod
+ def from_oauth_user_device_code(
+ client_id: str,
+ requested_scopes: typing.Optional[List[str]] = None,
+ save_state_to_storage: bool = True,
+ profile_name: typing.Optional[str] = None,
+ storage_provider: typing.Optional[ObjectStorageProvider] = None
+ ) -> AuthType:
+ """
+ Create authentication for the specified registered client
+ application.
+
+ Developers of applications must register clients with
+ Planet, and will be issued a Client ID as part of that process.
+ Developers should register a client for each distinct application so
+ that end-users may discretely manage applications permitted to access
+ Planet APIs on their behalf.
+
+ This method does not perform a user login to initialize a session.
+
+ This method does not perform a user login to initialize a session.
+ If not initialized out of band using the CLI, sessions must be initialized
+ with the device login methods before API calls may be made.
+
+ Parameters:
+ client_id: Client ID
+ requested_scopes: List of requested OAuth2 scopes
+ profile_name: User friendly name to use when saving the configuration
+ to storage per the `save_state_to_storage` flag. The profile name
+ will be normalized to file system compatible identifier, regardless
+ of the storage provider being used.
+ save_state_to_storage: Boolean controlling whether login sessions
+ should be saved to storage. When the default storage provider is
+ used, they will be stored in a way that is compatible with
+ the `planet` CLI.
+ storage_provider: A custom storage provider to save session state
+ for the application.
+ """
+ plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL
plauth_config_dict["client_type"] = "oidc_device_code"
+ plauth_config_dict["client_id"] = client_id
+ if requested_scopes:
+ plauth_config_dict["scopes"] = requested_scopes
+
+ if not profile_name:
+ profile_name = client_id
+ normalized_profile_name = Auth._normalize_profile_name(profile_name)
- # Other client types have other needs.
- # Confidential clients need client secrets.
- # Auth code clients need callback URLs.
- # plauth_config_dict["client_secret"] = client_id # Only needed if we support certain types of clients
-
- # TODO
- # This will not write the constructed config to the user's
- # ~/.planet/ dir the way a conf constructed by a cli command like
- # `planet auth login --client-id XXX --client-secret YYY` will.
- # The intent of doing it through the planet_auth_utils factory is so we
- # play well with tooling like the CLI. This maybe does not quite achieve
- # the desired result. We are saving tokens in the right place, but not
- # giving the CLI all it needs to co-manage said tokens with whatever app
- # is being build on the library. Those are perhaps separate decisions,
- # anyway.
- pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_with_config(
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_from_custom_config(
client_config=plauth_config_dict,
- # TODO - Probably need a user friendly profile name
- # We should also probably agree with what's registered in the Auth server.
- profile_name=client_id.lower(),
- save_token_file=save_token_file)
- return Auth.from_plauth(pl_authlib_context)
+ initial_token_data={},
+ save_token_file=save_state_to_storage,
+ profile_name=normalized_profile_name,
+ save_profile_config=save_state_to_storage,
+ storage_provider=storage_provider,
+ )
+
+ return Auth._from_plauth(pl_authlib_context)
@staticmethod
- def from_oauth_m2m(client_id: str, client_secret: str) -> AuthType:
- """Create authentication from the specified OAuth2 service account
- client ID and secret.
+ def from_oauth_m2m(
+ client_id: str,
+ client_secret: str,
+ requested_scopes: typing.Optional[List[str]] = None,
+ save_state_to_storage: bool = True,
+ profile_name: typing.Optional[str] = None,
+ storage_provider: planet_auth.ObjectStorageProvider = None,
+ ) -> AuthType:
+ """
+ Create authentication from the specified OAuth2 service account
+ client ID and secret.
Parameters:
client_id: Planet service account client ID.
client_secret: Planet service account client secret.
+ requested_scopes: List of requested OAuth2 scopes
+ profile_name: User friendly name to use when saving the configuration
+ to storage per the `save_state_to_storage` flag. The profile name
+ will be normalized to a file system compatible identifier regardless
+ of the storage provider being used.
+ save_state_to_storage: Boolean controlling whether login sessions
+ should be saved to storage. When the default storage provider is
+ used, they will be stored in a way that is compatible with
+ the `planet` CLI.
+ storage_provider: A custom storage provider to save session state
+ for the application.
"""
- pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(
- auth_client_id_opt=client_id,
- auth_client_secret_opt=client_secret,
- # auth_profile_opt=_BuiltinConfigurationProvider.BUILTIN_PROFILE_NAME_PLANET_M2M,
+ plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL
+ plauth_config_dict["client_id"] = client_id
+ plauth_config_dict["client_secret"] = client_secret
+ if requested_scopes:
+ plauth_config_dict["scopes"] = requested_scopes
+
+ if not profile_name:
+ profile_name = client_id
+ normalized_profile_name = Auth._normalize_profile_name(profile_name)
+
+ pl_authlib_context = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context_from_custom_config(
+ client_config=plauth_config_dict,
+ initial_token_data={},
+ save_token_file=save_state_to_storage,
+ profile_name=normalized_profile_name,
+ save_profile_config=save_state_to_storage,
+ storage_provider=storage_provider,
)
- return _PLAuthLibAuth(plauth=pl_authlib_context)
+ return Auth._from_plauth(pl_authlib_context)
@staticmethod
- def from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
+ def _from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
"""
Create authentication from the provided Planet Auth Library
Authentication Context. Generally, applications will want to use one
@@ -172,8 +319,9 @@ def from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
factory class).
This method is intended for advanced use cases where the developer
- as their own client ID registered. (A feature of the Planet Platform
- not yet released to the public as of January 2025.)
+ has their own client ID registered, and is familiar with the
+ Planet Auth Library. (Registering client IDs is a feature of the
+ Planet Platform not yet released to the public as of January 2025.)
"""
return _PLAuthLibAuth(plauth=pl_authlib_context)
@@ -257,7 +405,8 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
"""
warnings.warn(
"from_env() will be deprecated. Use from_defaults() in most"
- " cases, which will consider environment variables.",
+ " cases, which will consider both environment variables and user"
+ " configuration files.",
PendingDeprecationWarning)
variable_name = variable_name or planet_auth_utils.EnvironmentVariables.AUTH_API_KEY
api_key = os.getenv(variable_name, None)
@@ -308,14 +457,33 @@ class APIKeyAuthException(PlanetError):
pass
-class _PLAuthLibAuth(Auth, AuthType):
+class _PLAuthLibAuth(AuthType):
# The Planet Auth Library uses a "has a" authenticator pattern for its
# planet_auth.Auth context class. This SDK library employs a "is a"
- # authenticator design pattern for user's of its Auth context obtained
- # from the constructors above. This class partially smooths over that
- # design difference as we move to using the Planet Auth Library.
+ # authenticator design pattern for users of its Auth context obtained
+ # from the constructors above. This class smooths over that design
+ # difference as we move to using the Planet Auth Library.
def __init__(self, plauth: planet_auth.Auth):
self._plauth = plauth
def auth_flow(self, r: httpx._models.Request):
return self._plauth.request_authenticator().auth_flow(r)
+
+ def user_login(
+ self,
+ allow_open_browser: typing.Optional[bool] = False,
+ allow_tty_prompt: typing.Optional[bool] = False,
+ ):
+ self._plauth.login(
+ allow_open_browser=allow_open_browser,
+ allow_tty_prompt=allow_tty_prompt,
+ )
+
+ def device_user_login_initiate(self) -> dict:
+ return self._plauth.device_login_initiate()
+
+ def device_user_login_complete(self, login_initialization_info: dict):
+ return self._plauth.device_login_complete(login_initialization_info)
+
+ def is_initialized(self) -> bool:
+ return self._plauth.request_authenticator_is_ready()
From 04ab6bc302cf4fba0ce674ddfd10de2e8e4e253c Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:20:53 -0800
Subject: [PATCH 59/81] disable cache for dev
---
.github/workflows/test.yml | 70 +++++++++++++++++++-------------------
1 file changed, 35 insertions(+), 35 deletions(-)
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7b772de0..0b17cbf8 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,13 +13,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v4
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ # - name: Pip cache
+ # uses: actions/cache@v4
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -35,13 +35,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v4
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ # - name: Pip cache
+ # uses: actions/cache@v4
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -63,13 +63,13 @@ jobs:
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- - name: Pip cache
- uses: actions/cache@v4
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ # - name: Pip cache
+ # uses: actions/cache@v4
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Test
run: |
pip install --upgrade nox
@@ -85,13 +85,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v4
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ # - name: Pip cache
+ # uses: actions/cache@v4
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Coverage run and report
run: |
pip install --upgrade nox
@@ -107,13 +107,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- - name: Pip cache
- uses: actions/cache@v4
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip
- restore-keys: |
- ${{ runner.os }}-pip
+ # - name: Pip cache
+ # uses: actions/cache@v4
+ # with:
+ # path: ~/.cache/pip
+ # key: ${{ runner.os }}-pip
+ # restore-keys: |
+ # ${{ runner.os }}-pip
- name: Build Docs
run: |
pip install --upgrade nox
From 4b2bb54b1a55a78ac09c24000d4d50b3bdaa839c Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:22:44 -0800
Subject: [PATCH 60/81] re-enable pip cache
---
.github/workflows/test.yml | 70 +++++++++++++++++++-------------------
1 file changed, 35 insertions(+), 35 deletions(-)
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 0b17cbf8..7b772de0 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,13 +13,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- # - name: Pip cache
- # uses: actions/cache@v4
- # with:
- # path: ~/.cache/pip
- # key: ${{ runner.os }}-pip
- # restore-keys: |
- # ${{ runner.os }}-pip
+ - name: Pip cache
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip
+ restore-keys: |
+ ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -35,13 +35,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- # - name: Pip cache
- # uses: actions/cache@v4
- # with:
- # path: ~/.cache/pip
- # key: ${{ runner.os }}-pip
- # restore-keys: |
- # ${{ runner.os }}-pip
+ - name: Pip cache
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip
+ restore-keys: |
+ ${{ runner.os }}-pip
- name: Lint
run: |
pip install --upgrade nox
@@ -63,13 +63,13 @@ jobs:
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- # - name: Pip cache
- # uses: actions/cache@v4
- # with:
- # path: ~/.cache/pip
- # key: ${{ runner.os }}-pip
- # restore-keys: |
- # ${{ runner.os }}-pip
+ - name: Pip cache
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip
+ restore-keys: |
+ ${{ runner.os }}-pip
- name: Test
run: |
pip install --upgrade nox
@@ -85,13 +85,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- # - name: Pip cache
- # uses: actions/cache@v4
- # with:
- # path: ~/.cache/pip
- # key: ${{ runner.os }}-pip
- # restore-keys: |
- # ${{ runner.os }}-pip
+ - name: Pip cache
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip
+ restore-keys: |
+ ${{ runner.os }}-pip
- name: Coverage run and report
run: |
pip install --upgrade nox
@@ -107,13 +107,13 @@ jobs:
uses: actions/setup-python@v4
with:
python-version: 3.12
- # - name: Pip cache
- # uses: actions/cache@v4
- # with:
- # path: ~/.cache/pip
- # key: ${{ runner.os }}-pip
- # restore-keys: |
- # ${{ runner.os }}-pip
+ - name: Pip cache
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip
+ restore-keys: |
+ ${{ runner.os }}-pip
- name: Build Docs
run: |
pip install --upgrade nox
From ca4e0db6c14bf6e7908909fb0061f30363a958e0 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:24:56 -0800
Subject: [PATCH 61/81] fix pyproject.toml
---
pyproject.toml | 1 -
1 file changed, 1 deletion(-)
diff --git a/pyproject.toml b/pyproject.toml
index 03cdc89e..0ae42cb0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -57,7 +57,6 @@ docs = [
dev = [
"planet[test, docs, lint]",
]
-dev = ["planet[test, docs, lint]"]
[project.scripts]
planet = "planet.cli.cli:main"
From e84fc2c2b698fa7b2f3f097ccb67d0c0e1c66242 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:26:25 -0800
Subject: [PATCH 62/81] linting fixes
---
.../auth-session-management/cli_managed_auth_state__explicit.py | 2 +-
.../cli_managed_auth_state__specific_auth_profile.py | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/examples/auth-session-management/cli_managed_auth_state__explicit.py b/examples/auth-session-management/cli_managed_auth_state__explicit.py
index c512560a..3aff87c9 100644
--- a/examples/auth-session-management/cli_managed_auth_state__explicit.py
+++ b/examples/auth-session-management/cli_managed_auth_state__explicit.py
@@ -13,7 +13,7 @@ def example_main():
plsdk_auth = planet.Auth.from_user_default_session()
if not plsdk_auth.is_initialized():
- print(f"Login required. Execute the following command:\n\n\tplanet auth login\n")
+ print("Login required. Execute the following command:\n\n\tplanet auth login\n")
sys.exit(99)
# Create a Planet SDK object that uses the loaded auth session.
diff --git a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
index 4f519ed6..c4da4c2e 100644
--- a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
+++ b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
@@ -19,7 +19,7 @@ def example_main():
# If required, how to login depends on what is configured in the specific
# profile. See other examples for login calls.
if not plsdk_auth.is_initialized():
- print(f"Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n")
+ print("Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n")
sys.exit(99)
# Create a Planet SDK object that uses the loaded auth session.
From 71479f629a02cee21695776abb8bbe372d78a0c3 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:28:56 -0800
Subject: [PATCH 63/81] linting
---
...app_managed_auth_state__app_custom_storage__oauth_m2m.py | 6 ++++--
...app_custom_storage__oauth_user_authcode__with_browser.py | 6 ++++--
...stom_storage__oauth_user_devicecode__external_browser.py | 6 ++++--
.../cli_managed_auth_state__explicit.py | 4 +++-
.../cli_managed_auth_state__specific_auth_profile.py | 4 +++-
planet/auth.py | 5 +++--
planet/auth_builtins.py | 3 +--
7 files changed, 22 insertions(+), 12 deletions(-)
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
index 7e20c05f..c0a68c48 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py
@@ -8,7 +8,6 @@
from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
-
logging.basicConfig(level=logging.CRITICAL)
@@ -57,7 +56,10 @@ def _save_file(file_path: pathlib.Path, data: dict):
logging.debug(msg="Writing JSON data to file {}".format(file_path))
with open(file_path, mode="w", encoding="UTF-8") as file_w:
os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
- _no_none_data = {key: value for key, value in data.items() if value is not None}
+ _no_none_data = {
+ key: value
+ for key, value in data.items() if value is not None
+ }
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
index 83e18596..ba308819 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py
@@ -8,7 +8,6 @@
from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
-
logging.basicConfig(level=logging.CRITICAL)
@@ -57,7 +56,10 @@ def _save_file(file_path: pathlib.Path, data: dict):
logging.debug(msg="Writing JSON data to file {}".format(file_path))
with open(file_path, mode="w", encoding="UTF-8") as file_w:
os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
- _no_none_data = {key: value for key, value in data.items() if value is not None}
+ _no_none_data = {
+ key: value
+ for key, value in data.items() if value is not None
+ }
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
index e1b9bd37..904046db 100644
--- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
+++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py
@@ -8,7 +8,6 @@
from planet_auth import ObjectStorageProvider, ObjectStorageProvider_KeyType
-
logging.basicConfig(level=logging.CRITICAL)
@@ -57,7 +56,10 @@ def _save_file(file_path: pathlib.Path, data: dict):
logging.debug(msg="Writing JSON data to file {}".format(file_path))
with open(file_path, mode="w", encoding="UTF-8") as file_w:
os.chmod(file_path, stat.S_IREAD | stat.S_IWRITE)
- _no_none_data = {key: value for key, value in data.items() if value is not None}
+ _no_none_data = {
+ key: value
+ for key, value in data.items() if value is not None
+ }
file_w.write(json.dumps(_no_none_data, indent=2, sort_keys=True))
diff --git a/examples/auth-session-management/cli_managed_auth_state__explicit.py b/examples/auth-session-management/cli_managed_auth_state__explicit.py
index 3aff87c9..2a8a68f0 100644
--- a/examples/auth-session-management/cli_managed_auth_state__explicit.py
+++ b/examples/auth-session-management/cli_managed_auth_state__explicit.py
@@ -13,7 +13,9 @@ def example_main():
plsdk_auth = planet.Auth.from_user_default_session()
if not plsdk_auth.is_initialized():
- print("Login required. Execute the following command:\n\n\tplanet auth login\n")
+ print(
+ "Login required. Execute the following command:\n\n\tplanet auth login\n"
+ )
sys.exit(99)
# Create a Planet SDK object that uses the loaded auth session.
diff --git a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
index c4da4c2e..f1583ac9 100644
--- a/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
+++ b/examples/auth-session-management/cli_managed_auth_state__specific_auth_profile.py
@@ -19,7 +19,9 @@ def example_main():
# If required, how to login depends on what is configured in the specific
# profile. See other examples for login calls.
if not plsdk_auth.is_initialized():
- print("Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n")
+ print(
+ "Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n"
+ )
sys.exit(99)
# Create a Planet SDK object that uses the loaded auth session.
diff --git a/planet/auth.py b/planet/auth.py
index acc4ce75..978635eb 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -33,6 +33,7 @@
class AuthType(abc.ABC, httpx.Auth):
+
@abc.abstractmethod
def user_login(
self,
@@ -375,8 +376,8 @@ def from_file(
PendingDeprecationWarning)
plauth_config = {
**_ProductionEnv.LEGACY_AUTH_AUTHORITY,
- "client_type":
- planet_auth.PlanetLegacyAuthClientConfig.meta().get("client_type"),
+ "client_type": planet_auth.PlanetLegacyAuthClientConfig.meta().get(
+ "client_type"),
}
pl_authlib_context = planet_auth.Auth.initialize_from_config_dict(
client_config=plauth_config,
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 512ac3e0..62d2f605 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -45,8 +45,7 @@ class _ProductionEnv:
"audiences": ["https://api.planet.com/"]
}
LEGACY_AUTH_AUTHORITY = {
- "_comment":
- "Planet legacy JWT auth server used by Planet Public API endpoints",
+ "_comment": "Planet legacy JWT auth server used by Planet Public API endpoints",
"legacy_auth_endpoint": "https://api.planet.com/v0/auth/login"
}
PUBLIC_OAUTH_AUTHORITIES = [
From 91486da2e82b908d118c01f28e2698102a896fb4 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:31:12 -0800
Subject: [PATCH 64/81] type hint fixes
---
planet/auth.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/planet/auth.py b/planet/auth.py
index 978635eb..e3ff8be7 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -270,7 +270,7 @@ def from_oauth_m2m(
requested_scopes: typing.Optional[List[str]] = None,
save_state_to_storage: bool = True,
profile_name: typing.Optional[str] = None,
- storage_provider: planet_auth.ObjectStorageProvider = None,
+ storage_provider: typing.Optional[planet_auth.ObjectStorageProvider] = None,
) -> AuthType:
"""
Create authentication from the specified OAuth2 service account
From c7f2730b1b18b105076e39f41bf86012fb9fc6b0 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:35:35 -0800
Subject: [PATCH 65/81] update tests to use new auth constructor.
---
tests/integration/test_features_api.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/tests/integration/test_features_api.py b/tests/integration/test_features_api.py
index 4ae55483..a8cd5c7f 100644
--- a/tests/integration/test_features_api.py
+++ b/tests/integration/test_features_api.py
@@ -20,7 +20,7 @@
import respx
from planet import FeaturesClient, Session
-from planet.auth import APIKeyAuth
+from planet.auth import Auth
from planet.sync.features import FeaturesAPI
pytestmark = pytest.mark.anyio # noqa
@@ -47,7 +47,7 @@
TEST_COLLECTION_LIST = [TEST_COLLECTION_1, TEST_COLLECTION_2]
# set up test clients
-test_session = Session(auth=APIKeyAuth(key="test"))
+test_session = Session(auth=Auth.from_key(key="test"))
cl_async = FeaturesClient(test_session, base_url=TEST_URL)
cl_sync = FeaturesAPI(test_session, base_url=TEST_URL)
From 9dec5951805bc1c006ac84cdb56c1a5d1c49e1e2 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 18:41:26 -0800
Subject: [PATCH 66/81] linting
---
planet/auth.py | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index e3ff8be7..78b74135 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -25,8 +25,6 @@
import planet_auth
import planet_auth_utils
-from planet_auth import ObjectStorageProvider
-
from .constants import SECRET_FILE_PATH
from .auth_builtins import _ProductionEnv, _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL, _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL
from .exceptions import PlanetError
@@ -150,7 +148,8 @@ def from_oauth_user_auth_code(
requested_scopes: typing.Optional[List[str]] = None,
save_state_to_storage: bool = True,
profile_name: typing.Optional[str] = None,
- storage_provider: typing.Optional[ObjectStorageProvider] = None,
+ storage_provider: typing.Optional[
+ planet_auth.ObjectStorageProvider] = None,
) -> AuthType:
"""
Create authentication for the specified registered client
@@ -210,7 +209,8 @@ def from_oauth_user_device_code(
requested_scopes: typing.Optional[List[str]] = None,
save_state_to_storage: bool = True,
profile_name: typing.Optional[str] = None,
- storage_provider: typing.Optional[ObjectStorageProvider] = None
+ storage_provider: typing.Optional[
+ planet_auth.ObjectStorageProvider] = None
) -> AuthType:
"""
Create authentication for the specified registered client
@@ -270,7 +270,8 @@ def from_oauth_m2m(
requested_scopes: typing.Optional[List[str]] = None,
save_state_to_storage: bool = True,
profile_name: typing.Optional[str] = None,
- storage_provider: typing.Optional[planet_auth.ObjectStorageProvider] = None,
+ storage_provider: typing.Optional[
+ planet_auth.ObjectStorageProvider] = None,
) -> AuthType:
"""
Create authentication from the specified OAuth2 service account
From 28e7857d7ee541941b8696e9c75d3c4026b5daf3 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 19:36:36 -0800
Subject: [PATCH 67/81] adjust class relationships for AuthType
---
planet/auth.py | 118 ++++++++++++++++++++++++-------------------------
1 file changed, 59 insertions(+), 59 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 78b74135..3676d182 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -30,52 +30,7 @@
from .exceptions import PlanetError
-class AuthType(abc.ABC, httpx.Auth):
-
- @abc.abstractmethod
- def user_login(
- self,
- allow_open_browser: typing.Optional[bool] = False,
- allow_tty_prompt: typing.Optional[bool] = False,
- ):
- """
- Perform an interactive login. User interaction will be via the TTY
- and/or a local web browser, with the details dependent on the
- client auth configuration.
-
- :param allow_open_browser:
- :param allow_tty_prompt:
- """
-
- @abc.abstractmethod
- def device_user_login_initiate(self) -> dict:
- """
- Initiate a user login that uses the OAuth2 Device Code Flow for applications
- that cannot operate a browser locally. The returned dictionary should be used
- to prompt the user to complete the process, and will conform to RFC 8628.
- """
-
- @abc.abstractmethod
- def device_user_login_complete(self, login_initialization_info: dict):
- """
- Complete a user login that uses the OAuth2 Device Code Flow for applications
- that was initiated by a call to `device_user_login_initiate()`. The structure
- that was returned from `device_user_login_initiate()` should be passed
- to this function unaltered after it has been used to prompt the user.
- """
-
- @abc.abstractmethod
- def is_initialized(self) -> bool:
- """
- Check whether the user session has been initialized. For OAuth2
- user based sessions, this means that a login has been performed
- or saved login session data has been located. For M2M and API Key
- sessions, this should be true if keys or secrets have been
- properly configured.
- """
-
-
-class Auth(metaclass=abc.ABCMeta):
+class Auth(abc.ABC, httpx.Auth):
"""
Handle authentication information for use with Planet APIs.
Static constructor methods should be used to create an auth context
@@ -92,7 +47,7 @@ def _normalize_profile_name(profile_name):
return profile_name.lower()
@staticmethod
- def from_user_default_session() -> AuthType:
+ def from_user_default_session() -> Auth:
"""
Create authentication from user defaults.
@@ -122,7 +77,7 @@ def from_user_default_session() -> AuthType:
initialize_auth_client_context())
@staticmethod
- def from_profile(profile_name: str) -> AuthType:
+ def from_profile(profile_name: str) -> Auth:
"""
Create authentication for a user whose initialized login information
has been saved to `~/.planet.json` and `~/.planet/`.
@@ -150,7 +105,7 @@ def from_oauth_user_auth_code(
profile_name: typing.Optional[str] = None,
storage_provider: typing.Optional[
planet_auth.ObjectStorageProvider] = None,
- ) -> AuthType:
+ ) -> Auth:
"""
Create authentication for the specified registered client
application.
@@ -211,7 +166,7 @@ def from_oauth_user_device_code(
profile_name: typing.Optional[str] = None,
storage_provider: typing.Optional[
planet_auth.ObjectStorageProvider] = None
- ) -> AuthType:
+ ) -> Auth:
"""
Create authentication for the specified registered client
application.
@@ -272,7 +227,7 @@ def from_oauth_m2m(
profile_name: typing.Optional[str] = None,
storage_provider: typing.Optional[
planet_auth.ObjectStorageProvider] = None,
- ) -> AuthType:
+ ) -> Auth:
"""
Create authentication from the specified OAuth2 service account
client ID and secret.
@@ -313,7 +268,7 @@ def from_oauth_m2m(
return Auth._from_plauth(pl_authlib_context)
@staticmethod
- def _from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
+ def _from_plauth(pl_authlib_context: planet_auth.Auth) -> Auth:
"""
Create authentication from the provided Planet Auth Library
Authentication Context. Generally, applications will want to use one
@@ -328,7 +283,7 @@ def _from_plauth(pl_authlib_context: planet_auth.Auth) -> AuthType:
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
- def from_key(key: typing.Optional[str]) -> AuthType:
+ def from_key(key: typing.Optional[str]) -> Auth:
"""Obtain authentication from api key.
Parameters:
@@ -350,8 +305,8 @@ def from_key(key: typing.Optional[str]) -> AuthType:
@staticmethod
def from_file(
- filename: typing.Optional[typing.Union[str, pathlib.Path]] = None
- ) -> AuthType:
+ filename: typing.Optional[typing.Union[str,
+ pathlib.Path]] = None) -> Auth:
"""Create authentication from secret file.
The default secret file is named `.planet.json` and is stored in the user
@@ -390,7 +345,7 @@ def from_file(
return _PLAuthLibAuth(plauth=pl_authlib_context)
@staticmethod
- def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
+ def from_env(variable_name: typing.Optional[str] = None) -> Auth:
"""Create authentication from environment variables.
Reads the `PL_API_KEY` environment variable
@@ -417,7 +372,7 @@ def from_env(variable_name: typing.Optional[str] = None) -> AuthType:
@staticmethod
def from_login(email: str,
password: str,
- base_url: typing.Optional[str] = None) -> AuthType:
+ base_url: typing.Optional[str] = None) -> Auth:
"""Create authentication from login email and password.
Note: To keep your password secure, the use of `getpass` is
@@ -437,7 +392,7 @@ def from_login(email: str,
)
@classmethod
- def from_dict(cls, data: dict) -> AuthType:
+ def from_dict(cls, data: dict) -> Auth:
raise DeprecationWarning("Auth.from_dict() has been deprecated.")
def to_dict(self) -> dict:
@@ -453,13 +408,55 @@ def store(self,
def value(self):
raise DeprecationWarning("Auth.value has been deprecated.")
+ @abc.abstractmethod
+ def user_login(
+ self,
+ allow_open_browser: typing.Optional[bool] = False,
+ allow_tty_prompt: typing.Optional[bool] = False,
+ ):
+ """
+ Perform an interactive login. User interaction will be via the TTY
+ and/or a local web browser, with the details dependent on the
+ client auth configuration.
+
+ :param allow_open_browser:
+ :param allow_tty_prompt:
+ """
+
+ @abc.abstractmethod
+ def device_user_login_initiate(self) -> dict:
+ """
+ Initiate a user login that uses the OAuth2 Device Code Flow for applications
+ that cannot operate a browser locally. The returned dictionary should be used
+ to prompt the user to complete the process, and will conform to RFC 8628.
+ """
+
+ @abc.abstractmethod
+ def device_user_login_complete(self, login_initialization_info: dict):
+ """
+ Complete a user login that uses the OAuth2 Device Code Flow for applications
+ that was initiated by a call to `device_user_login_initiate()`. The structure
+ that was returned from `device_user_login_initiate()` should be passed
+ to this function unaltered after it has been used to prompt the user.
+ """
+
+ @abc.abstractmethod
+ def is_initialized(self) -> bool:
+ """
+ Check whether the user session has been initialized. For OAuth2
+ user based sessions, this means that a login has been performed
+ or saved login session data has been located. For M2M and API Key
+ sessions, this should be true if keys or secrets have been
+ properly configured.
+ """
+
class APIKeyAuthException(PlanetError):
"""exceptions thrown by APIKeyAuth"""
pass
-class _PLAuthLibAuth(AuthType):
+class _PLAuthLibAuth(Auth):
# The Planet Auth Library uses a "has a" authenticator pattern for its
# planet_auth.Auth context class. This SDK library employs a "is a"
# authenticator design pattern for users of its Auth context obtained
@@ -489,3 +486,6 @@ def device_user_login_complete(self, login_initialization_info: dict):
def is_initialized(self) -> bool:
return self._plauth.request_authenticator_is_ready()
+
+
+AuthType = Auth
From e1430fddf49175508b5fabbd9a3e38010631ca7c Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 19:36:44 -0800
Subject: [PATCH 68/81] update tests
---
tests/unit/test_auth.py | 83 +++++++++++++++++++++++++++--------------
1 file changed, 54 insertions(+), 29 deletions(-)
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 505a5767..b987fe62 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -14,6 +14,7 @@
# limitations under the License.
import logging
+import planet_auth_utils
import pytest
import planet.auth
@@ -141,54 +142,60 @@ def test_Auth_from_login(monkeypatch):
def test_Auth_from_user_defaults():
- # The primary implementation is implemented and unit tested by the planet auth libraries.
- # This tests that it doesn't explode with an exception.
+ # The primary implementation is implemented and unit tested by the planet
+ # auth libraries. This tests that it doesn't explode with an exception.
# CI/CD currently is run by configuring auth via PL_API_KEY env var.
- # What this will actually do in an user env depends on a lot of variables.
+ # What this will actually do in a user's environment depends on a lot
+ # of variables.
_ = auth.Auth.from_user_default_session()
-def test_Auth_from_oauth_m2m():
- under_test = auth.Auth.from_oauth_m2m(
- "mock_client_id__from_oauth_m2m", "mock_client_secret__from_oauth_m2m")
+def test_Auth_from_profile__builtin_default_profile():
+ under_test = auth.Auth.from_profile(
+ planet_auth_utils.Builtins.builtin_default_profile_name())
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
assert isinstance(under_test._plauth.auth_client(),
- planet_auth.ClientCredentialsClientSecretAuthClient)
-
- assert under_test._plauth.auth_client()._ccauth_client_config.auth_server(
- ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
+ planet_auth.DeviceCodeAuthClient)
- assert under_test._plauth.auth_client()._ccauth_client_config.client_id(
- ) == "mock_client_id__from_oauth_m2m"
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
+ "auth_server"]
assert under_test._plauth.auth_client(
- )._ccauth_client_config.client_secret(
- ) == "mock_client_secret__from_oauth_m2m"
+ )._devicecode_client_config.client_id(
+ ) == planet.auth_builtins._SDK_CLIENT_ID_PROD
-def test_Auth_from_oauth_user_session():
- under_test = auth.Auth.from_oauth_user_session()
+def test_Auth_from_user_auth_code_client():
+ under_test = auth.Auth.from_oauth_user_auth_code(
+ client_id="mock_client_id__auth_code_client",
+ callback_url="http://localhost:8080",
+ requested_scopes=[
+ PlanetOAuthScopes.PLANET, PlanetOAuthScopes.OFFLINE_ACCESS
+ ],
+ save_state_to_storage=False)
+
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
assert isinstance(under_test._plauth.auth_client(),
- planet_auth.DeviceCodeAuthClient)
+ planet_auth.AuthCodeAuthClient)
assert under_test._plauth.auth_client(
- )._devicecode_client_config.auth_server(
+ )._authcode_client_config.auth_server(
) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
"auth_server"]
- assert under_test._plauth.auth_client(
- )._devicecode_client_config.client_id(
- ) == planet.auth_builtins._SDK_CLIENT_ID_PROD
+ assert under_test._plauth.auth_client()._authcode_client_config.client_id(
+ ) == "mock_client_id__auth_code_client"
-def test_Auth_from_oauth_client_config():
- under_test = auth.Auth.beta_from_oauth_client_config(
- client_id="mock_client_id__from_oauth_config",
+def test_Auth_from_user_device_code_client():
+ under_test = auth.Auth.from_oauth_user_device_code(
+ client_id="mock_client_id__device_code_client",
requested_scopes=[
PlanetOAuthScopes.PLANET, PlanetOAuthScopes.OFFLINE_ACCESS
],
- save_token_file=False)
+ save_state_to_storage=False)
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
assert isinstance(under_test._plauth.auth_client(),
@@ -201,24 +208,42 @@ def test_Auth_from_oauth_client_config():
assert under_test._plauth.auth_client(
)._devicecode_client_config.client_id(
- ) == "mock_client_id__from_oauth_config"
+ ) == "mock_client_id__device_code_client"
+
+
+def test_Auth_from_oauth_m2m():
+ under_test = auth.Auth.from_oauth_m2m(
+ "mock_client_id__from_oauth_m2m", "mock_client_secret__from_oauth_m2m")
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.ClientCredentialsClientSecretAuthClient)
+
+ assert under_test._plauth.auth_client()._ccauth_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_M2M["auth_server"]
+
+ assert under_test._plauth.auth_client()._ccauth_client_config.client_id(
+ ) == "mock_client_id__from_oauth_m2m"
+
+ assert under_test._plauth.auth_client(
+ )._ccauth_client_config.client_secret(
+ ) == "mock_client_secret__from_oauth_m2m"
def test_auth_value_deprecated():
+ test_auth = auth.Auth.from_key("test_deprecated_key")
with pytest.raises(DeprecationWarning):
- test_auth = auth.Auth.from_key("test_deprecated_key")
_ = test_auth.value
def test_auth_store_deprecated():
+ test_auth = auth.Auth.from_key("test_deprecated_key")
with pytest.raises(DeprecationWarning):
- test_auth = auth.Auth.from_key("test_deprecated_key")
test_auth.store()
def test_auth_to_dict_deprecated():
+ test_auth = auth.Auth.from_key("test_deprecated_key")
with pytest.raises(DeprecationWarning):
- test_auth = auth.Auth.from_key("test_deprecated_key")
_ = test_auth.to_dict()
From c0538130e0679816fdb21e3485d438568dcbb151 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 20:24:55 -0800
Subject: [PATCH 69/81] minor updates - kill dead code lines.
---
planet/auth.py | 8 +-------
1 file changed, 1 insertion(+), 7 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 3676d182..5474eb72 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -39,9 +39,7 @@ class Auth(abc.ABC, httpx.Auth):
"""
@staticmethod
- def _normalize_profile_name(profile_name):
- if not profile_name:
- raise ValueError("Profile name must be set")
+ def _normalize_profile_name(profile_name: str):
if profile_name.find(os.sep) != -1:
raise ValueError(f"Profile names cannot contain '{os.sep}'")
return profile_name.lower()
@@ -384,9 +382,6 @@ def from_login(email: str,
base_url: The base URL to use. Defaults to production
authentication API base url.
"""
- warnings.warn(
- "Auth.from_login() has been deprecated. Use Auth.from_user_session().",
- DeprecationWarning)
raise DeprecationWarning(
"Auth.from_login() has been deprecated. Use Auth.from_user_session()."
)
@@ -401,7 +396,6 @@ def to_dict(self) -> dict:
def store(self,
filename: typing.Optional[typing.Union[str,
pathlib.Path]] = None):
- warnings.warn("Auth.store() has been deprecated.", DeprecationWarning)
raise DeprecationWarning("Auth.store() has been deprecated.")
@property
From 26d8737867ef23bab59435af90b1ae259d6ab9ce Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 4 Mar 2025 20:25:10 -0800
Subject: [PATCH 70/81] improve test coverage
---
tests/unit/test_auth.py | 94 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 88 insertions(+), 6 deletions(-)
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index b987fe62..8a2d15df 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -171,9 +171,6 @@ def test_Auth_from_user_auth_code_client():
under_test = auth.Auth.from_oauth_user_auth_code(
client_id="mock_client_id__auth_code_client",
callback_url="http://localhost:8080",
- requested_scopes=[
- PlanetOAuthScopes.PLANET, PlanetOAuthScopes.OFFLINE_ACCESS
- ],
save_state_to_storage=False)
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
@@ -188,13 +185,66 @@ def test_Auth_from_user_auth_code_client():
assert under_test._plauth.auth_client()._authcode_client_config.client_id(
) == "mock_client_id__auth_code_client"
+ assert under_test._plauth.auth_client()._authcode_client_config.scopes(
+ ) == planet.auth_builtins._OIDC_AUTH_CLIENT_CONFIG__USER_SKEL["scopes"]
+
+
+def test_Auth_from_user_auth_code_client_2():
+ under_test = auth.Auth.from_oauth_user_auth_code(
+ client_id="mock_client_id__auth_code_client_2",
+ callback_url="http://localhost:8080",
+ requested_scopes=[PlanetOAuthScopes.PLANET],
+ profile_name="utest-override-default-profile-name-auth-code-2",
+ save_state_to_storage=False)
+
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.AuthCodeAuthClient)
+
+ assert under_test._plauth.auth_client(
+ )._authcode_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
+ "auth_server"]
+
+ assert under_test._plauth.auth_client()._authcode_client_config.client_id(
+ ) == "mock_client_id__auth_code_client_2"
+
+ assert under_test._plauth.auth_client()._authcode_client_config.scopes(
+ ) == [PlanetOAuthScopes.PLANET]
+
+ assert under_test._plauth.profile_name(
+ ) == "utest-override-default-profile-name-auth-code-2"
+
def test_Auth_from_user_device_code_client():
under_test = auth.Auth.from_oauth_user_device_code(
client_id="mock_client_id__device_code_client",
+ save_state_to_storage=False)
+
+ assert isinstance(under_test, planet.auth._PLAuthLibAuth)
+ assert isinstance(under_test._plauth.auth_client(),
+ planet_auth.DeviceCodeAuthClient)
+
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.auth_server(
+ ) == planet.auth_builtins._ProductionEnv.OAUTH_AUTHORITY_USER[
+ "auth_server"]
+
+ assert under_test._plauth.auth_client(
+ )._devicecode_client_config.client_id(
+ ) == "mock_client_id__device_code_client"
+
+ assert under_test._plauth.auth_client()._devicecode_client_config.scopes(
+ ) == planet.auth_builtins._OIDC_AUTH_CLIENT_CONFIG__USER_SKEL["scopes"]
+
+
+def test_Auth_from_user_device_code_client_2():
+ under_test = auth.Auth.from_oauth_user_device_code(
+ client_id="mock_client_id__device_code_client_2",
requested_scopes=[
- PlanetOAuthScopes.PLANET, PlanetOAuthScopes.OFFLINE_ACCESS
+ PlanetOAuthScopes.PLANET,
],
+ profile_name="utest-override-default-profile-name-device-code-2",
save_state_to_storage=False)
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
@@ -208,12 +258,23 @@ def test_Auth_from_user_device_code_client():
assert under_test._plauth.auth_client(
)._devicecode_client_config.client_id(
- ) == "mock_client_id__device_code_client"
+ ) == "mock_client_id__device_code_client_2"
+
+ assert under_test._plauth.auth_client()._devicecode_client_config.scopes(
+ ) == [PlanetOAuthScopes.PLANET]
+
+ assert under_test._plauth.profile_name(
+ ) == "utest-override-default-profile-name-device-code-2"
def test_Auth_from_oauth_m2m():
under_test = auth.Auth.from_oauth_m2m(
- "mock_client_id__from_oauth_m2m", "mock_client_secret__from_oauth_m2m")
+ client_id="mock_client_id__from_oauth_m2m",
+ client_secret="mock_client_secret__from_oauth_m2m",
+ requested_scopes=[
+ PlanetOAuthScopes.PLANET,
+ ],
+ )
assert isinstance(under_test, planet.auth._PLAuthLibAuth)
assert isinstance(under_test._plauth.auth_client(),
planet_auth.ClientCredentialsClientSecretAuthClient)
@@ -228,6 +289,27 @@ def test_Auth_from_oauth_m2m():
)._ccauth_client_config.client_secret(
) == "mock_client_secret__from_oauth_m2m"
+ assert under_test._plauth.auth_client()._ccauth_client_config.scopes() == [
+ PlanetOAuthScopes.PLANET
+ ]
+
+
+def test_Auth_profile_name_normalization():
+ under_test = auth.Auth.from_oauth_m2m(
+ client_id="mock_client_id__from_oauth_m2m",
+ client_secret="mock_client_secret__from_oauth_m2m",
+ profile_name="mIxeD_CaSe")
+
+ assert under_test._plauth.profile_name() == "mixed_case"
+
+
+def test_Auth_profile_name_illegal():
+ with pytest.raises(ValueError):
+ _ = auth.Auth.from_oauth_m2m(
+ client_id="mock_client_id__from_oauth_m2m",
+ client_secret="mock_client_secret__from_oauth_m2m",
+ profile_name="path/sep/not/allowed")
+
def test_auth_value_deprecated():
test_auth = auth.Auth.from_key("test_deprecated_key")
From 2c151d0b62aedc8f25f143e0bdda06c9da078f7d Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Thu, 6 Mar 2025 11:12:43 -0800
Subject: [PATCH 71/81] adjust hard failure level for code coverage
---
setup.cfg | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/setup.cfg b/setup.cfg
index 95d610d5..6199f4c1 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -18,7 +18,7 @@ branch = True
[coverage:report]
skip_covered = True
show_missing = True
-fail_under = 98
+fail_under = 90
[yapf]
based_on_style = pep8
From 79f3b73fe09b51fb24a46032b3f359ed7cf4d4d2 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sat, 8 Mar 2025 20:31:41 -0800
Subject: [PATCH 72/81] adjust logging
---
planet/auth_builtins.py | 3 +++
1 file changed, 3 insertions(+)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 62d2f605..cb7a902e 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -19,6 +19,9 @@
os.environ[
"PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
+from planet_auth.logging.auth_logger import setStructuredLogging
+# setPyLoggerForAuthLogger(logging.getLogger("planet_auth_sdk"))
+setStructuredLogging(nested_key=None)
# No StrEnum in our lowest supported Python version
# class PlanetOAuthScopes(enum.StrEnum):
From 62e3ed190601274963e8ce41e2a71c6f729e592b Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sun, 9 Mar 2025 18:33:20 -0700
Subject: [PATCH 73/81] use a published version
---
pyproject.toml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/pyproject.toml b/pyproject.toml
index 0ae42cb0..2162da3f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ dependencies = [
"pyjwt>=2.1",
"tqdm>=4.56",
"typing-extensions",
- "planet-auth @ https://github.com/planetlabs/planet-auth-python/archive/refs/heads/carl/sdk-integration-work.zip"
+ "planet-auth==2.0.4.1741569482b0"
]
readme = "README.md"
requires-python = ">=3.9"
From b60e1ff5dfd83398de23103fd85d4766b699d327 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Sun, 9 Mar 2025 18:39:30 -0700
Subject: [PATCH 74/81] lint fixes
---
planet/auth_builtins.py | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index cb7a902e..7f9be8fd 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -13,16 +13,18 @@
# limitations under the License.
import os
from typing import Dict, List, Optional
+from planet_auth.logging.auth_logger import setStructuredLogging
from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
-# Needs to be set at runtime (not necessarily at import time) for dependency injection to planet_auth_util
+# Needs to be set at runtime (not necessarily at import time) for dependency
+# injection to planet_auth_util
os.environ[
"PL_AUTH_BUILTIN_CONFIG_PROVIDER"] = "planet.auth_builtins._BuiltinConfigurationProvider"
-from planet_auth.logging.auth_logger import setStructuredLogging
# setPyLoggerForAuthLogger(logging.getLogger("planet_auth_sdk"))
setStructuredLogging(nested_key=None)
+
# No StrEnum in our lowest supported Python version
# class PlanetOAuthScopes(enum.StrEnum):
class PlanetOAuthScopes:
From eade4c63b1dfdd0f7da8f06aa69d25f9b2ab3769 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 10 Mar 2025 09:18:05 -0700
Subject: [PATCH 75/81] minor updates
---
CHANGES.txt | 12 +++++-
OAuth-Reviewer-and-Release-Notes.md | 62 -----------------------------
docs/python/sdk-client-auth.md | 21 +++++-----
3 files changed, 23 insertions(+), 72 deletions(-)
delete mode 100644 OAuth-Reviewer-and-Release-Notes.md
diff --git a/CHANGES.txt b/CHANGES.txt
index 19483a69..ba31df5b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,6 +1,16 @@
+3.0.0 (Unreleased)
+- Overhaul of planet.Auth AP interface to leverage the
+ [Planet Auth Utility Library](https://github.com/planetlabs/planet-auth-python)
+ and move preferred authentication mechanisms to OAuth2 over API keys.
+ See the Client Authentication Guide in the documentation for details and
+ examples.
+- Overhaul of the `planet auth` CLI to support Auth infrastructure overhaul.
+ Of immediate note to uses is that `planet auth login` should be preferred
+ to `planet auth init` to initialize the CLI client for use.
+
2.13.0 (2024-12-18)
- Add Planet class (`from planet import Planet`)
- - Planet is a client that uses sync methods. Users do not have
+ - Planet is a client that uses sync methods. Users do not have
to interact with asyncio to use the sync client.
- the Planet class is implemented by calling out to the async methods.
This should be transparent to users. Depending on uptake and feedback,
diff --git a/OAuth-Reviewer-and-Release-Notes.md b/OAuth-Reviewer-and-Release-Notes.md
deleted file mode 100644
index 48d850fa..00000000
--- a/OAuth-Reviewer-and-Release-Notes.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Overview
-* Auth functions are now implemented by the `planet_auth` and
- `planet_auth_utils` libraries.
-* The use of API keys and Planet's legacy username/password based
- authentication protocol is being phased out in favor of OAuth2 based
- mechanisms. These legacy mechanisms remain in place for the time being,
- but clients are encouraged to start adopting OAuth2.
-
-# Changes to the `planet auth` CLI command
-* Deprecated:
- * The `planet auth init` command has been marked as deprecated, and will be
- removed in a future release. The `planet auth init` command operates using
- Planet's proprietary username/password based authentication protocol and
- durable API keys. This protocol will be phased out in favor of OAuth2.
- Use of durable API keys are discouraged in favor of time limited OAuth2
- access tokens.
- * The `planet auth store` command has been marked as deprecated, and will be
- removed in a future release.
- * The `planet auth value` command has been marked as deprecated, and will be
- removed in a future release.
-* Replacements:
- * The `planet auth login` command should replace both `planet auth init` for
- initializing authentication for interactive CLI use, and `planet auth store`
- for initializing authentication for other use cases. This command will
- store OAuth2 access and refresh tokens and perform any other necessary
- configuration.
- * The `planet auth print-access-token` command provides a similar function
- for obtaining current access tokens that can be used in scripted cases.
-* Additions:
- * _Auth profiles_
- * Auth profiles are a new addition to the Planet Client SDK, and come from
- the underlying `planet_auth` library. Profiles encapsulate a number of
- related auth concerns, and can be used to manage multiple client sessions
- with separate identities or underlying protocol configurations.
- * The Planet CLI provides a number of commands for manipulating profiles
- geared for Planet CLI users and use cases:
- * `planet auth profile-show`
- * `planet auth profile-list`
- * `planet auth profile-set`
- * `plauth` - The `planet_auth_utils` library provides a separate, lower level
- `plauth` command line utility for expert use cases.
-
-# Library API changes
-* TODO - Document
-
-# On-disk interface changes
-* TODO - Document
-
-# Misc Notes
-* The interfaces for the `planet_auth` and `planet_auth_utils` libraries are
- not currently considered to be as stable as the `planet` library.
-
-# Release Sequencing & Requirements
-* Planet APIs need to accept SH M2M tokens.
-* Users/Admins need a good way to register/manage M2M clients.
-
-
-# Branch TODO
-- I think this bumps to version 3
-- update API docs
-- Update example docs
-- Update new dev center docs
diff --git a/docs/python/sdk-client-auth.md b/docs/python/sdk-client-auth.md
index 1bd5f3f9..5014e2f8 100644
--- a/docs/python/sdk-client-auth.md
+++ b/docs/python/sdk-client-auth.md
@@ -1,9 +1,5 @@
# Client Authentication Guide
-[TOC]
-
-----
-
## Introduction
All calls to Planet APIs must be authenticated. Only authorized clients may
use Planet Platform APIs.
@@ -14,11 +10,18 @@ the [Authentication](https://docs.planet.com/develop/authentication) section of
!!! warning
Some statements are forward-looking. OAuth2 M2M tokens are
currently only supported by `services.sentine-hub.com` and not supported
- by `api.planet.com`. All APIs support interactive user OAuth2 access
- tokens, but a process for developers to register and manage clients has
- not yet been made public. We have also not yet release a way for end-users
- of such applications to manage which applications have been authorized
- to access the platform on their behalf.
+ by `api.planet.com`.
+
+ All APIs support interactive user OAuth2 access tokens, but a process for
+ developers to register and manage clients has not yet been made public.
+ We have also not yet release a way for end-users of such applications to
+ manage which applications have been authorized to access the platform on
+ their behalf.)
+
+ If you would like to developed an interactive application that uses
+ Planet's APIs on behalf of a user (as the `planet` CLI utility does),
+ please contact Planet and work with engineering to register your
+ application.
----
## Authentication Protocols
From 9a46005707bf407ec7e834d8739eed2de23c7ca0 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 10 Mar 2025 10:30:35 -0700
Subject: [PATCH 76/81] fix typo
---
docs/python/sdk-client-auth.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/python/sdk-client-auth.md b/docs/python/sdk-client-auth.md
index 5014e2f8..bcc3adfa 100644
--- a/docs/python/sdk-client-auth.md
+++ b/docs/python/sdk-client-auth.md
@@ -16,7 +16,7 @@ the [Authentication](https://docs.planet.com/develop/authentication) section of
developers to register and manage clients has not yet been made public.
We have also not yet release a way for end-users of such applications to
manage which applications have been authorized to access the platform on
- their behalf.)
+ their behalf.
If you would like to developed an interactive application that uses
Planet's APIs on behalf of a user (as the `planet` CLI utility does),
From eded1e577b0668998217ad87c746e19613f2add5 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 10 Mar 2025 21:07:22 -0700
Subject: [PATCH 77/81] remove off-named file I had saved locally
---
tests/pytest.ini.main | 4 ----
1 file changed, 4 deletions(-)
delete mode 100644 tests/pytest.ini.main
diff --git a/tests/pytest.ini.main b/tests/pytest.ini.main
deleted file mode 100644
index cd8c265e..00000000
--- a/tests/pytest.ini.main
+++ /dev/null
@@ -1,4 +0,0 @@
-[pytest]
-log_cli = True
-log_format = %(asctime)s %(levelname)s %(message)s
-log_date_format = %Y-%m-%d %H:%M:%S
From 2e1f4d90d92918bb45be47b7e292c7882dd02144 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Tue, 18 Mar 2025 23:42:53 -0700
Subject: [PATCH 78/81] update planet auth
---
pyproject.toml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/pyproject.toml b/pyproject.toml
index 2162da3f..957a0fcb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ dependencies = [
"pyjwt>=2.1",
"tqdm>=4.56",
"typing-extensions",
- "planet-auth==2.0.4.1741569482b0"
+ "planet-auth==2.0.4.1742365883b0"
]
readme = "README.md"
requires-python = ">=3.9"
From c9defc824d3c3e3663267be197b3766c918ad202 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Wed, 19 Mar 2025 14:05:53 -0700
Subject: [PATCH 79/81] update package version
---
pyproject.toml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/pyproject.toml b/pyproject.toml
index 957a0fcb..0bdac4bb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ dependencies = [
"pyjwt>=2.1",
"tqdm>=4.56",
"typing-extensions",
- "planet-auth==2.0.4.1742365883b0"
+ "planet-auth==2.0.4.1742417719b0"
]
readme = "README.md"
requires-python = ">=3.9"
From 2dab6e77305c00df4395e9765f68b97215852450 Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Thu, 27 Mar 2025 18:29:18 -0700
Subject: [PATCH 80/81] copy SKEL usage.
---
planet/auth.py | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/planet/auth.py b/planet/auth.py
index 5474eb72..2a79da8d 100644
--- a/planet/auth.py
+++ b/planet/auth.py
@@ -15,6 +15,7 @@
"""Manage authentication with Planet APIs"""
from __future__ import annotations # https://stackoverflow.com/a/33533514
import abc
+import copy
import os
import pathlib
import typing
@@ -133,7 +134,7 @@ def from_oauth_user_auth_code(
storage_provider: A custom storage provider to save session state
for the application.
"""
- plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL
+ plauth_config_dict = copy.deepcopy(_OIDC_AUTH_CLIENT_CONFIG__USER_SKEL)
plauth_config_dict["client_type"] = "oidc_auth_code"
plauth_config_dict["client_id"] = client_id
if requested_scopes:
@@ -195,7 +196,7 @@ def from_oauth_user_device_code(
storage_provider: A custom storage provider to save session state
for the application.
"""
- plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__USER_SKEL
+ plauth_config_dict = copy.deepcopy(_OIDC_AUTH_CLIENT_CONFIG__USER_SKEL)
plauth_config_dict["client_type"] = "oidc_device_code"
plauth_config_dict["client_id"] = client_id
if requested_scopes:
@@ -245,7 +246,7 @@ def from_oauth_m2m(
storage_provider: A custom storage provider to save session state
for the application.
"""
- plauth_config_dict = _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL
+ plauth_config_dict = copy.deepcopy(_OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL)
plauth_config_dict["client_id"] = client_id
plauth_config_dict["client_secret"] = client_secret
if requested_scopes:
From ad19709b0c25af3270cea461daeb1d8b10b2843d Mon Sep 17 00:00:00 2001
From: "Carl A. Adams" <carl.adams@planet.com>
Date: Mon, 31 Mar 2025 09:18:50 -0700
Subject: [PATCH 81/81] Remove 'none' built-in profile
---
planet/auth_builtins.py | 7 -------
1 file changed, 7 deletions(-)
diff --git a/planet/auth_builtins.py b/planet/auth_builtins.py
index 7f9be8fd..f322f362 100644
--- a/planet/auth_builtins.py
+++ b/planet/auth_builtins.py
@@ -102,10 +102,6 @@ class _ProductionEnv:
"client_type": "planet_legacy",
}
-_NOOP_AUTH_CLIENT_CONFIG = {
- "client_type": "none",
-}
-
class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
"""
@@ -122,7 +118,6 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_PLANET_USER = "planet-user"
BUILTIN_PROFILE_NAME_PLANET_M2M = "planet-m2m"
BUILTIN_PROFILE_NAME_LEGACY = "legacy"
- BUILTIN_PROFILE_NAME_NONE = "none"
# Aliases
# BUILTIN_PROFILE_ALIAS_PLANET_USER = "planet-user"
@@ -132,7 +127,6 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
BUILTIN_PROFILE_NAME_PLANET_USER: _OIDC_AUTH_CLIENT_CONFIG__SDK_PROD,
BUILTIN_PROFILE_NAME_PLANET_M2M: _OIDC_AUTH_CLIENT_CONFIG__M2M_SKEL,
BUILTIN_PROFILE_NAME_LEGACY: _LEGACY_AUTH_CLIENT_CONFIG__PROD,
- BUILTIN_PROFILE_NAME_NONE: _NOOP_AUTH_CLIENT_CONFIG,
}
_builtin_profile_aliases: dict[str, str] = {
@@ -144,7 +138,6 @@ class _BuiltinConfigurationProvider(BuiltinConfigurationProviderInterface):
"oidc_auth_code": BUILTIN_PROFILE_NAME_PLANET_USER,
"oidc_client_credentials_secret": BUILTIN_PROFILE_NAME_PLANET_M2M,
"planet_legacy": BUILTIN_PROFILE_NAME_LEGACY,
- "none": BUILTIN_PROFILE_NAME_NONE,
}
_builtin_trust_realms: Dict[str, Optional[List[dict]]] = {