chore(installation): docs for token manager + private key (go-vela#349)

adeebahmed · Mar 6, 2023 · 8cbc6e2 · 8cbc6e2
1 parent c805bf3
commit 8cbc6e2
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 23 deletions.
diff --git a/content/installation/server/reference/_index.md b/content/installation/server/reference/_index.md
@@ -97,21 +97,15 @@ The variable should be provided as a `string`.
 This variable should match [the `VELA_SERVER_SECRET` variable](/docs/installation/worker/reference/#vela_server_secret) provided to the worker.
 {{% /alert %}}
 
-## Optional
-
-This section contains a list of all variables that can be provided to the server.
+### VELA_SERVER_PRIVATE_KEY
 
-### VELA_ACCESS_TOKEN_DURATION
+This variable sets the private key that will be used to sign all JWT tokens within Vela. Please be sure to follow [guidelines](https://www.rfc-editor.org/rfc/rfc2104#section-3) related to generating a private key.
 
-This variable sets the maximum duration of time a Vela access token for a user is valid on the server.
-
-The access token is used for authenticating user's requests to the server.
+The variable should be provided as a `string`.
 
-The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+## Optional
 
-{{% alert title="Note:" color="primary" %}}
-This variable has a default value of `15m`.
-{{% /alert %}}
+This section contains a list of all variables that can be provided to the server.
 
 ### VELA_CLONE_IMAGE
 
@@ -436,18 +430,6 @@ The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute
 This variable has a default value of `vela`.
 {{% /alert %}}
 
-### VELA_REFRESH_TOKEN_DURATION
-
-This variable sets the maximum duration of time a Vela refresh token for a user is valid on the server.
-
-The refresh token is used for refreshing a user's access token on the server.
-
-The variable can be provided as a `duration` (i.e. `5s`, `10m`).
-
-{{% alert title="Note:" color="primary" %}}
-This variable has a default value of `8h`.
-{{% /alert %}}
-
 ### VELA_REPO_ALLOWLIST
 
 This variable sets a group of repositories, from the SCM, that can be enabled on the server.
@@ -604,6 +586,42 @@ The variable can be provided as a `string`.
 This variable has a default value of `2`.
 {{% /alert %}}
 
+### VELA_USER_ACCESS_TOKEN_DURATION
+
+This variable sets the maximum duration of time a Vela access token for a user is valid on the server.
+
+The access token is used for authenticating user's requests to the server.
+
+The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+
+{{% alert title="Note:" color="primary" %}}
+This variable has a default value of `15m`.
+{{% /alert %}}
+
+### VELA_USER_REFRESH_TOKEN_DURATION
+
+This variable sets the maximum duration of time a Vela refresh token for a user is valid on the server.
+
+The refresh token is used for refreshing a user's access token on the server.
+
+The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+
+{{% alert title="Note:" color="primary" %}}
+This variable has a default value of `8h`.
+{{% /alert %}}
+
+### VELA_BUILD_TOKEN_BUFFER_DURATION
+
+This variable sets the maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server.
+
+The build token is used for authenticating a worker's access to the server to update build resources.
+
+The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+
+{{% alert title="Note:" color="primary" %}}
+This variable has a default value of `5m`.
+{{% /alert %}}
+
 ### VELA_WEBUI_ADDR
 
 This variable sets a fully qualified URL to the Vela [UI](/docs/installation/ui/) address.

diff --git a/content/installation/server/reference/token_manager.md b/content/installation/server/reference/token_manager.md
@@ -0,0 +1,26 @@
+---
+title: "Token Manager"
+linkTitle: "Token Manager"
+description: >
+  This section contains information on the token manager component for the Vela server.
+---
+
+This component is responsible for generating and validating JWT tokens shared between the Vela server, workers, and users based off the configuration provided.
+
+The token manager is designed to ensure secure interactions with the server and protect build resources.
+
+
+## Configuration
+
+The following options are used to configure the component:
+
+| Name                          | Description                                                                                                                     | Required | Default   | Environment Variables                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------- |
+| `vela-server-private-key`     | private key used for signing and validating all JWT tokens                                                                      | `true`   | `N/A`     | `VELA_SERVER_PRIVATE_KEY`                     |
+| `user-access-token-duration`  | maximum duration of time a Vela access token for a user is valid on the server                                                  | `true`   | `15m`     | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`             |
+| `user-refresh-token-duration` | maximum duration of time a Vela refresh token for a user is valid on the server                                                 | `true`   | `8h`      | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`           |
+| `build-token-buffer-duration` | maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server  | `true`   | `5m`      | `VELA_BUILD_TOKEN_BUFFER_DURATION`<br>`BUILD_TOKEN_BUFFER_DURATION`             |
+
+{{% alert title="Note:" color="primary" %}}
+For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/).
+{{% /alert %}}