This document details Vespa Cloud's security model.
For use of keys in automation, refer to examples in automated deployments and the api key reference.
User API Key |
This key is used to access the Vespa Cloud control APIs. The key is set on the tenant level - it is hence valid for all applications for the tenant. The key is associated with a user and can be uploaded or generated in the "Keys" view in the Console. Use this key to deploy/submit applications with Maven (see getting started, including Java development). This key has full control plane read/write credentials. |
|
|---|---|---|
Application API Key |
This key is used to access the Vespa Cloud control APIs. The key is associated with an application, and can be uploaded or generated in the "Application deploy" view in the Console. Use this key in CI/CD pipelines where headless access is required to deploy applications. This key has control plane read credentials, and also deploy/submit rights. |
|
Vespa API Certificate |
The key is a private key and X.509 certificate generated for the client. Only clients using the private key and certificate will be granted access to the application's data plane. Example data plane APIs are query, feed and metrics. Generate the certificate and key and include the certificate in the application package - example: create a self-signed certificate. |
The following explains how access to management features in Vespa is controlled.
Console access is available to authenticated users only. This is bootstrapped by creating a tenant. Manage users and roles in the users view: http://console.vespa.ai/tenant/tenant_name/users:
Developer |
Can create applications, deploy to dev zones and submit to prod zones. |
|---|---|
Admin |
Manage users and tenant information. Tenant information includes usage information and billing. |
There are two kinds of application deployments:
manual deployments to dev/perf zones, and
automated deployments to production zones.
Likewise, there are two kinds of keys that can be used for API authentication:
User API keys, which identify a member of the developer role, and allows, e.g., manual deployments and system tests, and
application API keys, which identify a build service which submits application packages for automated deployment.
User API keys are personal, and are managed in the users view. Each developer may have a single key at any time, and both administrators and developers may revoke the key of another developer, if it has been compromised.
Application API keys are managed on the application level - see deploy view. An application can have multiple Application API keys.
Refer to the api key reference for details.
All application endpoints are secured with mutual TLS.
On first time deployment, a server certificate identifying the application is provisioned. This certificate will be automatically set up on all application endpoints. The certificate is signed by DigiCert or Globalsign.
To enable TLS client side authentication,
add trusted certificates (or issuer certificates) to [application-package]/security/clients.pem
With this, only clients with a valid certificate can access the application endpoints.
In order to test application deployments, another trusted client certificate is added by Vespa Cloud for deployment to the test and staging zones only. This does not affect production deployments.
To run system tests against a development endpoint,
specify the dataPlaneCertificateFile and dataPlaneKeyFile properties,
in the same manner as the apiKeyFile used for API access.
To add a new certificate/key pair:
Generate a new pair. Example:
$ openssl req -x509 -nodes -days 365 -newkey rsa:4096 \ -subj "/CN=cloud.vespa.example" \ -keyout data-plane-private-key.pem -out data-plane-public-cert.pem
Add new public certificate to application package
(it is OK with blank lines in clients.pem -
example):
$ cat data-plane-public-cert.pem >> src/main/application/security/clients.pem
Deploy the application package.
Use new cert/key pair in Vespa requests.
Remove unused certs from clients.pem and deploy again.
In Vespa guides, curl is used in examples, like:
$ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem $ENDPOINT
To use a browser, install key/cert pair - this procedure is tested on macOS Catalina / Chrome 80.0.3987.132, assuming Certificate Common Name is "cloud.vespa.example" (as in the guides):
Install key/cert pair:
$ security import data-plane-private-key.pem -k ~/Library/Keychains/login.keychain $ security import data-plane-public-cert.pem -k ~/Library/Keychains/login.keychain
In Keychain Access: With login keychain -> My Certificates category -> cloud.vespa.example, right-click and "New Identity Preference", then add the endpoint url, like https://me.my-app.mytenant1.aws-us-east-1c.dev.public.vespa.oath.cloud
Open the same URL in Chrome, choose the example.com certificate and allow Chrome to read the private key.
All application nodes run as separate isolated Docker containers.
All internal communication between nodes in an application is secured in two layers:
Network ACLs (iptables) allowing only local communication within the application.
Mutual TLS with authorization only allowing nodes from the same application.