FR: allow management of API key lifecycle via API

[tjstansell]

Tell us about your idea!

allow management of lifecycle of API keys via API

What are you trying to do?

API keys have a finite expiration date. Therefore, they must be rotated regularly. We use API keys in automation to automatically enable subnet routes as EC2 nodes get cycled in our AWS VPCs. We'd like for these API keys to also be able to be programmatically cycled via CI automation.

How should we solve this?

Provide a generic key management API that has feature parity with the admin console. Namely:

1. query status of keys
2. generate new keys
3. delete expired keys

What is the impact of not solving this?

We need to remember to manually generate new API keys every 180 days and manually populate a credential store for our automation to use.

Anything else?

Ideally, this API mechanism would allow admins to see the status of ALL API keys, not just personal ones (those associated with the admin user who created the API key). That's not a requirement for the ability to manage the lifecycle of one's own keys, however, which is what this issue is mainly about.

Additionally, while we specifically are looking at API key lifecycle here, the lifecycle of all key types should be considered, as we need the same automation to be able to generate new ephemeral keys as well, but I believe that's being handled by #1369.

[DentonGentry]

Since this bug was filed, an API endpoint was added to create an authkey: https://github.com/tailscale/tailscale/blob/main/api.md#tailnet-keys-post

An idea being considered is to use the node key of the device to sign the request for a new API key, proving that the operation is being done on a node which is actively on the tailnet. This provides some ability to reason about the chance the key has been exfiltrated. However, it wouldn't work in cases where the API key is being used on a device which is not itself on the tailnet.

[DentonGentry]

The current status is that using an API key one can:

• create an authkey: https://github.com/tailscale/tailscale/blob/main/api.md#tailnet-keys-post
• assign tags to the authkey: https://tailscale.com/blog/acl-tags-ga/
• revoke an authkey: https://github.com/tailscale/tailscale/blob/main/api.md#tailnet-keys-key-delete

To set expectations: I don't expect to provide controls over the lifetime of an authkey to make it expire at some interval other than the default 90 days. Generally when people ask for this it is to have some assurance that the key will be gone. Key expirations occur in such numbers that they are batched, the control server doesn't always delete it the instant it is supposed to expire. If you need to be very sure the key is revoked by a particular time, please delete it explicitly: https://github.com/tailscale/tailscale/blob/main/api.md#tailnet-keys-key-delete

---

API keys expire after 90 days. Right now it is a manual process to generate a new API key from the admin panel and install it wherever it is being used. We do expect to provide an automated way to allocate/renew API keys, but this is not implemented yet.

[mikevischer]

We are looking forward to renewing API keys via the API. Thanks for the update!

[DentonGentry]

Work on being able to renew/replace API keys automatically has started.

[justenwalker]

I'm developing a way to automatically rotate our Tailscale Device Keys and this works very well except it is rendered nearly useless without the ability to rotate the Tailscale API Keys too.

The problem is that they seem to have the same fixed lifetime (90 days), so either the API Key I use for rotation expires before it gets a chance to be used to rotate the device keys or it would only be good to rotate our device keys once before it would need to be rotated (manually) itself.

I'd be OK manually rotating the API key maybe once or twice a year, but as it stands, API Keys would need to be rotated manually every 90 days - which is a frequency that begs for automation (like Let's Encrypt)

[ItalyPaleAle]

We would love this feature too for Dapr, to be able to use Tailscale to run our E2E tests (see: dapr/dapr#4962 )

[willnorris]

We're currently working on an upgrade to our API keys that will follow the OAuth 2.0 Client Credential flow. That will include:

• from the Admin panel, create an OAuth client with long-lived credentials.
• OAuth clients are associated with the tailnet, not the individual user that created it
• OAuth client credentials are used to create short-lived (currently 1 hour) access tokens that are used to authenticate to the API
• OAuth client credentials don't ever expire, but can be revoked from the admin panel. Revoking an OAuth client also revokes all of the access tokens created by it.

We will also be introducing more granular scopes so that access tokens can only call certain API endpoints. When creating an OAuth client, you'll specify the default scopes that tokens created by it can have. You can also create an access token with fewer scopes.

The intent is that you will be able to use this with standard OAuth 2.0 libraries that support the client credential flow (which seems to be basically all of the popular ones we looked at).

[justenwalker]

@willnorris Sounds great. Also sounds like this is a long-term project and not something quickly implemented. Are there any rough timelines around when this feature will be available?

[DentonGentry]

The update posted on this issue some time ago:

Work on being able to renew/replace API keys automatically has started.

referred to this project. We don't have a timeline to share yet, but it has been underway for some time.

[Gowiem]

@DentonGentry @willnorris any update or timeline on the oauth work? That 90 day requirement means adding a manual process to tailscale automation that I'm sure we'd all like to remove. Appreciate any info ya'll can provide -- thanks!

[willnorris]

@willnorris any update or timeline on the oauth work?

hmmm, yeah I think we can do that. Lemme go click some buttons. brb

[willnorris]

OAuth is now available (in beta) for all tailnets: https://tailscale.com/blog/oauth/

[ItalyPaleAle]

Nice!!! 🎉 Thanks a lot @willnorris and folks!

[rogierlommers]

Highly appreciated! I think I can use this during my CICD pilelines (github actions being able to SSH into my server).

[willnorris]

With the launch of OAuth support, I'm going to go ahead and close this issue as complete. There were a few additional ideas surrounding APIs to manage keys which we may look at adding in the future, but for now we think we can handle most use cases with the current implementation.

[ericsampson]

Thank you all!! woot