Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More consistent usage of "back-end" (instead of "backend") in couple of places #51

Merged
merged 1 commit into from
Aug 19, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions documentation/1.0/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ While a couple of openEO operations can be done anonymously, most of the interes

## HTTP Basic

Let's start with the easiest authentication method, based on the HTTP Basic authentication scheme. It is however *not recommended* for various reasons, such as its limited *security* measures. For example, if you are connecting to a backend with a `http://` URL (unencrypted; discouraged in openEO) instead of a `https://` one (encrypted), you should certainly not use HTTP Basic authentication.
Let's start with the easiest authentication method, based on the HTTP Basic authentication scheme. It is however *not recommended* for various reasons, such as its limited *security* measures. For example, if you are connecting to a back-end with a `http://` URL (unencrypted; discouraged in openEO) instead of a `https://` one (encrypted), you should certainly not use HTTP Basic authentication.

With these security related caveats out of the way, you authenticate using your username and password. The clients usually have a `authenticate_basic` method for this or graphical clients (e.g. QGIS and the Web Editor) will ask for your username and password directly.

Expand All @@ -25,17 +25,17 @@ OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol. It
- There is **decoupling** between:

- the *OpenID Connect identity provider* (the platform that handles the authentication of the user)
- the *openEO backend*, which manages earth observation collections and executes your algorithms
- the *openEO back-end*, which manages earth observation collections and executes your algorithms

openEO Backends can decide to host their own OpenID Connect infrastructure, but they may also allow to authenticate with an external OpenID Connect provider, which could be an organization like Google or Microsoft. This means that the backend does not have to take care of all the security and privacy challenges of properly handling user registration, authentication, etc. Also, it allows the user to securely reuse an existing account registered with an established organization, instead of having to register yet another account with some web service.
openEO back-ends can decide to host their own OpenID Connect infrastructure, but they may also allow to authenticate with an external OpenID Connect provider, which could be an organization like Google or Microsoft. This means that the back-end does not have to take care of all the security and privacy challenges of properly handling user registration, authentication, etc. Also, it allows the user to securely reuse an existing account registered with an established organization, instead of having to register yet another account with some web service.

::: tip Note
An openEO backend might support **multiple OpenID Connect providers**. If there is only one, the openEO client libraries will usually pick it automatically, but otherwise you may need to decide explicitly which provider to authenticate against.
An openEO back-end might support **multiple OpenID Connect providers**. If there is only one, the openEO client libraries will usually pick it automatically, but otherwise you may need to decide explicitly which provider to authenticate against.
:::

- Your openEO script or application acts as a so called **OpenID Connect client**, with an associated **client ID**. This practically means that, apart from a user account, you need a client ID as well (and often a client secret too) when authenticating.

The details of how to obtain the client ID and secret largely depend on the backend and OpenID Connect provider: you might have to register a client yourself, or you might have to use an existing client ID. Consult the openEO backend (documentation) about how to obtain client ID (and secret).
The details of how to obtain the client ID and secret largely depend on the back-end and OpenID Connect provider: you might have to register a client yourself, or you might have to use an existing client ID. Consult the openEO back-end (documentation) about how to obtain client ID (and secret).

- There are several possible "**flows**" (also called "grants") to complete the whole OpenID Connect authentication dance:

Expand Down Expand Up @@ -65,7 +65,7 @@ This is the most popular and widely supported OpenID Connect flow in the general
- The web browser has (network) access
- A URL must be whitelisted in the OpenID client's "redirect URL" configuration at the OpenID Connect provider's side.

For authentication, the client forwards a user to the log-in page of the OpenID Connect provider. There. the user can log in there with an existing account (or create a new one) and then generally has to explicitly grant access to basic profile information (e.g. email address) that the backend will use to identify the user.
For authentication, the client forwards a user to the log-in page of the OpenID Connect provider. There. the user can log in there with an existing account (or create a new one) and then generally has to explicitly grant access to basic profile information (e.g. email address) that the back-end will use to identify the user.

### Device Flow

Expand All @@ -78,13 +78,13 @@ The "magic" is that the client will show a message like this:
To authenticate: visit https://provider.example.com/device
and enter the user code 'DTNY-KLNX'.

You should now visit this URL. Usually it is intentionally a short URL to make it feasible to type it instead of copy-pasting it (e.g. on another device). Authenticate with the OpenID Connect provider and enter the user code shown in the message. Meanwhile, the client library is usually actively polling the OpenID Connect provider and when you successfully complete the authentication and entering of the user code, it will receive the necessary tokens for authenticated communication with the backend.
You should now visit this URL. Usually it is intentionally a short URL to make it feasible to type it instead of copy-pasting it (e.g. on another device). Authenticate with the OpenID Connect provider and enter the user code shown in the message. Meanwhile, the client library is usually actively polling the OpenID Connect provider and when you successfully complete the authentication and entering of the user code, it will receive the necessary tokens for authenticated communication with the back-end.

### Client Credentials Flow

The Client Credentials flow directly uses the client ID and secret to authenticate. It does not involve interactive authentication through a web browser, which makes it useful for **non-interactive use cases**.

The downside is of the Client Credentials flow is that it can be challenging or even impossible with a given OpenID Connect provider, to set up a client that supports this. Also, your openEO backend might not allow it, because technically you are authenticating a *client*, and not a *user*.
The downside is of the Client Credentials flow is that it can be challenging or even impossible with a given OpenID Connect provider, to set up a client that supports this. Also, your openEO back-end might not allow it, because technically you are authenticating a *client*, and not a *user*.

### Resource Owner Password flow

Expand All @@ -94,6 +94,6 @@ However, usage of the Resource Owner Password flow is **generally discouraged**

### Refresh Token Flow

When OpenID Connect authentication completes successfully, the client receives an access token to be used when doing authenticated calls to the backend. The access token usually has a short lifetime to reduce the security risk when it would be stolen or intercepted. The client also receives a *refresh token* that can be used, through the Refresh Token flow, to easily request a new access token, without having to re-authenticate, which makes it useful for **non-interactive uses cases**.
When OpenID Connect authentication completes successfully, the client receives an access token to be used when doing authenticated calls to the back-end. The access token usually has a short lifetime to reduce the security risk when it would be stolen or intercepted. The client also receives a *refresh token* that can be used, through the Refresh Token flow, to easily request a new access token, without having to re-authenticate, which makes it useful for **non-interactive uses cases**.

However, as it needs an existing refresh token, the Refresh Token Flow requires **first to authenticate with one of the other flows** (but in practice it might not be required very often because refresh tokens usually have a relatively long lifetime).
4 changes: 2 additions & 2 deletions documentation/1.0/developers/backends/opendatacube.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ First of all, you should read carefully the [getting started guide for service p
The Open Data Cube implementation for openEO is not a full-fledged out-of-the-box openEO back-end,
but can be part of the infrastructure for the data management part.
In detail it can be used as data source for [EO Data Discovery](apireference.md#tag/EO-Data-Discovery) and e.g.
in combination with a dask cluster as processing backend for [Data Processing](apireference.md#tag/Data-Processing).
in combination with a dask cluster as processing back-end for [Data Processing](apireference.md#tag/Data-Processing).
In any case, a [HTTP REST interface must be available in front of ODC to properly answer openEO requests](#http-rest-interface).
:::

Expand All @@ -23,7 +23,7 @@ There are three main components involved with ODC and openEO:
* Repository: [openeo-pg-parser-python](https://github.com/Open-EO/openeo-pg-parser-python)

The process graph parser translates a process graph in json / dict format into a traversable python object. It
automatically validates that only collections and processes are used which are available at the backend.
automatically validates that only collections and processes are used which are available at the back-end.

For example, this [EVI process graph](https://github.com/Open-EO/openeo-odc/blob/master/tests/process_graphs/evi.json) can be
translated using the openEO Process Graph Parser in the following way:
Expand Down
2 changes: 1 addition & 1 deletion documentation/1.0/udfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ The abbreviation **UDF** stands for **user-defined function**. With this concept
You can run UDFs with any client (including JavaScript and Web Editor), but the code you can execute on the server will be limited to Python and R.
All openEO clients allow to run UDFs via the pre-defined process [`run_udf`](processes.md#run_udf) if the back-end implements UDFs. You can check the [openEO Hub](https://hub.openeo.org) for back-ends that support user-defined functions. There's also [`run_udf_externally`](processes.md#run_udf_externally) if you want to host UDFs yourself (see back-end instructions below), but the process is still experimental and not widely supported yet. If we refer to `run_udf` below and the back-end supports it, you can also use `run_udf_externally` without it being explicitly mentioned.

As data cubes can be very large, the backend may only be able to run your code on a smaller chunk of the whole cube. So you need to help the server a bit, by designing your code to work on smaller piece of data. This can be done by using data cube processes that run the UDF on smaller chunks of the data. There are a number of pre-defined processes that can run UDFs on such chunks, for example:
As data cubes can be very large, the back-end may only be able to run your code on a smaller chunk of the whole cube. So you need to help the server a bit, by designing your code to work on smaller piece of data. This can be done by using data cube processes that run the UDF on smaller chunks of the data. There are a number of pre-defined processes that can run UDFs on such chunks, for example:

* [`aggregate_spatial`](processes.md#aggregate_spatial): Reduces pixels withing geometries to a single value using an UDF
* [`apply`](processes.md#apply): Applies an UDF to each pixel (it might also be slow to make the chunks too small though)
Expand Down