[Proposal] Redesign Scoped Personal Access Tokens (PATs) / Fine Grained Personal Access Tokens #10773

New Issue

GiteaMirror · 2025-11-02T09:17:46-06:00

GiteaMirror commented

2025-11-02 09:17:46 -06:00

Originally created by @kdumontnu on GitHub (May 3, 2023).

Feature Description

There are a number of issues with scoped access tokens currently, ranging from UI/UX to implementation.

The gitea implementation of scoped PATs was clearly based off of GitHub's original implementation, which inherits some issues:

GH's token scopes never really made sense and have since been depricated
- You couldn't give separate read vs write permissions to repos
- They were always ambiguous as to what the scopes gave access to

Additionally, our implementation had to map the odd GH scopes to our API routes, which further complicates the implementation, and leaves reqToken calls sprinkled around the code (which introduces bugs now and will be difficult to maintain going forward).

Consider that we already have a nice hierarchy of scopes introduced by the API - imo, there is no reason to remap these to arbitrary GH scopes. I propose the following high-level scopes:

activitypub
admin (hidden if user is not a site admin)
misc
notification
organization
package
issue
repository
user

The for each of the above we have an option for:

read
write
delete

We also add an option at the top for:

only public repositories / orgs

This will be significantly easier for users to understand and for us to document and maintain, and it more closely matches the direction GitHub is moving.

While we're here, some further improvements:

By default in the UI, scopes are collapsed, meaning that if a user just creates a PAT without expanding the hidden scopes, they won't have access to anything (or will it? it's unclear what "no scopes" implies).
- Solution: if no scopes literally gives access to nothing, the "create" button should be disabled if no scopes are selected.
- if no scopes gives access to something, we should have a "scope" that explains what that access is, and is always checked.
- edit: apparently default is all, but the shows Scopes: (empty)' and not all`
Tooltips & documentation embedded in the scoped access tokens UI
In GH, if you selected a higher level scope (eg. "repo") it would automatically check the lower level scopes (eg. repo:status and public_repo), however, it does not for us. So what happens if I select repo ("Full control over all repositories."), but not "repo:status")?
- Solution: selecting a higher level scope should select all of the lower level scopes
User shouldn't be able to select scopes they themselves do not have access to. It's confusing and misleading. We should disable those options.
Allow to set a expiry on tokens
Allow to scope to repo

Screenshots

eg.

Originally created by @kdumontnu on GitHub (May 3, 2023). ### Feature Description There are a number of issues with scoped access tokens currently, ranging from UI/UX to implementation. The gitea implementation of scoped PATs was clearly based off of GitHub's original implementation, which inherits some issues: - GH's token scopes never really made sense and have since [been depricated](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/) - You couldn't give separate read vs write permissions to repos - They were always ambiguous as to what the scopes gave access to Additionally, our implementation had to map the odd GH scopes to our API routes, which further complicates the implementation, and leaves `reqToken` calls sprinkled around the code (which introduces bugs now and will be difficult to maintain going forward). Consider that we already have a nice hierarchy of scopes introduced by the API - imo, there is no reason to remap these to arbitrary GH scopes. I propose the following high-level scopes: - `activitypub` - `admin` (hidden if user is not a site admin) - `misc` - `notification` - `organization` - `package` - `issue` - `repository` - `user` The for each of the above we have an option for: - `read` - `write` - `delete` We also add an option at the top for: - only public repositories / orgs This will be significantly easier for users to understand and for us to document and maintain, and it more closely matches the direction GitHub is moving. While we're here, some further improvements: - By default in the UI, scopes are collapsed, meaning that if a user just creates a PAT without expanding the hidden scopes, they won't have access to anything (or will it? it's unclear what "no scopes" implies). - Solution: if no scopes literally gives access to nothing, the "create" button should be disabled if no scopes are selected. - if no scopes gives access to something, we should have a "scope" that explains what that access is, and is always checked. - edit: apparently default is `all`, but the shows Scopes: `(empty)' and not `all` - Tooltips & documentation embedded in the scoped access tokens UI - In GH, if you selected a higher level scope (eg. "repo") it would automatically check the lower level scopes (eg. `repo:status` and `public_repo`), however, it does not for us. So what happens if I select `repo` ("Full control over all repositories."), but not "repo:status")? - Solution: selecting a higher level scope should select all of the lower level scopes - User shouldn't be able to select scopes they themselves do not have access to. It's confusing and misleading. We should disable those options. - Allow to set a expiry on tokens - Allow to scope to repo ### Screenshots eg. ![image](https://user-images.githubusercontent.com/12700993/235945690-aad630e6-558a-4dd9-8d79-8dc9e109b27b.png)

GiteaMirror added the type/proposal type/feature labels 2025-11-02 09:17:46 -06:00

GiteaMirror closed this issue

2025-11-02 09:17:47 -06:00

GiteaMirror commented

2025-11-02 09:17:47 -06:00

@harryzcy commented on GitHub (May 3, 2023):

In general, I agree that we can have an improved scoping.

I implemented the token scope, so to answer a few questions:

By default in the UI, scopes are collapsed, meaning that if a user just creates a PAT without expanding the hidden scopes, they won't have access to anything (or will it? it's unclear what "no scopes" implies).

no scope means you can access any information that's publicly available, just like you can browse gitea website without login. Anything that requires login are not accessible.
The default for newly created token is empty. Only for tokens already created before v1.19.0, the scope is set to all during migration for backward compatibility.

In GH, if you selected a higher level scope (eg. "repo") it would automatically check the lower level scopes (eg. repo:status and public_repo), however, it does not for us. So what happens if I select repo ("Full control over all repositories."), but not "repo:status")?

It's a UI issue and should be fixed. On the backend, lower level scopes are actually enabled.

I think the routes require some cleanup too and we should order then based on hierarchy. Currently, a few endpoints are scattered in different groups. That makes it harder to maintain.

@harryzcy commented on GitHub (May 3, 2023): In general, I agree that we can have an improved scoping. I implemented the token scope, so to answer a few questions: > By default in the UI, scopes are collapsed, meaning that if a user just creates a PAT without expanding the hidden scopes, they won't have access to anything (or will it? it's unclear what "no scopes" implies). `no scope` means you can access any information that's publicly available, just like you can browse gitea website without login. Anything that requires login are not accessible. The default for newly created token is empty. Only for tokens already created before v1.19.0, the scope is set to `all` during migration for backward compatibility. > In GH, if you selected a higher level scope (eg. "repo") it would automatically check the lower level scopes (eg. repo:status and public_repo), however, it does not for us. So what happens if I select repo ("Full control over all repositories."), but not "repo:status")? It's a UI issue and should be fixed. On the backend, lower level scopes are actually enabled. I think the routes require some cleanup too and we should order then based on hierarchy. Currently, a few endpoints are scattered in different groups. That makes it harder to maintain.

GiteaMirror commented

2025-11-02 09:17:47 -06:00

@kdumontnu commented on GitHub (May 3, 2023):

Thanks for the followup @harryzcy! I'm working with @jackHay22 on refactoring some of these items. It would be great to have your help implementing/reviewing.

What do you think about refactoring the scopes to align more with the API routes?
As a followup, we could even introduce "fine-grained" scopes that actually match to specific API routes (maybe using wildcards?), but this is a bigger proposal we could discuss later.

@kdumontnu commented on GitHub (May 3, 2023): Thanks for the followup @harryzcy! I'm working with @jackHay22 on refactoring some of these items. It would be great to have your help implementing/reviewing. What do you think about refactoring the scopes to align more with the API routes? As a followup, we could even introduce "fine-grained" scopes that actually match to specific API routes (maybe using wildcards?), but this is a bigger proposal we could discuss later.

GiteaMirror commented

2025-11-02 09:17:47 -06:00

@harryzcy commented on GitHub (May 3, 2023):

@kdumontnu Scopes that align with API routes are much easier to understand. Totally agreed.
I'm not sure what your status is. If you have a PR at some point, feel free to @ me.

If we want to support "fine-grained" scopes, we probably should leave room for it when designing the token pattern. Matching the repo names or even the specific routes could be options. The actually implementation could be for another PR.

@harryzcy commented on GitHub (May 3, 2023): @kdumontnu Scopes that align with API routes are much easier to understand. Totally agreed. I'm not sure what your status is. If you have a PR at some point, feel free to @ me. If we want to support "fine-grained" scopes, we probably should leave room for it when designing the token pattern. Matching the repo names or even the specific routes could be options. The actually implementation could be for another PR.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#10773