Skip to main content

Dynamic Access Keys

Outline offers two types of access keys: static and dynamic. Static keys encode all the connection information within the key itself, while dynamic keys encode the location of the connection information, allowing you to store that information remotely and change it if needed. This means you can update your server configuration without having to generate and distribute new keys to your users. This document explains how to use dynamic access keys for more flexible and efficient management of your Outline server.

There are three formats to specify the access information that will be used by your dynamic access keys:

Outline Client v1.8.1+.

You can directly use an existing ss:// link. This method is ideal if you don't need to frequently change the server, port, or encryption method, but still want the flexibility to update the server address.

Example:

ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTpleGFtcGxl@outline-server.example.com:8388/?outline=1

Use a JSON object​

Outline Client v1.8.0+.

This method offers more flexibility for managing all aspects of your users' Outline connection. You can update the server, port, password, and encryption method this way.

Example:

{
  "server": "outline-server.example.com",
  "server_port": 8388,
  "password": "example",
  "method": "chacha20-ietf-poly1305"
}
  • server: The domain or IP address of your VPN server.
  • server_port: The port number your VPN server is running on.
  • password: The password required to connect to the VPN.
  • method: The encryption method used by the VPN. Refer to the Shadowsocks supported AEAD ciphers

Use a YAML Object​

Outline Client v1.15.0+.

This method is similar to the previous JSON method but adds even more flexibility by leveraging Outline's advanced configuration format. You can update the server, port, password, encryption method, and much more.

Example:

transport:
  $type: tcpudp
  tcp:
    $type: shadowsocks
    endpoint: outline-server.example.com:8388
    cipher: chacha20-ietf-poly1305
    secret: example
  udp:
    $type: shadowsocks
    endpoint: outline-server.example.com:8388
    cipher: chacha20-ietf-poly1305
    secret: example
  • transport: Defines the transport protocols to be used (TCP and UDP in this case).
  • tcp/udp: Specifies the configuration for each protocol.
    • $type: Indicates the type of configuration, here it's shadowsocks.
    • endpoint: The domain or IP address and port of your VPN server.
    • secret: The password required to connect to the VPN.
    • cipher: The encryption method used by the VPN. Refer to the Shadowsocks supported AEAD ciphers.

See Access Key Configuration for details on all the ways you can configure access to your Outline server, including transports, endpoints, dialers, and packet listeners.

Extract Access Information from a Static Key​

If you have an existing static access key, you can extract the information to create a JSON- or YAML-based dynamic access key. Static access keys follow the following pattern:

SS-URI = "ss://" userinfo "@" hostname ":" port [ "/" ] [ "#" tag ]
userinfo = websafe-base64-encode-utf8(method  ":" password)
           method ":" password

Example:

ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTpleGFtcGxl@outline-server.example.com:8388/?outline=1

  • Server: outline-server.example.com

  • Server Port: 8388

  • User Info: Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTpleGFtcGxl Decoded as base64 using a tool like the Google Admin Toolbox Encode/Decode

    • Method: chacha20-ietf-poly1305
    • Password: example

Choose a Hosting Platform​

Now that you understand how to create dynamic access keys, it's important to choose a suitable hosting platform for your access key configuration. When making this decision, consider factors like the platform's reliability, security, ease of use, and censorship resistance. Will the platform consistently serve your access key information without downtime? Does it offer appropriate security measures to protect your configuration? How easy is it to manage your access key information on the platform? Is the platform accessible in regions with internet censorship?

For situations where access to information might be restricted, consider hosting on censorship-resistant platforms like Google Drive, pad.riseup.net, Amazon S3 (with path-style access), Netlify, or GitHub secret gists. Evaluate the specific needs of your deployment and choose a platform that aligns with your requirements for accessibility and security.

Share the Key with Your Users​

Hosting the configuration is only half of a dynamic access key. What your users add to the Outline client is the location of that configuration, written with the ssconf:// scheme. Take the HTTPS URL the configuration is served from and replace https:// with ssconf://.

https://keys.example.com/a1b2c3d4e5f6.yml    <- where you host the config
ssconf://keys.example.com/a1b2c3d4e5f6.yml   <- the access key you share

The client replaces the ssconf:// scheme with https:// before fetching, so the host, port, path and query string are all preserved as they are. A plain https:// URL is also accepted as a dynamic access key; the ssconf:// scheme exists so that the operating system opens the link with the Outline client instead of a browser.

You can append a fragment to name the entry in the client's server list:

ssconf://keys.example.com/a1b2c3d4e5f6.yml#My%20Server

The client shows this entry as "My Server"; the fragment is not part of the fetched URL.

caution

A dynamic access key URL is a credential. Anyone who has it can fetch your configuration and read the secret inside it. Serve it over HTTPS, give each user their own long, randomly generated path rather than a guessable one such as /alice.yml, and avoid platforms that publish or index what they host, such as public GitHub repositories or public gists. See Choose a Hosting Platform for more factors to weigh when picking where to host.

note

Deleting the hosted configuration does not revoke access: the credentials it contained remain valid until you remove the key from the server, connected clients stay connected, and clients that reconnect automatically (at device boot or app launch) reuse the last configuration they fetched successfully. A connected client also keeps using the configuration it fetched at connect time. Edits to the hosted file take effect the next time it reconnects.