From e1023500f1aabc3b982a2f47b60acfe0a30c12a3 Mon Sep 17 00:00:00 2001 From: Phillip LeBlanc Date: Mon, 11 Nov 2024 15:55:15 +0900 Subject: [PATCH] Add API Key authentication docs (#623) --- .../docs/api/arrow-flight-sql/index.md | 6 +- spiceaidocs/docs/api/auth/index.md | 63 +++++++++++++++++++ spiceaidocs/docs/api/http/index.md | 4 ++ spiceaidocs/docs/api/jdbc/index.md | 16 ++++- spiceaidocs/docs/clients/DBeaver/index.md | 2 + 5 files changed, 88 insertions(+), 3 deletions(-) create mode 100644 spiceaidocs/docs/api/auth/index.md diff --git a/spiceaidocs/docs/api/arrow-flight-sql/index.md b/spiceaidocs/docs/api/arrow-flight-sql/index.md index b028d1f7..85f45c66 100644 --- a/spiceaidocs/docs/api/arrow-flight-sql/index.md +++ b/spiceaidocs/docs/api/arrow-flight-sql/index.md @@ -1,7 +1,7 @@ --- title: 'Arrow Flight SQL API' sidebar_label: 'Arrow Flight SQL' -sidebar_position: 3 +sidebar_position: 4 description: 'Query Spice using JDBC/ODBC/ADBC' --- @@ -10,3 +10,7 @@ description: 'Query Spice using JDBC/ODBC/ADBC' Spice implements the Flight SQL protocol which enables querying the datasets configured in Spice via tools that support connecting via one of the Arrow Flight SQL drivers, such as [DBeaver](https://dbeaver.io), [Tableau](https://www.tableau.com/), or [Power BI](https://www.microsoft.com/en-us/power-platform/products/power-bi). arrow flight and spice + +## Authentication + +API Key authentication is supported for the Arrow Flight SQL endpoint. See [API Key Authentication](../../api/auth/index.md) for more details. diff --git a/spiceaidocs/docs/api/auth/index.md b/spiceaidocs/docs/api/auth/index.md new file mode 100644 index 00000000..322c6143 --- /dev/null +++ b/spiceaidocs/docs/api/auth/index.md @@ -0,0 +1,63 @@ +--- +title: 'Authentication' +sidebar_label: 'Authentication' +sidebar_position: 3 +description: 'Authentication documentation' +pagination_prev: null +pagination_next: null +--- + +Spice supports adding optional authentication to its API endpoints via configurable API keys. + +Use the `auth` section as a child to `runtime` to provide the API keys. Multiple API keys can be specified, and any of the keys can be used to authenticate requests. + +```yaml +runtime: + auth: + api-key: + enabled: true + keys: + - ${ secrets:api_key } # Use the secret replacement syntax to load the API key from a secret store + - 1234567890 # Or specify the API key directly +``` + +To learn more about secrets, see [Secret Stores](../../components/secret-stores/index.md). + +:::info + +The API key authentication is applied on startup and changes will not take effect until the runtime is restarted. + +::: + +## HTTP + +For HTTP routes, the API key is expected to be included in the `X-API-Key` header. + +```bash +> curl -i "http://localhost:8090/v1/sql" -H "X-API-Key: 1234567890" -d 'SELECT 1' + +HTTP/1.1 200 OK +content-type: text/plain; charset=utf-8 +x-cache: Miss from spiceai +content-length: 16 +date: Fri, 08 Nov 2024 07:14:24 GMT + +[{"Int64(1)":1}] +``` + +The `/health` and `/v1/ready` endpoints are not protected and can be accessed without an API key. + +## Flight SQL + +For the Flight SQL endpoint, the API key is expected to be included in the `Authorization` header as a Bearer token, i.e. `Authorization: Bearer ${ api_key }`. + +## Spice CLI + +When API key authentication is enabled, the Spice CLI can connect to the runtime by specifying the `--api-key` argument. + +```bash +spice sql --api-key 1234567890 +spice status --api-key 1234567890 +spice refresh taxi_trips --api-key 1234567890 +# etc. +``` diff --git a/spiceaidocs/docs/api/http/index.md b/spiceaidocs/docs/api/http/index.md index 17d1f99e..2b15e8bf 100644 --- a/spiceaidocs/docs/api/http/index.md +++ b/spiceaidocs/docs/api/http/index.md @@ -10,3 +10,7 @@ pagination_next: null import DocCardList from '@theme/DocCardList'; + +## Authentication + +API Key authentication is supported for all HTTP routes. See [API Key Authentication](../../api/auth/index.md) for more details. diff --git a/spiceaidocs/docs/api/jdbc/index.md b/spiceaidocs/docs/api/jdbc/index.md index d974dfe5..1ee2514c 100644 --- a/spiceaidocs/docs/api/jdbc/index.md +++ b/spiceaidocs/docs/api/jdbc/index.md @@ -15,7 +15,7 @@ Spice supports JDBC clients through a JDBC driver implementation based on the [F ### Download the Flight SQL JDBC driver -- Find the appropriate [Flight SQL JDBC driver](https://central.sonatype.com/artifact/org.apache.arrow/flight-sql-jdbc-driver/versions) version. +- Find the appropriate [Flight SQL JDBC driver](https://central.sonatype.com/artifact/org.apache.arrow/flight-sql-jdbc-driver/versions) version. - Click **Browse** next to the version you want to download - Click the `flight-sql-jdbc-driver-XX.XX.XX.jar` file (with only the `.jar` file extension) from the list of files to download the driver jar file @@ -57,7 +57,19 @@ Follow the instructions specific to your application for adding a custom JDBC dr 1. **Ensure Spice is running** 1. Click **Connect** -Note: Spice has [TLS support](/api/tls). For testing or non-production use cases for Spice without TLS, the following JDBC connection URL will bypass TLS `jdbc:arrow-flight-sql://{host}:{port}?useEncryption=false&disableCertificateVerification=true`. +:::info + +Spice has [TLS support](/api/tls). For testing or non-production use cases for Spice without TLS, the following JDBC connection URL will bypass TLS `jdbc:arrow-flight-sql://{host}:{port}?useEncryption=false&disableCertificateVerification=true`. + +::: + +### Authentication + +If [API Key authentication](../../api/auth/index.md) is enabled, the API key can be provided in the JDBC connection URL as a query parameter: + +`jdbc:arrow-flight-sql://{host}:{port}?user=&password=` + +Replace `` with the API key value. The `user` and `password` parameters are required by the JDBC driver, but only the `password` parameter is used for the API key. ## Execute Test Query diff --git a/spiceaidocs/docs/clients/DBeaver/index.md b/spiceaidocs/docs/clients/DBeaver/index.md index e6811dbb..5c9672b2 100644 --- a/spiceaidocs/docs/clients/DBeaver/index.md +++ b/spiceaidocs/docs/clients/DBeaver/index.md @@ -32,8 +32,10 @@ pagination_next: null 1. Click the "Settings" tab 1. In the "Driver Name" field - enter: ```Apache Arrow Flight SQL``` 1. In the "URL Template" field - enter: ```jdbc:arrow-flight-sql://{host}:{port}?useEncryption=false&disableCertificateVerification=true``` + - If [API key authentication](../../api/auth/index.md) is enabled, the URL template should be: ```jdbc:arrow-flight-sql://{host}:{port}?useEncryption=false&disableCertificateVerification=true&user=&password=``` - where `` is the API key value 1. In the "Driver Type" drop-down box - choose: "SQLite" 1. Select "No authentication" + - This should be selected even if API key authentication is enabled in the runtime, as the API key is supplied via the URL template above. 1. The driver manager "Edit Driver" window should look like this: ![Driver Manager completed](https://imagedelivery.net/HyTs22ttunfIlvyd6vumhQ/20348c42-117b-4763-80d2-6e615b23ae00/public "Driver Manager completed") 1. Click the blue "OK" button on the lower-right to save the driver