Epic: Personal Access Tokens

[easyCZ]

Summary

To enable automated interaction with Gitpod, users need the ability to manage their Personal Access Tokens.

Context

Personal Access Tokens are API tokens which act on behalf of the user. They can be used to automate workflows against Gitpod.

Value

• Integration on API level
• Enables extensibility of Gitpod
• Complements our efforts to introduce the Public API

Acceptance Criteria

The user is able to:

• Create Access Token
• Rotate an Access Token
• List Tokens
• Delete a Token

Measurement

• We will measure proportion of traffic against Gitpod with API keys vs regular dashboard sessions

RFC

• internal RFC

User stories

1. As a user, I want to add a token with a name, an expiry date, and scopes, so that I can use it to authenticate
   Note: Properties here
2. As a user, I want to see the token that I have just created.
3. As a user, I want to see the tokens that I have created, when it expires, and when it was used.
   Note: without seeing the secret value
4. As a user, I want to delete a token so that I can revoke permissions
5. As a user, I want to regenerate a token (for any reason) and see the new token.
6. As a user, I want to update the scopes of an existing token.
7. As a user, I want to authenticate to Gitpod API using my existing token.

Milestone plan

• 1 week of API implementation
• 1 week of UI implementation
• 1 week of validation
  Note: UI and API implementation can be started independently

Diagram

Storage

Will be stored in a new table d_b_personal_access_token.
Reasons why we are not using the existing d_b_gitpod_token:

• Does not fit the new usecase
• Allows simpler migration path in the future

(additional contexts[1][2])

Schema

--	field	type
primary key, idx	id	varchar
idx	user_id	varchar
idx	hash	varchar
	name	varchar
	description	text
	scopes	text
	expiration_time	timestamp
	created_at	timestamp
idx	last_modified	timestamp
	deleted	boolean

Issues

• Technical breakdown of Gitpod Personal tokens #14465
• [public api] Proto definitions for tokens #14523
• [public api] Wire up UnimplementedTokensService #14627
• Implement server API to check if a User has permission to operate on a token #14619
• Implement GetPersonalAccessToken RPC #14609
• Implement ListPersonalAccessTokens RPC #14610
• Implement RegeneratePersonalAccessToken RPC #14611
• Implement CreatePersonalAccessToken RPC #14602
• Implement UpdatePersonalAccessToken RPC #14612
• Implement DeletePersonalAccessToken RPC #14613
• Implement empty PersonalAccessToken page in the dashboard #14614
• Implement token creation page/modal #14615
• Implement token regeneration UI #14616
• Implement scopes update UI #14617
• Implement delete token UI #14618
• Implement List tokens UI #14860
• Remove description field from PAT #14900
• Ensure observability for Personal Access Tokens feature & add SLO #14911
• Server & Public API Accept PATs when authorizing requests #14912
• Handle PATs UI loading states #14944
• Show errors when interacting with PATs #14945
• Add client-side validation for PATs name #14946
• Highlight expired PATs in ListView #14947
• Fix tokens page visit #14972
• Design improvements for the personal access tokens page and flow #15002
• List all (or paginate) access tokens view #15098
• Improve expiration time UX #15103
• Reduce Regenerate Token UI density #15104
• Updating a Token without any field modifications returns a Not Found #15105

Rollout

• Behind a feature flag for specific users or percentage of users.
• Documentation for Personal Access Tokens #14910
• Include a link to the documentation

Documentation

https://www.gitpod.io/docs/configure/user-settings/access-tokens

Follow-up

Follow-up epic which tracks feedback, improvements and general direction towards a stable release is in

• Epic: Personal Access Tokens v1.1 #15100

[gtsiolis]

Adding this to the product design board. 🎹

Cross-linking relevant discussion (internal):

Regarding the Gitpod Tokens: RFC (internal), we used to have a similar functionality in the dashboard before the redesign last year (see API Tokens section in relevant discussion), which was not widely used and we decided to drop during the dashboard redesign.

There’s already an issue with design specs for this section, named loosely Access Tokens, (see #3399) thought which we could use as a base for this iteration taking into account the decisions or needs described in the RFC once approved and updating the designs, copy, and structure.

[laushinka]

we used to have a similar functionality in the dashboard before the redesign last year

There’s already an issue with design specs for this section, named loosely Access Tokens, (see #3399) thought which we could use as a base for this iteration

Thanks for the context, @gtsiolis!
Looking at the past designs briefly we could use the same base. Some WIP to keep in mind:

• Creation will require more input than just name, but also description, scopes, expiration time. Depending on the length of scopes list, it might affect whether we use a modal on creation.
• List of tokens shows more details e.g. when it expires, maybe when it was last used.
• Each token can be deleted, regenerated, or (scopes) updated.

Will post updates in this epic.

[laushinka]

the RFC once approved

@gtsiolis RFC is accepted 👍🏼

[gtsiolis]

Thanks for the heads-up, @laushinka!

Regarding the context in #14280 (comment), I haven't read the RFC in-depth yet but the list of options listed there looks long. Should we consider breaking the list of features into smaller pieces as MVC skateboards to avoid scope creep?

Cc @easyCZ

[easyCZ]

@laushinka is doing the breakdown currently. Once we have that, we we will of course slice it up, or choose to defer some parts of it.

As it stands, the only aspect that can be deferred is "fine grained scopes". From the user stories, it's necessary to offer the token lifecycle and the corresponding authentication pieces as without them, the feature does not actually yield the value we want.

[gtsiolis]

@easyCZ Perfect, sounds good! I'll dive into more designs for this features in the next few days.