allow custom cors headers for stac (#599)

## Overview

- Allow each service to specify values for `Access-Control-Allow-Origin`

Previously, if a `location` block in the `nginx` configuration for a
given service included the cors helper
configuration (with `include /etc/nginx/conf.d/cors.include;`) then all
origins were allowed by default.

This was done by setting the header `Access-Control-Allow-Origin: *`
which works well but is a bit too permissive
  since it allowed __all__ origins.

This change introduces a mechanism to specify specific additional
allowed origins by setting the
`$access_control_allow_origin` nginx variable in the `location` block
before including the `cors.include` file.

  For example:

  ```
  set $access_control_allow_origin http://example.com;
  include /etc/nginx/conf.d/cors.include;
  ```

will set the value of the `Access-Control-Allow-Origin` response header
to `http://example.com`.

By default, the header value will be `*` if
`$access_control_allow_origin` is not set (to maintain backwards
  compatibility).

To specify multiple allowed origins, use a `map` directive (see the
implementation for `components/stac` for an
  example).

- Set allowed CORS origins for `stac` through an environment variable

This change implements this flexibility for the `components/stac`
component. By setting the `STAC_CORS_ORIGINS`
variable a user can specify allowed origins for responses from the
`components/stac` component.

  For example, setting the following:
  
  ```
export STAC_CORS_ORIGINS='https://example.com
~^https?://(www\.)?other\.example\.com$'
  ```

then requests from https://example.com and http://other.example.com will
get a response with the
`Access-Control-Allow-Origin header` set to their origin, but
http://example.ca will not.

Note that this breaks backwards compatibility slightly since previously
all origins were allowed for `/stac` by
  default. To keep the backwards compatible behaviour you can set:

  ```
  export STAC_CORS_ORIGINS='~.*' 
  ```

  to match all origins.

## Changes

**Non-breaking changes**
- Adds mechanism to allow services to have more control over CORS
headers

**Breaking changes**
- responses from `/stac` no longer set `Access-Control-Allow-Origin: *`
by default

## Related Issue / Discussion

- As discussed in #450

## Additional Information

## CI Operations

<!--
The test suite can be run using a different DACCS config with
``birdhouse_daccs_configs_branch: branch_name`` in the PR description.
To globally skip the test suite regardless of the commit message use
``birdhouse_skip_ci`` set to ``true`` in the PR description.

Using ``[<cmd>]`` (with the brackets) where ``<cmd> = skip ci`` in the
commit message will override ``birdhouse_skip_ci`` from the PR
description.
Such commit command can be used to override the PR description behavior
for a specific commit update.
However, a commit message cannot 'force run' a PR which the description
turns off the CI.
To run the CI, the PR should instead be updated with a ``true`` value,
and a running message can be posted in following PR comments to trigger
tests once again.
-->

birdhouse_daccs_configs_branch: master
birdhouse_skip_ci: false

Author: mishaschwartz

.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "2.18.9"
+current_version = "2.18.10"
 commit = true
 tag = false
 tag_name = "{new_version}"

CHANGES.md

@@ -17,6 +17,58 @@
 
 [//]: # (list changes here, using '-' for each new entry, remove this when items are added)
 
+[2.18.10](https://github.com/bird-house/birdhouse-deploy/tree/2.18.10) (2025-11-12)
+------------------------------------------------------------------------------------------------------------------
+
+## Changes
+
+- Allow each service to specify values for `Access-Control-Allow-Origin`
+
+  Previously, if a `location` block in the `nginx` configuration for a given service included the cors helper
+  configuration (with `include /etc/nginx/conf.d/cors.include;`) then all origins were allowed by default.
+
+  This was done by setting the header `Access-Control-Allow-Origin: *` which works well but is a bit too permissive
+  since it allowed __all__ origins.
+
+  This change introduces a mechanism to specify specific additional allowed origins by setting the 
+  `$access_control_allow_origin` nginx variable in the `location` block before including the `cors.include` file.
+
+  For example:
+
+  ```shell
+  set $access_control_allow_origin http://example.com;
+  include /etc/nginx/conf.d/cors.include;
+  ```
+
+  will set the value of the `Access-Control-Allow-Origin` response header to `http://example.com`.
+
+  By default, the header value will be `*` if `$access_control_allow_origin` is not set (to maintain backwards
+  compatibility).
+
+  To specify multiple allowed origins, use a `map` directive (see the implementation for `components/stac` for an
+  example).
+
+- Set allowed CORS origins for `stac` through an environment variable
+
+  This change implements this flexibility for the `components/stac` component. By setting the `STAC_CORS_ORIGINS`
+  variable a user can specify allowed origins for responses from the `components/stac` component.
+
+  For example, setting the following:
+  
+  ```shell
+  export STAC_CORS_ORIGINS='https://example.com ~^https?://(www\.)?other\.example\.com$' 
+  ```
+
+  then requests from https://example.com and http://other.example.com will get a response with the 
+  `Access-Control-Allow-Origin header` set to their origin, but http://example.ca will not.
+
+  Note that this breaks backwards compatibility slightly since previously all origins were allowed for `/stac` by
+  default. To match all origins and keep the backwards compatible behaviour you can set:
+
+  ```shell
+  export STAC_CORS_ORIGINS='~.*' 
+  ```
+
 [2.18.9](https://github.com/bird-house/birdhouse-deploy/tree/2.18.9) (2025-11-10)
 ------------------------------------------------------------------------------------------------------------------
 

Makefile

@@ -8,7 +8,7 @@ override BIRDHOUSE_MAKE_DIR := $(shell realpath -P $$(dirname $(BIRDHOUSE_MAKE_C
 # Generic variables
 override SHELL       := bash
 override APP_NAME    := birdhouse-deploy
-override APP_VERSION := 2.18.9
+override APP_VERSION := 2.18.10
 
 # utility to remove comments after value of an option variable
 override clean_opt = $(shell echo "$(1)" | $(_SED) -r -e "s/[ '$'\t'']+$$//g")

README.rst

@@ -18,13 +18,13 @@ for a full-fledged production platform.
     * - citation
       - | |citation|
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/bird-house/birdhouse-deploy/2.18.9.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/bird-house/birdhouse-deploy/2.18.10.svg
     :alt: Commits since latest release
-    :target: https://github.com/bird-house/birdhouse-deploy/compare/2.18.9...master
+    :target: https://github.com/bird-house/birdhouse-deploy/compare/2.18.10...master
 
-.. |latest-version| image:: https://img.shields.io/badge/tag-2.18.9-blue.svg?style=flat
+.. |latest-version| image:: https://img.shields.io/badge/tag-2.18.10-blue.svg?style=flat
     :alt: Latest Tag
-    :target: https://github.com/bird-house/birdhouse-deploy/tree/2.18.9
+    :target: https://github.com/bird-house/birdhouse-deploy/tree/2.18.10
 
 .. |readthedocs| image:: https://readthedocs.org/projects/birdhouse-deploy/badge/?version=latest
     :alt: ReadTheDocs Build Status (latest version)

RELEASE.txt

@@ -1 +1 @@
-2.18.9 2025-11-10T17:14:06Z
+2.18.10 2025-11-12T17:25:51Z

birdhouse/components/README.rst

@@ -698,31 +698,62 @@ information.
 Usage
 -----
 
-The STAC API can be browsed via the ``stac-browser`` component. By default, the browser will point to the STAC API 
-exposed by the current stack instance. Once this component is enabled, STAC API will be accessible at 
-``https://<BIRDHOUSE_FQDN_PUBLIC>/stac`` endpoint and the STAC browser will be available at
-``https://<BIRDHOUSE_FQDN_PUBLIC>/stac-browser`` endpoint. In order to make the STAC browser the default entrypoint,
-define the following in the ``env.local`` file::
-
-  export BIRDHOUSE_PROXY_ROOT_LOCATION='return 302 ${BIRDHOUSE_PROXY_SCHEME}://\$host/stac-browser;'
+The STAC API can be browsed via the ``stac-browser`` component. Once this component is enabled, STAC API 
+will be accessible at the ``https://<BIRDHOUSE_FQDN_PUBLIC>/stac``.
 
-Here is a sample search query using a CLI::
+Here is a sample search query using a the ``pystac-client`` python CLI:
 
 .. code-block:: shell
 
     pip install pystac-client
-    stac-client search $PAVIS_FQDN/stac -q "variable_id=txgt_32" "scenario=ssp585"
+    stac-client search $BIRDHOUSE_FQDN_PUBLIC/stac -q "variable_id=txgt_32" "scenario=ssp585"
 
-Calls to the STAC API pass through Twitcher in order to validate authorization. Unauthenticated users will have 
-read-only access by default to STAC API resources while members of the `stac-admin` group can create and modify 
-resources. STAC Browser is not protected by any authorization mechanism.
+Calls to the STAC API pass through Twitcher in order to validate authorization.
+By default, only users that belong to the ``administrator`` and ``stac-admin`` groups will have access to STAC
+endpoints. Additional access permissions can be set in ``Magpie`` as needed.
+To give unauthenticated users read-only access to STAC API resources, enable the ``optional-components/stac-public-access``
+component.
 
 How to Enable the Component
 ---------------------------
 
 - Edit ``env.local`` (a copy of `env.local.example`_)
 - Add ``./components/stac`` to ``BIRDHOUSE_EXTRA_CONF_DIRS``.
 
+STAC Browser
+============
+
+STAC Browser is a web UI used to interact with the STAC API. 
+
+Usage
+-----
+
+The STAC API can be browsed via the ``stac-browser`` component. By default, the browser will point to the STAC API 
+exposed by the current ``components/stac`` service. 
+Once this component is enabled, the STAC browser will be available at the ``https://<BIRDHOUSE_FQDN_PUBLIC>/stac-browser`` 
+endpoint
+
+If your STAC API contains geojson data, it is recommended to set the ``STAC_CORS_ORIGINS`` value to accept the origin
+``https://geojson.io`` since the STAC Browser offers a link to open geojson data at this URL. 
+Note that you do not need to change the ``STAC_CORS_ORIGINS`` value from the default (which accepts all origins), but
+if you have changed it please update it to include this origin as well.
+
+For example:
+
+.. code::shell
+
+  # If the STAC_CORS_ORIGINS is currently
+  export STAC_CORS_ORIGINS='http://example.com ~http:(www|other)\.api\.example\.com'
+
+  # you can update it to
+  export STAC_CORS_ORIGINS='http://example.com ~http:(www|other)\.api\.example\.com https://geojson.io'
+
+How to Enable the Component
+---------------------------
+
+- Edit ``env.local`` (a copy of `env.local.example`_)
+- Add ``./components/stac-browser`` to ``BIRDHOUSE_EXTRA_CONF_DIRS``.
+
 Canarie-API
 ===========
 

birdhouse/components/canarie-api/docker_configuration.py.template

@@ -108,8 +108,8 @@ SERVICES = {
             # NOTE:
             #   Below version and release time auto-managed by 'make VERSION=x.y.z bump'.
             #   Do NOT modify it manually. See 'Tagging policy' in 'birdhouse/README.rst'.
-            'version': '2.18.9',
-            'releaseTime': '2025-11-10T17:14:06Z',
+            'version': '2.18.10',
+            'releaseTime': '2025-11-12T17:25:51Z',
             'institution': '${BIRDHOUSE_INSTITUTION}',
             'researchSubject': '${BIRDHOUSE_SUBJECT}',
             'supportEmail': '${BIRDHOUSE_SUPPORT_EMAIL}',
@@ -141,8 +141,8 @@ PLATFORMS = {
             # NOTE:
             #   Below version and release time auto-managed by 'make VERSION=x.y.z bump'.
             #   Do NOT modify it manually. See 'Tagging policy' in 'birdhouse/README.rst'.
-            'version': '2.18.9',
-            'releaseTime': '2025-11-10T17:14:06Z',
+            'version': '2.18.10',
+            'releaseTime': '2025-11-12T17:25:51Z',
             'institution': '${BIRDHOUSE_INSTITUTION}',
             'researchSubject': '${BIRDHOUSE_SUBJECT}',
             'supportEmail': '${BIRDHOUSE_SUPPORT_EMAIL}',

birdhouse/components/proxy/conf.d/cors.include

@@ -1,7 +1,17 @@
       proxy_hide_header 'Access-Control-Allow-Origin';
 
+     if ( $access_control_allow_origin ~ "^$" ) {
+        set $access_control_allow_origin '*';
+     }
+
+     set $vary_origin ""; # nginx will omit this header value if set to the empty string
+     if ( $access_control_allow_origin != '*' ) {
+        set $vary_origin Origin;
+     }
+
      if ($request_method = 'OPTIONS') {
-        add_header 'Access-Control-Allow-Origin' '*';
+        add_header 'Access-Control-Allow-Origin' $access_control_allow_origin;
+        add_header Vary $vary_origin;
         add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
         #
         # Custom headers and headers various browsers *should* be OK with but aren't
@@ -16,13 +26,15 @@
         return 204;
      }
      if ($request_method = 'POST') {
-        add_header 'Access-Control-Allow-Origin' '*';
+        add_header 'Access-Control-Allow-Origin' $access_control_allow_origin;
+        add_header Vary $vary_origin;
         add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
         add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
         add_header 'Access-Control-Expose-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
      }
      if ($request_method = 'GET') {
-        add_header 'Access-Control-Allow-Origin' '*';
+        add_header 'Access-Control-Allow-Origin' $access_control_allow_origin;
+        add_header Vary $vary_origin;
         add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
         add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
         add_header 'Access-Control-Expose-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';

birdhouse/components/proxy/conf.d/frontend.conf.template

@@ -14,6 +14,8 @@ map $http_x_forwarded_proto $real_scheme {
   ''      $scheme;
 }
 
+include /etc/nginx/conf.extra-directives.d/*/*.conf;
+
 server {
     listen       80 ${PROXY_LISTEN_80_PARAMS};
     server_name  localhost;

birdhouse/components/stac/.gitignore

@@ -1,4 +1,5 @@
 config/magpie/config.yml
 config/proxy/conf.extra-service.d/stac.conf
+config/proxy/conf.extra-directives.d/stac.conf
 config/canarie-api/canarie_api_monitoring.py
 service-config.json