diff --git a/flyctl/integrating.mdx b/flyctl/integrating.mdx index f1aeae2a11..cea068e806 100644 --- a/flyctl/integrating.mdx +++ b/flyctl/integrating.mdx @@ -64,6 +64,14 @@ fly tokens create readonly -o my-org -x 720h Scoped to the entire org (like `fly tokens create org`) but can't create, deploy, or modify anything. Good for monitoring scripts, status dashboards, or any workflow that only consumes data from the Fly API. +**WireGuard token** For managing an organization's WireGuard peers: + +```bash +fly tokens create wireguard -o my-org --network staging -x 720h +``` + +The `--network` flag limits the token to the networks it needs. For what the token can and can't do, see [Create an org-scoped WireGuard token](/security/tokens#create-an-org-scoped-wireguard-token). + ### Token management List active tokens: diff --git a/networking/custom-private-networks.mdx b/networking/custom-private-networks.mdx index 767b0dc13c..9a4c4895bd 100644 --- a/networking/custom-private-networks.mdx +++ b/networking/custom-private-networks.mdx @@ -24,6 +24,8 @@ If you destroy all the apps on a custom 6PN, the network technically still exist It's a best practice to use a formula for naming custom 6PNs, especially if you're going to have a lot of them or if you need to add more than one app to each custom 6PN. For example, `customerID-network` or `appName-someID-network`. Network names can have letters, numbers, and dashes, but must start with a letter. +You can limit a WireGuard token to specific networks by name. See [Create an org-scoped WireGuard token](/security/tokens#create-an-org-scoped-wireguard-token). + ## Create a custom private network diff --git a/security/tokens.mdx b/security/tokens.mdx index 1aa8a10a19..3186488c9e 100644 --- a/security/tokens.mdx +++ b/security/tokens.mdx @@ -1,6 +1,6 @@ --- title: Access tokens -description: "Create Fly.io access tokens scoped to one app or org, including SSH, machine-exec and read-only tokens, then set expiry, list and revoke them with fly tokens." +description: "Create Fly.io access tokens scoped to one app or org, including SSH, machine-exec, read-only and WireGuard tokens, then set expiry, list and revoke them." source_url: https://fly.io/docs/security/tokens/ --- @@ -22,7 +22,7 @@ You can create a standard app-scoped deploy token, a token to SSH into an app's Use an org-scoped token for access to manage all the apps within a single organization. An org-scoped token is the middle ground between the auth token and the more restricted app-scoped token, and is useful when you want to automate a single org. -You can create a standard org-scoped token or a read-only org-scoped token. +You can create a standard org-scoped token or a read-only org-scoped token. You can also create an org-scoped WireGuard token, which manages an org's WireGuard peers and can't act on apps. ## Create and manage tokens @@ -82,7 +82,7 @@ fly tokens create machine-exec --command "" ### Create org-scoped tokens -Org-scoped tokens are limited to managing a single org and its resources, including apps. +Org-scoped tokens are limited to a single org. A standard org-scoped token can manage the org and its resources, including apps. If you don't specify a name with the `--name` option, then the default name is `Org deploy token`. @@ -116,6 +116,50 @@ Create a read-only token based on an existing token: fly tokens create readonly --name <"my token name"> --expiry --from-existing -t ``` +#### Create an org-scoped WireGuard token + +A WireGuard token is for managing the WireGuard peers of a single org: + +- The token can create and remove WireGuard peers. Without `--network`, it works on every private network in the org. +- The token can do org-level reads, like listing the org's WireGuard peers. +- The token can't act on apps or Machines, reads included. Any command that names an app is refused, for example `fly ssh console --app`, `fly proxy --app`, `fly status -a`, or `fly machines list -a`. + +If you don't specify a name with the `--name` option, then the default name is `WireGuard token`. + +Create a WireGuard token with a custom name and expiry: + +``` +fly tokens create wireguard -o --name <"my token name"> --expiry +``` + +A WireGuard peer joins a private network and can reach every private service on that network. A token that can create peers on any network gives access to all of them. Use the `--network` option with the [network name](/networking/custom-private-networks#network-names-and-ids) to limit a token to the networks it needs: + +- The token can create and remove WireGuard peers only on the networks you name. A request that names any other network is refused, reads included. +- Reads that name no network, like listing the org's WireGuard peers, aren't affected. +- To allow several networks, repeat the option or separate the names with commas: `--network staging --network prod` or `--network staging,prod`. +- To allow the org's default network, use `--network default`. You can't use `--network` to name a custom network that's called `default`. +- Network names aren't checked when you create the token. With `--network staging,prdo`, the token works on `staging` but not on `prod`, and you get no error. + +This example creates a WireGuard token for the `my-org` org that's limited to the `staging` network and valid for 24 hours: + +``` +fly tokens create wireguard -o my-org --network staging --expiry 24h +``` + +With a network-limited token, [`fly wireguard create`](/flyctl/cmd/fly_wireguard_create) must name an allowed network: + +``` +fly wireguard create my-org ord my-peer --network staging +``` + +For the default network, `--network` works differently on the two commands: + +- Token allows the default network: `fly tokens create wireguard --network default` +- Peer on the default network: `fly wireguard create ` (no `--network`). This is refused unless the token allows the default network. +- `fly wireguard create --network default` means a custom network named `default`. + +For all options, refer to the [`fly tokens create wireguard` command docs](/flyctl/cmd/fly_tokens_create_wireguard). + ### List or view tokens List all the tokens for current app, or use the `--app` option to specify an app: