Skip to content

Latest commit

 

History

History
107 lines (82 loc) · 5.44 KB

README.md

File metadata and controls

107 lines (82 loc) · 5.44 KB

terra-stac-api

Architecture of terra-stac-api

Configuration

The application can be configured via environment variables. Here is an overview of the most important settings:

Environment variable Description Default value
ES_HOST Elasticsearch host
ES_PORT Elasticsearch port
ES_USE_SSL Use SSL to connect to Elasticsearch true
ES_VERIFY_CERTS Verify certificates for Elasticsearch true
CURL_CA_BUNDLE CA certificates for Elasticsearch
STAC_COLLECTIONS_INDEX Collection index in Elasticsearch collections
STAC_ITEMS_INDEX_PREFIX Prefix for Item indices in Elasticsearch items_
OIDC_ISSUER OIDC token issuer. When not provided, auth integration will be disabled.
OIDC_ROLES_CLAIM Token claim from which the user roles are read realm_access.roles
ROLE_ADMIN Role for admin users stac-admin
ROLE_EDITOR Role for editors stac-editor
EDITOR_PUBLIC_COLLECTIONS Indicates whether editors can create public collections false

Dependencies

The terra-stac-api application relies on a OpenSearch / Elasticsearch database to store the STAC Collections and Items. The necessary indices will be created automatically by the application on application start-up (collections index) or when creating new collections (item index).

Important

If you want to run multiple instances of the terra-stac-api with same OpenSearch / Elasticsearch instance, make sure to properly configure the STAC_COLLECTIONS_INDEX and STAC_ITEMS_INDEX_PREFIX to be unique and prefix-free.

Authorization integration

The application supports authorization via the use of OpenID Connect (OIDC) access tokens. The access token should be sent as a Bearer token in the Authorization header of a HTTP request. The roles of a user are read from the $.realm_access.roles property in the access token. Users can be assigned to a role in the authorization server (eg. Keycloak). Specific permissions can be configured based on these roles.

Application-level authorization

On the application-level, there are two important roles: admin and editor. The specific names of these roles (how they appear in the access tokens) can be defined via environment variables.

Role Environment variable Description
Admin ROLE_ADMIN All CRUD operations on all collections. Create public collections.
Editor ROLE_EDITOR Create non-public collections. Allowed to create public collections when the EDITOR_PUBLIC_COLLECTIONS feature flag is enabled

Collection-level authorization

Specific authorizations on the collection-level can be configured in the STAC collection document. You can grant read and write access to specific roles with the _auth field. A special 'role' is dedicated to unauthenticated users: anonymous. Only users with role $ROLE_ADMIN can create collections open to the public. For example:

{
    "_auth": {
        "read": [
            "anonymous"
        ],
        "write": [
            "stac-admin",
            "stac-editor"
        ]
    }
}

If you don't want to store the collection authorizations in your (local) STAC document, you can also send these details as HTTP query parameters when creating the collection. These parameters are _auth_read and _auth_write. Multiple roles can be provided by specifying the query parameter multiple times.

POST /collections?_auth_read=anonymous&_auth_write=stac-admin&_auth_write=stac-editor

Development

To start developing on this project, you should install all needed dependencies for running and testing the code:

$ pip install -e .[dev]

This will also install linting and formatting tools, which are automatically executed when you commit using Git. To set up pre-commit as a Git hook, run

$ pre-commit install

Testing

Running the tests requires an active Elasticsearch cluster. By default, it will look for an Elasticsearch cluster on the local host, port 9200.

In the Jenkins pipeline, we will run an Elasticsearch process in the test container. If you want to run the tests locally, you can use the Docker compose file elasticsearch/docker-compose.yml.