Skip to content

Commit 7c2a57f

Browse files
carl-adams-planetcarl-adams-planet
authored
updates from beta feedback (#1148)
* updates from beta feedback for improved login CLI experience. * plumb profile copy * update planet-auth per feedback. * formatting for the linter * proofreading. * simplify examples * update links * minor edits to example code * reorder sections * more breadcrumbs in the 'python' housed pointer page for auth docs. * update the auth section in non-auth sub-trees of the doc site * More doc edits for clarification. Adding links to the list of protocols to specific implementaiton examples. * accepting edit suggestion. * adding suggested link * clarifying links page * unhide M2M options for now * add option to control saving to storage to constructor. Doc updates
1 parent bc109b3 commit 7c2a57f

24 files changed

+731
-489
lines changed

‎docs/auth/auth-dev-app-managed-apikey.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Application Managed Sessions - Planet API Key
2+
3+
## Planet API Key Sessions
4+
Legacy applications that need to continue to support Planet API keys may do so
5+
until API keys are deprecated. This method should not be adopted for new
6+
development if possible.
7+
8+
### Examples - Planet API Keys
9+
10+
#### In Memory Session State
11+
Once provided with an API key, an application may operate with the API key
12+
in memory indefinitely without the need to prompt the user for re-authentication.
13+
```python linenums="1" title="Access APIs using Planet API keys in memory"
14+
{% include 'auth-session-management/app_managed_auth_state__in_memory__api_key.py' %}
15+
```
16+
17+
#### Version 2 Compatibility
18+
The SDK continues to support files written by version 2 of the SDK to save
19+
auth state.
20+
```python linenums="1" title="Access APIs using Planet API keys using the on disk file format used by older versions of the SDK"
21+
{% include 'auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py' %}
22+
```
23+
24+
```json linenums="1" title="Legacy API Key file example"
25+
{% include 'auth-session-management/legacy_api_key_file.json' %}
26+
```
27+
28+
#### Session State Shared with CLI
29+
```python linenums="1" title="Access APIs using Planet API keys with CLI managed shared state on disk"
30+
{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py' %}
31+
```
32+
33+
#### Session State Saved to Application Storage
34+
35+
```python linenums="1" title="Access APIs using Planet API keys with sessions persisted to application provided storage"
36+
{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py' %}
37+
```
38+
39+
----

‎docs/auth/auth-dev-app-managed-oauth.md

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Application Managed Sessions - OAuth2
2+
3+
If an application cannot or should not use a login session initiated by the
4+
[`planet auth`](../../cli/cli-reference/#auth) CLI command, the application will be
5+
responsible for managing the process on its own, persisting session state as
6+
needed.
7+
8+
Application managed sessions may be used with all authentication protocols.
9+
Application developers may control whether sessions are visible to the CLI.
10+
This is managed with the `save_state_to_storage` parameter on the `planet.Auth`
11+
constructor methods illustrated below.
12+
13+
The process varies depending on the authentication protocol used.
14+
Depending on the use case, applications may need to support multiple authentication
15+
methods, just as the [`planet`](../../cli/cli-reference) CLI command supports interacting with Planet APIs
16+
using either a user or a service user account.
17+
18+
## OAuth2 Session for Users
19+
User session initialization inherently involves using a web browser to
20+
complete user authentication. This architecture allows for greater security
21+
by keeping the user's password from being directly exposed to the application
22+
code. This also allows for flexibility in user federation and multifactor
23+
authentication procedures without the complexity of these needing to
24+
be exposed to the application developer who is focused on geospatial
25+
operations using the Planet platform, and not the nuances of user
26+
authentication and authorization.
27+
28+
### OAuth2 User Client Registration
29+
Developers of applications must register client applications with Planet, and
30+
will be issued a Client ID as part of that process. Developers should register
31+
a client for each distinct application so that end-users may discretely manage
32+
applications permitted to access Planet APIs on their behalf.
33+
34+
See [OAuth2 Client Registration](http://docs.planet.com/develop/authentication/#interactive-client-registration)
35+
for more information.
36+
37+
### With a Local Web Browser
38+
In environments where a local browser is available, the Planet SDK library can manage
39+
the process of launching the browser locally, transferring control to the Planet
40+
authorization services for session initialization, and accepting a network
41+
callback from the local browser to regain control once the authorization
42+
process is complete. At a network protocol level, this establishes the user
43+
login session using the OAuth2 authorization code flow.
44+
45+
To use this method using the SDK, the following requirements must be met:
46+
47+
* The application must be able to launch a local web browser.
48+
* The web browser must be able to connect to Planet services.
49+
* The application must be able to listen on a network port that is accessible
50+
to the browser.
51+
52+
#### Examples - OAuth2 Authorization Code Flow
53+
54+
##### In Memory Session State
55+
When an application cannot safely store user session state, it may operate purely in memory. When this
56+
method is used, the user will be prompted to complete the login process each time the application is run.
57+
58+
```python linenums="1" title="Login as a user using a local browser with in memory only state persistance"
59+
{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py' %}
60+
```
61+
62+
##### Session State Shared with CLI
63+
Applications may save their session state in a way that is shared with the CLI. With saved state,
64+
the user will only be prompted to complete the login process once.
65+
```python linenums="1" title="Login as a user using a local browser with sessions persisted on disk and shared with the CLI"
66+
{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py' %}
67+
```
68+
69+
##### Session State Saved to Application Storage
70+
Applications may save their session state to application provided storage. With saved state,
71+
the user should only be prompted to complete the login process once. Using application provided storage
72+
will result in the session state not being shared with the CLI.
73+
74+
Applications needing to use their own storage will do so by providing
75+
the `Auth` layer in the SDK with a custom implementation of the
76+
[`planet_auth.ObjectStorageProvider`](https://planet-auth.readthedocs.io/en/latest/api-planet-auth/#planet_auth.ObjectStorageProvider)
77+
abstract base class. See examples below for more details.
78+
79+
```python linenums="1" title="Login as a user using a local browser with sessions persisted to application provided storage"
80+
{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py' %}
81+
```
82+
83+
### Without a Local Web Browser
84+
In environments where a local web browser is not available, additional steps must
85+
be taken by the application author to initialize the user session.
86+
For example, a remote shell to a cloud environment is not likely
87+
to be able to open a browser on the user's desktop or receive network callbacks
88+
from the user's desktop browser. In these cases, a browser is
89+
still required. To complete login in such a case, the SDK will generate a URL and a
90+
verification code that must be presented to the user. The user must visit the
91+
URL out of band to complete the login process while the application polls for
92+
the completion of the login process using the SDK. At a network protocol
93+
level, this establishes the user login session using the OAuth2 device
94+
code flow.
95+
96+
To use this method using the SDK, the following requirements must be met:
97+
98+
* The application must be able to connect to Planet services.
99+
* The application must be able to display instructions to the user, directing
100+
them to a web location to complete login.
101+
102+
As above, this may be done with state only persisted in memory, with state
103+
shared with the CLI, or with state saved to application provided storage.
104+
105+
#### Examples - OAuth2 Device Code Flow
106+
107+
##### In Memory Session State
108+
```python linenums="1" title="Login as a user using an external browser with in memory only state persistance"
109+
{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py' %}
110+
```
111+
112+
##### Session State Shared with CLI
113+
```python linenums="1" title="Login as a user using an external browser with sessions persisted on disk and shared with the CLI"
114+
{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py' %}
115+
```
116+
117+
##### Session State Saved to Application Storage
118+
```python linenums="1" title="Login as a user using an external browser with sessions persisted to application provided storage"
119+
{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py' %}
120+
```
121+
122+
## OAuth2 Session for Service Accounts
123+
Service account session initialization is simpler than user session
124+
initialization, and does not require a web browser.
125+
126+
While preserving session state for user sessions was a concern driven
127+
in part by a concern for the user experience of using a web browser for
128+
initialization, for service accounts it remains a concern to avoid
129+
throttling by the authorization service.
130+
131+
If applications are expected to run longer than the life of an access token
132+
(a few hours), then in memory operations are acceptable (for example: a long-running
133+
data processing job). If application lifespan is short and frequent,
134+
then the application should take steps to persist the session state (for
135+
example: a command line utility run repeatedly from a shell with a short lifespan).
136+
137+
Like the session state itself, service account initialization parameters are
138+
sensitive, and it is the responsibility of the application to store them
139+
securely.
140+
141+
At a network protocol level, OAuth2 service account sessions are implemented
142+
using the OAuth2 authorization code flow. This carries with it some additional
143+
security concerns, discussed in
144+
[RFC 6819 §4.4.4](https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.4).
145+
Because of these considerations, service accounts should only be used for
146+
workflows that are independent of a controlling user.
147+
148+
As above, this may be done with state only persisted in memory, with state
149+
shared with the CLI, or with state saved to application provided storage.
150+
151+
### OAuth2 M2M Client Registration
152+
Service accounts are managed under the
153+
**OAuth Clients** panel on the [Planet Insights Account](https://insights.planet.com/account/#/) page.
154+
155+
See [Sentinel Hub Authentication](https://docs.sentinel-hub.com/api/latest/api/overview/authentication/) for further information.
156+
157+
### Examples - OAuth2 Client Credentials Flow
158+
159+
#### In Memory Session State
160+
```python linenums="1" title="Access APIs using a service account with in memory only state persistance"
161+
{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py' %}
162+
```
163+
164+
#### Session State Shared with CLI
165+
```python linenums="1" title="Access APIs using a service account with sessions persisted on disk and shared with the CLI"
166+
{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py' %}
167+
```
168+
169+
#### Session State Saved to Application Storage
170+
```python linenums="1" title="Access APIs using a service account with sessions persisted to application provided storage"
171+
{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py' %}
172+
```
173+
174+
----

‎docs/auth/auth-dev-cli-managed.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# CLI Managed Sessions
2+
For simple programs and scripts, it is easiest for the program to defer
3+
session management to the [`planet auth`](../../cli/cli-reference/#auth)
4+
CLI. This method will store session information in the user's home directory
5+
in the `~/.planet.json` file and `~/.planet/` directory. The Python SDK will
6+
use the information saved in these locations to make API calls.
7+
8+
When this approach is taken, the authentication session will be shared between
9+
actions taken by the `planet` utility and those taken by programs built
10+
using the SDK. Changes made by one will impact the behavior of the other.
11+
12+
CLI managed sessions can be used for all authentication protocols supported
13+
by the SDK library.
14+
15+
**Requirements and Limitations:**
16+
17+
* The program must have read and write access to the user's home directory.
18+
* This method requires that the end-user has access to and understands
19+
the [`planet`](../../cli/cli-reference) CLI command needed to manage
20+
authentication.
21+
* This approach should not be used on public terminals or in cases where the
22+
user's home directory cannot be kept confidential.
23+
24+
## Initialize Session - CLI Login
25+
Session login can be performed using the following command. This command can
26+
be used to initialize sessions using any of the supported authentication methods,
27+
and will default to creating an OAuth2 user session.
28+
Refer to the command's `--help` for more information.
29+
30+
<a name="planet-auth-login"></a>
31+
```shell title="Initialize session using planet CLI."
32+
planet auth login
33+
```
34+
35+
A particular configuration may be selected by using the `--auth-profile` option.
36+
`planet-user` is the default, but may be [overridden](../auth-sdk/#configuration)
37+
by the runtime environment.
38+
39+
<a name="planet-auth-login-planet-user"></a>
40+
```shell title="Initialize session using planet CLI, forcing the built-in user interactive OAuth2 login flow."
41+
planet auth login --auth-profile planet-user
42+
```
43+
44+
<a name="planet-auth-login-planet-m2m"></a>
45+
```shell title="Initialize session using planet CLI, forcing the use of the specified service principal."
46+
planet auth login --auth-client-id <your-client-id> --auth-client-secret <your-client-secret>
47+
```
48+
49+
<a name="planet-auth-login-planet-apikey"></a>
50+
```shell title="Initialize session using planet CLI, forcing the use of a legacy Planet API key."
51+
planet auth login --auth-api-key <your-api-key>
52+
```
53+
54+
## Using Saved Session
55+
Using a CLI managed session is the default behavior for SDK functions.
56+
Developing an application that uses a CLI managed session requires no additional
57+
action by the developer. When a developer chooses to create an application
58+
that behaves in this way, it will most often be done implicitly by relying
59+
on SDK default behavior, but it may also be done explicitly.
60+
61+
### CLI Selected Session
62+
The default behavior of the SDK is to defer which session is loaded to CLI.
63+
64+
<a name="use-cli-session-implicit"></a>
65+
```python linenums="1" title="Implicitly use CLI managed login sessions, deferring session selection to the user and the CLI."
66+
{% include 'auth-session-management/cli_managed_auth_state__implicit.py' %}
67+
```
68+
<a name="use-cli-session-explicit"></a>
69+
```python linenums="1" title="Explicitly use CLI managed login sessions, deferring session selection to the user and the CLI."
70+
{% include 'auth-session-management/cli_managed_auth_state__explicit.py' %}
71+
```
72+
73+
### Application Selected Session
74+
Applications may be developed to always select a specific CLI managed profile.
75+
This may be useful in cases where an application wishes to guide the user
76+
experience towards expecting an auth session that is separate from the default
77+
sessions used by the CLI.
78+
79+
In cases where the application has access to the
80+
user's home directory and saved sessions, forcing the use of a particular
81+
profile circumvents the user's CLI managed preferences.
82+
83+
<a name="use-cli-session-force-custom"></a>
84+
Note: This first example does not create the session `my-app-profile`.
85+
This must be created either through a separate code path as show in
86+
the [Application Managed Sessions](../auth-dev-app-managed-oauth) guide,
87+
or by using a CLI command to copy an existing profile such as
88+
`planet auth profile copy planet-user my-app-profile`.
89+
90+
```python linenums="1" title="Use a specific session that is shared with the CLI."
91+
{% include 'auth-session-management/cli_managed_auth_state__specific_auth_profile.py' %}
92+
```
93+
94+
<a name="use-cli-session-force-builtin"></a>
95+
It is also possible to force the use of the SDK's built-in OAuth2 application ID
96+
for interactive user applications. This capability is provided for developer
97+
convenience, primarily for smaller programs and scripts. Larger applications
98+
developed for multiple users should
99+
[register](../auth-dev-app-managed-oauth/#oauth2-user-client-registration)
100+
a unique application ID.
101+
102+
This second example also initiates a login and does not save session state to storage.
103+
This means this example does not depend on the CLI, and may be considered a simple
104+
example of an [Application Managed Session](../auth-dev-app-managed-oauth).
105+
106+
```python linenums="1" title="Use the Planet SDK with an OAuth2 user session initialized by the application and utilizing the SDK's built-in OAuth2 application ID."
107+
{% include 'auth-session-management/app_managed_auth_state__using_sdk_app_id.py' %}
108+
```
109+
110+
---

0 commit comments

Comments
 (0)