Document machine-to-machine auth options in openeo

APIs/openEO/Python_Client/Python.qmd

@@ -136,34 +136,18 @@ just like this:
 connection.authenticate_oidc()
 ```
 
--   By default, the first time you call this `authenticate_oidc()` method,
-    a URL will be printed. Something like for example:
+-   By default, the first time `authenticate_oidc()` is called,
+    instructions to visit a certain URL will be printed, e.g.:
 
     ```
-    Visit https://auth.example.com/device?user_code=EAXD-RQXV to authenticate.
+    Visit https://auth.example/?user_code=EAXD-RQXV to authenticate.
     ```
 
-    Visit this URL (click it or copy-paste it into your web browser)
-    and follow the login flow using your Copernicus Data Space Ecosystem credentials.
-
-    ::: {.callout-tip collapse="true"}
-
-    You can visit this URL with any browser you prefer to complete the login procedure
-    (e.g. on your laptop or smartphone). 
-    It does *not* have to be a browser running on the same machine/network as your Python script/application.
-
-    :::
-
-    Once the authentication is completed, your Python script will receive 
-    the necessary authentication tokens and print 
-
-    ```
-    Authorized successfully.
-    ```
+    Visit this URL and follow the login flow
+    using your Copernicus Data Space Ecosystem credentials.
 
 -   Other times, when you still have valid (refresh) tokens on your system,
-    it will not be necessary to go through the Copernicus Data Space Ecosystem login steps
-    and you will immediately see
+    the manual login process is skipped and you will immediately see
 
     ```
     Authenticated using refresh token.
@@ -172,8 +156,9 @@ connection.authenticate_oidc()
 In any case, your `connection` is now authenticated and capable to make download/processing requests.
 
 
-A more in-depth discussion of various authentication concepts is available
-in the [openEO Python client documentation](https://open-eo.github.io/openeo-python-client/auth.html){target="_blank"}.
+Find more in-depth information on authentication
+[here](../authentication.qmd) 
+or in the [openEO Python client documentation](https://open-eo.github.io/openeo-python-client/auth.html){target="_blank"}.
 
 
 ## Working with Datacube

APIs/openEO/authentication.qmd

@@ -0,0 +1,198 @@
+---
+title: "Authentication in openEO"
+---
+
+While basic discovery of openEO collections and processes is possible without authentication, executing openEO workflows requires user authentication. This is necessary to manage user quotas, resources, and credit consumption effectively. User authentication in openEO is handled with the OpenID Connect protocol (often abbreviated as "OIDC").
+
+The openEO endpoint of the Copernicus Data Space Ecosystem is configured to use the identity provider service of the Copernicus Data Space Ecosystem. It is therefore recommended to complete the [Copernicus Data Space Ecosystem registration](../../Registration.qmd) before attempting to authenticate with openEO.
+
+
+
+
+## Getting Started: A Typical openEO Authentication Flow With The openEO Python Client Library {#sec-typical-authentication-flow}
+
+A typical Copernicus Data Space Ecosystem openEO workflow,
+using the openEO Python client library,
+starts with setting up a connection like this:
+
+```python
+import openeo
+
+connection = openeo.connect(url="openeo.dataspace.copernicus.eu")
+connection.authenticate_oidc()
+```
+
+After connecting to the Copernicus Data Space Ecosystem openEO endpoint,
+[`Connection.authenticate_oidc()`](https://open-eo.github.io/openeo-python-client/api.html#openeo.rest.connection.Connection.authenticate_oidc){target="_blank"} initiates the OpenID Connect authentication flow:
+
+-   By default, the first time `authenticate_oidc()` is called,
+    instructions to visit a certain URL will be printed, e.g.:
+
+    ```
+    Visit https://auth.example/?user_code=EAXD-RQXV to authenticate.
+    ```
+
+    Visit this URL (click or copy-paste it into a web browser) and follow the login flow using Copernicus Data Space Ecosystem credentials.
+
+    ::: {.callout-tip collapse="false"}
+
+    Visit this URL using any preferred browser to complete the login procedure (e.g., on a laptop or smartphone). It does *not* need to be a browser on the same machine or network as the Python script/application.
+
+    :::
+
+    Once authentication is complete, the Python script will receive the necessary authentication tokens and print
+
+    ```
+    Authorized successfully.
+    ```
+
+-   Other times, when valid (refresh) tokens are still present on the system, the openEO Python client library will automatically use these tokens and bypass the manual login process. The following will be visible immediately:
+
+    ```
+    Authenticated using refresh token.
+    ```
+
+In any case, `connection` is now authenticated and ready to make download or processing requests.
+
+
+## Alternative Authentication Methods
+
+The [openEO Python client library documentation](https://open-eo.github.io/openeo-python-client/auth.html){target="_blank"}
+has a more in-depth information of various authentication concepts,
+and discusses alternative authentication methods.
+
+
+## Non-interactive And Machine-to-Machine Authentication with the openEO Python client library
+
+@sec-typical-authentication-flow describes the typical authentication flow for interactive use cases,
+e.g. when working in a Jupyter Notebook or manually running a script on a local machine.
+This section will discuss authentication approaches
+that are more fitting for *non-interactive* and *machine-to-machine* use cases.
+The practical aspects will be based on the openEO Python client library,
+but the concepts are also generally applicable to other openEO client libraries.
+
+
+### Refresh Tokens
+
+Refresh tokens are long-lived tokens (order of weeks or months)
+that can be used to obtain new access tokens
+without the need for the user to re-authenticate.
+
+As mentioned in @sec-typical-authentication-flow,
+[`Connection.authenticate_oidc()`](https://open-eo.github.io/openeo-python-client/api.html#openeo.rest.connection.Connection.authenticate_oidc){target="_blank"}
+will require user to go through an interactive login flow in a browser,
+when there is no (valid) refresh token available.
+But when the openEO Python client library can find a valid refresh token on this system,
+this will be a non-interactive operation.
+This makes it a viable option for non-interactive and machine-to-machine authentication,
+if it is feasible to produce a new refresh token once in a while using an interactive login flow.
+
+To get this working, there are basically two aspects to cover
+(both of which have built-in support in the openEO Python client library):
+
+1.  Obtain and store a new refresh token.
+
+    There are several authentication methods on the `Connection` object
+    (e.g. the often used `authenticate_oidc()` method)
+    and most these have an option `store_refresh_token`
+    to enable storing of the refresh token obtained during the authentication process.
+    Note that this is enabled by default in `authenticate_oidc()`,
+    but not in `authenticate_oidc_device()`.
+
+    The refresh token is stored in a private JSON file, by default, in a folder within the personal data directory (typically determined by environment variables such as `XDG_DATA_HOME` on Linux or `APPDATA` on Windows). The folder can also be configured directly using the `OPENEO_CONFIG_HOME` environment variable.
+    The actual location can be verified
+    with the [`openeo-auth` command line tool](https://open-eo.github.io/openeo-python-client/auth.html#auth-config-files-and-openeo-auth-helper-tool){target="_blank"}.
+
+
+2.  Load and use the refresh token
+
+    When a valid refresh token is stored in a location accessible to the openEO Python client library, the user can authenticate directly with:
+
+    ```python
+    connection.authenticate_oidc_refresh_token()
+    ```
+
+    Alternatively:
+
+    -   If a user wants to keep the logic generic, the following can also be used
+
+        ```python
+        connection.authenticate_oidc()
+        ```
+
+        This method will first try to use a refresh token if available,
+        and fall back on other methods (e.g. device code flow) otherwise.
+
+    -   If a user manages the storage and loading of the refresh token, it can be explicitly passed:
+
+        ```python
+        connection.authenticate_oidc_refresh_token(
+            refresh_token=your_refresh_token,
+        )
+        ```
+
+::: {.callout-tip}
+## Advanced refresh token storage
+
+For advanced use cases, it is also possible to override the file-based
+refresh token storage with a custom implementation through the
+`refresh_token_store` parameter of
+[`Connection`](https://open-eo.github.io/openeo-python-client/api.html#openeo.rest.connection.Connection){target="_blank"}.
+
+:::
+
+
+
+### Client Credentials Flow
+
+
+OpenID Connect also supports the so-called "client credentials flow",
+which is a non-interactive flow, based on a client id and a secret,
+that is suitable for machine-to-machine authentication.
+
+The openEO Python client library has built-in support for this flow,
+with the ['authenticate_oidc_client_credentials()` method](https://open-eo.github.io/openeo-python-client/auth.html#oidc-authentication-client-credentials-flow){target="_blank"}:
+
+```python
+connection.authenticate_oidc_client_credentials(
+    client_id=...,
+    client_secret=...,  # Note: Do not hard-code your secret here!
+)
+```
+
+#### Obtaining Client Credentials
+
+::: {.callout-warning}
+The use of client credentials in openEO is an experimental feature. It is not widely supported across openEO backends, and the setup procedure is not yet fully standardized or streamlined.
+:::
+
+The Sentinel Hub service in the Copernicus Data Space Ecosystem
+has a [dashboard web app](https://shapps.dataspace.copernicus.eu/dashboard)
+and under the account settings there is a self-service feature to
+[register your own OAuth client](../SentinelHub/Overview/Authentication.qmd#registering-oauth-client){target="_blank"}.
+The client id and client secret obtain here can also be used
+for the client credentials flow with the openEO service of Copernicus Data Space Ecosystem.
+
+#### Caveats And Considerations
+
+-   Treat the client secret securely, like a password.
+    Take extra care to not leak it accidentally.
+    For example, the simplicity of the `authenticate_oidc_client_credentials()` example snippet above, might be tempting to hard-code the client secret in scripts or notebooks, potentially leading to its permanent storage in version control repositories.
+
+    Instead, read the client secret from a secure location
+    (e.g. a private file outside the reach of the version control repositories),
+    or leverage environment variables (e.g as directly [supported by the openEO Python client library](https://open-eo.github.io/openeo-python-client/auth.html#oidc-client-credentials-using-environment-variables){target="_blank"}).
+-   The client credentials only identify OAuth client, not a personal user account.
+
+    -   This means that openEO resources such as openEO batch jobs, their results, UDP's, etc
+        from one identity are not available to the other.
+        For example, batch jobs created with client credentials cannot be listed when using a personal account.
+    -   Likewise, the balances of processing credits are separate.
+        However, it is possible to link the balance of the client credentials account to a personal account. To enable this, contact support and provide the client ID and user ID.
+
+-   The client credentials flow is not supported on the
+    [Copernicus Data Space Ecosystem openEO web editor](https://openeo.dataspace.copernicus.eu/).
+    As mentioned above, this practically means that tracking the progress and status of batch jobs created with client credentials is not possible.
+    However, it is still possible to approximate the batch job overview of the web editor with a Jupyter Notebook using the openEO Python client library.
+
+

_quarto.yml

@@ -118,6 +118,8 @@ website:
               text: openEO Processes
             - href: "APIs/openEO/File_formats.qmd"
               text: File Formats
+            - href: "APIs/openEO/authentication.qmd"
+              text: Authentication
             - href: "https://open-eo.github.io/openeo-python-client"
               text: Python documentation
               target: "_blank"