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.

[akosyakov]

@gtsiolis Is there a design available?

[gtsiolis]

@akosyakov I'm currently working on this. I'm planning to upload some early designs today. Any feedback or something that designs should take into account, besides the relevant RFC (internal)?

[akosyakov]

@gtsiolis nope it just we wanted to start to work on it. If we do some cross cutting slices it would be good to have some ideas about UI.

[gtsiolis]

Posting some early designs for the personal access tokens (PATs) flow, including 1️⃣ the empty state and 2️⃣ the new token modal. I’ll add later today, 3️⃣ the new token confirmation and 4️⃣ the listing of existing tokens. Cc @laushinka @easyCZ

1️⃣ No tokens	2️⃣ New token

See design specs.

[tdensmore]

Quick question about the "Permissions" checkbox: does this need to be checked for the PAT to work as expected? If not, what are the default permissions? I have seen these split into USER and ADMIN options for other products, but maybe that does not apply yet since we are still building out our public API set?

[gtsiolis]

Hey @tdensmore! Cross-posting from the relevant discussion (internal) for visibility:

@easyCZ: For the Token Create - the scopes:

• Initially we should include a checkbox which says "Grant all my permissions to this PAT". This acts as a "grant all" special token and explicitly acknowledges that is what the token will be able to do
• This allows us to then later introduce more fine-grained scopes in subsequent iterations

[gtsiolis]

Adding below more design specs for the token creation.

Creating the first token	Refreshing the list	Creating the second token

More actions on a token	Editing a token	Deleting a token

For the token creation, an alternative approach could be to use a modal for nudging users to copy the token:

Creating the token (Alternative)

[jimmybrancaccio]

I wonder if it's worth using a yellow alert component for the "nudge" text. I like the alternative with the modal too - but perhaps remove the footer of the model since there's already a copy button/function in the text field.

Look great though, really nice job!

[gtsiolis]

Thanks for the feedback @jimmybrancaccio!

I'd avoid relying on the alert component for everything we add as this could be overwhelming for users. We're already using a lot of alerts for other cases like local preview, usage limit, etc.

For the latest designs, we're leaning towards a non-modal approach as it would scale better with more permissions that we'd like to add over time, see relevant discussion (internal). Feedback is welcome!

[gtsiolis]

Shall we close this in favor of #15100? Cc @easyCZ @jldec

[easyCZ]

@gtsiolis Currently this epic is in a validation phase. I'd like to keep it open until we've concluded that phase, and have run it for some time.

[gtsiolis]

OK, @easyCZ! I've removed this from product design / in progress board for now, as there's no ongoing product design work for any issues related to this feature. 🤝

[atduarte]

@easyCZ can we close this?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.