Secrets file

Accessing files on remote servers, such as the RiskScape Platform, may require some form of authentication before you can access it. RiskScape allows you to provide this information using a secrets file.

The secrets file is kept separate from your project files to make it easy for each user to have their own secrets and avoid accidentally exposing your secrets as you share your projects with others.

The RiskScape secrets file is an INI format file located at:

• %USERPROFILE%\RiskScape\secrets.ini (Windows)

• ${HOME}/.config/riskscape/secrets.ini (Linux)

• ~/RiskScape/secrets.ini (Mac)

Note

Your secrets file should only be readable by you to avoid exposing your secrets to others. Baeldung has some information on how to do this in Linux, but if you can, ask your IT provider how best to do this on your computer.

Authentication Methods

RiskScape supports different kinds of authentication methods, which it terms ‘frameworks’.

Which framework you use will depend on what authentication methods the remote service supports. As an example, the RiskScape Platform supports passing an API token in an HTTP header, so we can use the http-header framework, or the more convenient platform framework.

RiskScape currently supports the following authentication frameworks. Click on a framework below for more details.

• Secret frameworks
  • http-header
  • koordinates
  • platform

Tip

When you define bookmarks that require a secret you should set the requires-secret bookmark parameter to the required secret framework. Then if the secret is not found RiskScape can give you (or someone you shared the project with) an error telling you exactly what the problem is.

See RiskScape Platform below for an example.

Examples

RiskScape Platform

To be able to work with data stored in a project in the RiskScape Platform, you can use a WebDAV token.

Follow the link and copy the generated token and paste it in to your secrets file like so:

[riskscape-nz]
framework = platform
token = YOUR_WEBDAV_TOKEN

With this in place, you can access data layers stored in the platform, e.g.

[bookmark population-grid]
# RiskScape will automatically pass your webdav token when it fetches this data
requires-secret = platform
location = https://riskscape.nz/dav/projects/riskscape/example/getting-started/pop-grid.tiff

Koordinates

Koordinates is a cloud geospatial storage service that powers sites such as:

• LINZ data service

• Stats NZ data finder

Koordinates uses an API key embedded in a URL to authenticate requests for data. You can generate an API key from the specific Koordinates service’s user profile menu and then add it to your secrets file. You then do not need to include your API key in any other project files in order to access the Koordinates datasets.

Here’s an example secret that will use the configured API key when fetching WFS data from https://data.linz.govt.nz/services:

[data.linz.govt.nz]
framework = koordinates
api-key = YOUR_API_KEY

For more information on using Koordinates data with RiskScape, via WFS, see Koordinates example.

Note

RiskScape will add your API key to data service URLs as needed. This means that your API key can still potentially appear in debug or error messages.

When to use secrets

Secrets are currently only supported when using the RiskScape CLI Engine, as they rely on the secrets.ini file to be present on your local computer. Secrets are intended to be used when fetching remote data via WFS or HTTP links and using it on your local computer.

When interacting with the RiskScape Platform, secrets can be used on your local computer to fetch data from the Platform. However, using secrets in projects on the Platform itself is currently not supported. When uploading a project to the Platform, be careful it does not contain bookmarks with require-secrets set.

Tip

You can take a bookmark that uses secrets and use the following command to turn it into a GeoPackage file:

riskscape bookmark eval BOOKMARK_ID --format geopackage

You can then upload the GeoPackage file to the Platform and use that instead of your bookmark. Using a local GeoPackage copy of the bookmark may also make your model run faster locally, as it avoids fetching the data via WFS each time.

.