[Feedback tracking] Fine-grained personal access tokens

[hpsin]

This topic serves as an area for feedback and discussion on the new fine-grained personal access tokens format, launched on October 18th. It includes more permissions, mandatory expirations, and organization + repository scoping. You can find more details in the blog post and the documentation.

There are some limits to fine-grained PATs that we'll be addressing in the coming months:

• Multi-organization support, including collaborator support, inner-source, and open-source

Recently, we've added:

• APIs to allow organization owners to programmatically manage the PATs that target their organization
• Support for GraphQL

There are also some APIs that do not yet support the fine-grained permission model, that we'll be adding support for in time:

• Packages
• Projects
• Notifications

Please let us know what you'd love to see in this new token type, what worked for you, and what didn't. Thank you!

[Jackenmen]

I'm wondering, is there/will there be a way to create a fine-grained token for a repository one has collaborator permissions on? Such repositories don't seem to appear in the repository list, and no separate entries on the resource owners list are shown for such repositories.

[dvklopfenstein]

I also would like to use fine-grained tokens on a repo where I push as a collaborator.

The repo is not associated with any organizations.

I am currently using "classic tokens" as a work-around, but wish to use fine-grained.

[fffergal]

I would also really like to use fine grained tokens on personally owned repositories I am only a collaborator on. I only need git read access, if it's easier to start with one feature instead of all. I don't have admin of the repos so can't make a deployment SSH key, so I am using a classic token, when a fine grained token would make more sense. The situation is contracting work where I am setting up build and deployment including pulling from git, but customers feel better if they don't have to give me full admin access.

[Saklad5]

Could this be extended to SSH keys as well? My work keys don't really need access to my personal repositories, and vice versa.

I'd also like the ability to use GnuPG authentication subkeys for SSH without adding them separately, but that's another issue. Scoping them on a subkey-by-subkey basis would still be an improvement.

[sethamclean]

Is it possible to require an SSH CA, disabling private ssh keys and old style tokens while retaining the ability to use fine grained tokens that are managed by our organization?

[s-marinkovic]

+1 For this. Is it possible to require SSH Certificates and use Fine Grained access tokens?

[hpsin]

Partially. You can require SSH CAs for all git access, and that doesn't block FG PAT access to the APIs. The SSH CA requirement only applies to the git protocol.

Are you looking for, instead, the ability to use FG PATs or an SSH CA via the git protocol, but not personal keys or PATs (classic)?

[Gygysik33]

Hello mate

[DanTheMan827]

Will there be a way to create tokens that don't expire for CI?

[laurenty]

Ignoring the lack of tooling for automation for now, better manual tools would help with FGPAT rotation.
On existing FGPATs, there is a "regenerate token" button, but it instantly invalidates the old one which isn't useful for rotation.Something similar to what AWS does for rotation of IAM credentials (allows 2 access keys) would help.
Another option could be to add a "duplicate" feature on FGPATs, so that permissions and repository scopes don't have to manually be selected.

[marten-seemann]

The mandatory expiration is what's preventing me from using FGPAT. I'd like to use them to give my personal website (which gets updated every blue moon) access to a private repo that contains the code for the site.

I'm sure I'll forget to renew the token (if not next year, then the year after), will have forgotten about the intricacies of the setup, and then spend hours debugging why changes don't get deployed after a year.

Happy to hear suggestions for a better workflow for this use case. And no, "create a reminder in your calendar, then renew the token and update your web server configuration in 11.5 months" doesn't qualify as one.

[brian6932]

This seems like a very counter productive thing, why would you add mandatory expiration on something that's meant to be a replacement in many ways to standard PATs to further scope tokens for better security (perfect for CI/CD workflows)? I understand that it's in ""Beta"", but this doesn't make sense. We are so back bros.

[mnapoli]

I keep creating classic tokens because of this 🤦

I want to use the new fine-grained tokens but for CI I cannot update the CI every year, that makes no sense!

[hpsin]

Today we've lifted the 366 day requirement for fine-grained PATs. The restriction remains in place for orgs and enterprises, but you can now create infinite lifespan tokens for your personal projects https://github.com/orgs/community/discussions/141929

[davidcorrigan714]

Is there an API for creating these access tokens? Been playing with Hashicorp Vault and would love to use these tokens to build a Vault Secrets Engine plugin.

[ps-jay]

I'm using https://github.com/martinbaillie/vault-plugin-secrets-github - it works really well.

[ranok]

I'd love to see an API to create fine-grained tokens, it looks like the PAT token API was sunset (now 404s), but there is no way to create down-scoped tokens that last longer than 1hr!

[smheidrich]

For anyone who wants to create fine-grained tokens programmatically without the App workaround, here is a hacky solution that just simulates a user clicking through GitHub's web interface: https://smheidrich.gitlab.io/github-fine-grained-token-client/ (Python library & CLI)
Obviously I would prefer a proper API as well.

[zkamvar]

I was hoping for some way to create a token with specific permissions in a low-rent way such as URL parameters (e.g. https://github.com/settings/tokens/new?scopes=public_repo&description=test%20token for a public repository-scoped token that is called "test token"). This was a nice method of doing it because the person who needs to generate the token needs to authenticate themselves in the browser and they do not need to build a bot or trust a bot.

[ljharb]

Expiry means I can't set it and forget it, and that's the entire point of granular access tokens - namely, the risk is zero because the permissions are tightly scoped.

Forced expiry also means folks will just come up with trivial ways to reissue new ones, which will defeat the purpose anyways. It's like a forced password reuse policy - it seems like it helps security, but it actually harms it.

I hope you'll reconsider forced expiry.

[thedoggybrad]

I suggest to Github to consider adding a no expiry option but first popup a notice that has an agree or disgaree button like a waiver that selecting this option can be dangerous and it can be possible to only allow this option only if a single repository has been selected.

But for now I am just using the classic PAT until the time when there will be no expiry option on the Fine-Grained PAT.

[not-matt]

+1 on this. I was setting up a fine grained access token with tight permissions for exactly what was required, but instead opted for a classic token simply because I need it to last more than a year... losing all the security benefits offered by a fine access token.

[29039]

At least allow the same token to be renewed (even if already expired) rather than regenerating it.

[distinctdan]

Yeah this is worthless without a "No Expiration" option. I can't be having my tools randomly stop working because their tokens expire.

[hpsin]

Today we've lifted the 366 day requirement for fine-grained PATs. The restriction remains in place for orgs and enterprises, but you can now create infinite lifespan tokens for your personal projects https://github.com/orgs/community/discussions/141929

[AdnaneKhan]

In order to facilitate transitioning between classic PATs and fine-grained, will it be possible to enable classic PAT functionality for specific users, but disable them for all others?

It makes the transition a lot more manageable from a security perspective if organizations could disable classic PATs for standard users, but keep them enabled for users that have tokens created that are integrated into automated systems that will take time to migrate.

[hpsin]

Thanks @AdnaneKhan - certainly a valid use case! We'd love to help organizations move off of classic PATs, and you've exactly described how we'd do this. We'd look at org-level and repo-level permissions for users that would give them the ability to bypass the restriction on PATs (classic) in that specific context. I don't have a date for you on this, but it's definitely something we'd like to build.

[mbainter]

It would also be nice if there were some way to "approve" existing keys, but not allow new ones to be created, with a view of what tokens are currently allowed so you can iteratively help people migrate over. That's a big additional ask I'm sure, but if you're going to implement the above maybe that's something that could be incorporated.

[AdnaneKhan]

@mbainter I believe if an Enterprise Org has SAML SSO enabled and enforced, you can use https://api.github.com/orgs/ORG/credential-authorizations to get a view of all classic PATs that have access to an org and their scopes. Could potentially combine that with auto-revoke logic (for the SAML SSO grant) if a user isn't allow-listed. Kind of a hack, but it would work!

[greschd]

Loving the feature 🎉 Of the listed things on the roadmap, multi-org support and packages (GHCR) API would be very useful!

Regarding the token expiry, is there some way to get notified ahead of time?

[davidcorrigan714]

Is there an actual rotation feature now??? The old one had "regenerate" which doesn't allow any overlap and then reset the SSO authorization so to do a true rotation you have to recreate a new one from scratch.

[greschd]

We send reminder emails

Good to know, thanks! Who do these go out to? The token creator, repo / org owner, or both? Is it somehow configurable?

[tarebyte]

Who do these go out to?

These go out to the token owner not the organization.

Is it somehow configurable?

Currently not.

[greschd]

Thanks for the info!

[Gitnitdun]

Y'all are hacking me

[melaniesaraj]

Ahhh I just spent half of my day trying to use a fine-grained token to download a private package; I overlooked the note with the list of unsupported API endpoints in this section of the documentation. I didn't figure it out until I saw the bullet points at the end of this thread!

That was pretty clearly user error, but I'm posting this to see if this was a common mistake others encountered, in which case it could be useful for User Experience to take another look and see if this info could be made more prevalent. For example, maybe it could be presented outside of a box or in a red "warning" box. Or the bullet point could be less verbose (separate out the link to the supported endpoints); or the sub-list items could exclude the extra words "REST API to manage", making them easier to process. But I think my main source of confusion was that when I was reading too quickly and I saw "only work with personal access tokens (classic)", I thought it was going to be a list of things that only work with PATs. So it might be clearer to frame it instead as things that "are not supported for fine-grained personal access tokens".

[dgholz]

Yeah, it's especially confusing that the UI for generating a new fine-grained PAT allows you to add Package permissions, which largely won't work in the way the user expects

[melaniesaraj]

Yes, that was another thing that led me astray, thanks for pointing it out! IMO that option should be hidden for now or conspicuously clarified.

[hpsin]

So sorry you hit this issue! We're removing the Packages permission until it's better supported.

[nbibler]

Just to add: I certainly attempted to create a fine-grained, organization-owned PAT with hopes of generating a read-only permission to use with GitHub Actions and Dependabot.

This would solve a lot of security gaps with the traditional PATs (ownership with the Org rather than an org member, token-level restriction to specific repositories rather than access to all with access "controlled" via secrets access restriction, etc.). But alas, this looks to be currently unsupported.

I, too, missed the call outs in the documentation.

Looking forward to this use-case someday becoming a reality!

[larshp]

according to https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/

In the new Personal Access Tokens tab in the Organization Settings, Organization Owners can choose to approve each fine-grained PAT that developers target at that Organization or any of its repositories. This option is enabled by default.

However on the organization page,

this seems to be a mismatch? am I reading this wrong?

[larshp]

ah, that section is only regarding the approval and auditing

the "Get Started" tells that the feature is disabled for all organizations by default

[hpsin]

Right, in the public beta we are not enabling organization access with fine-grained PATs by default, as it requires a new set of auditing processes that companies wouldn't have in place. Thus, organizations need to opt-in to this new token type. We'll update this when fine-grained PATs go to general availability, such that organizations and enterprises that haven't explicitly enabled or disabled this will have it enabled for them.

[Afiq186]

menurut https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/

Dalam tab Token Akses Peribadi baharu dalam Tetapan Organisasi, Pemilik Organisasi boleh memilih untuk meluluskan setiap PAT halus yang disasarkan oleh pembangun pada Organisasi itu atau mana-mana repositorinya. Pilihan ini didayakan secara lalai.

Walau bagaimanapun pada halaman organisasi,

ini nampaknya tidak sepadan? adakah saya salah membaca ini?

[bobby-lin-cdc]

Will be nice to have source IP restriction on GH token similar to AWS IAM Roles (https://aws.amazon.com/premiumsupport/knowledge-center/iam-restrict-calls-ip-addresses/)

[hpsin]

We don't support per-token IP restrictions, but we do support enterprise-wide and organization-wide IP allowlists for all access, which does cover the use of PATs. If you want granularity at the per-user level for IP allowlists, you may be able to check out the IdP-driven IP allowlist feature that's in beta for Azure AD backed Enterprise Managed Users, which will use your per-user CA policies in AAD to enforce IP range restrictions on PATs and user sign-ins.

[jyxjjj]

We don't support per-token IP restrictions, but we do support enterprise-wide and organization-wide IP allowlists for all access, which does cover the use of PATs. If you want granularity at the per-user level for IP allowlists, you may be able to check out the IdP-driven IP allowlist feature that's in beta for Azure AD backed Enterprise Managed Users, which will use your per-user CA policies in AAD to enforce IP range restrictions on PATs and user sign-ins.

Please clarify don't or won't, I don't think a personal open source developer have enough money to do anything like a company or buy something like Azure. And you seems misunderstood why we need IP based authentication for personal access token.
In my usage, GitHub API is a good thing to subscribe software updates via call the releases or commits or tags endpoint to generate an automatically notification, a little like what dependabot did.
And due to store methods and the reason i said above, users will not buy something like Azure Vault too for personal usage.
Open source users and developers will not earn money, we develop things for love.
If GitHub only wants to earn money from companies, I don't know what to say.
You can prove if GitHub want's to support it later, or won't at all.
(I didn't say you one people sir, i mean your teams.)

[radeksimko]

The mandatory expiration makes sense for human-oriented use cases - e.g. testing some scripts, locally running programs which interact with GitHub API etc. I have had a number of tokens I created in the past which I only discovered as still active some months or years later.

However, for tokens which are used by machines - such as in a CI - the manual rotation seems like unnecessary overhead, as was already mentioned.

Contrary to some suggestions made here though, I would say that instead of just allowing no expiry, it would make sense to somehow allow establishment of a trust relationship, such that GitHub backend does the token rotation and humans don't even need to ever see the token, let alone copy and paste it - hence further decreasing the chance of leaks. This would make sense IMO at least for the common case when the token is used within GitHub Actions.

GitHub already essentially does that with the default GITHUB_TOKEN variable, which receives permissions based on the permissions block in the workflow file: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs

I don't know what the best UX for cross-org and cross-repo tokens is, but perhaps there's some inspiration to take from impersonation mechanisms in GCP, AWS or HashiCorp Vault? Active trust relationships is probably something users would still need to be reminded of regularly, but at least it takes a lot of the overhead away and arguably makes it safer by not exposing the token to humans.

[asmeurer]

Would it make sense for the expiration to be based on time of the token being inactive? I'd be fine with a one-off token that I generated for some script to automatically disable itself after a month. But it's something that I actually do use regularly, having to regenerate it even every 3 months becomes a serious hassle.

[mrgrain]

I like this idea! All I really need is to tell GitHub to put a fine-grained PAT into the environmental variable MY_TOKEN in the repo me/my_repo. And that PAT can be updated every week, or even more often! I'd even be okay with a semi-manual request to re-approve the access every X days.

The approach with GitHub Apps works fine, except in reality users are now just adding a private key to a bunch of repos and that is even less likely to get rotated.

[dgholz]

Would it make sense for the expiration to be based on time of the token being inactive?

It wouldn't, the main reason to have expiry dates on authentication credentials like PATs is to limit the amount of time that a stolen/leaked credential can be used.

Most every other authentication credential system (AWS, regular OAuth) has built-in support for refreshing a token to get a new one & invalidate the old; for some reason, GitHub PATs do not have any refresh mechanism, and no support for managing them in the API. Quite remarkable!

[29039]

At least allow the same token to be renewed (even if already expired) rather than regenerating it.

[singhprd]

A missing feature for me is being able to authenticate against GitHub packages.

Currently (buried in the docs for packages):

GitHub Packages only supports authentication using a personal access token (classic). For more information, see "Creating a personal access token."

https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages

This is compounded by the fact that apps also can't install packages.

And also by the confusing UI whereby we can add a package scope to repositories with 'fine-grained tokens':

☝️ That text sounds like you you can authenticate against GitHub packages!

This is overall a great change and thanks for your hard work getting it into beta!

🚀

[hpsin]

This is being removed until we have support from Packages for fine-grained PATs, sorry about the confusion here!

[singhprd]

No worries, thanks for the fast response! It's still the first few days of beta! 😄 🚀

[reiniertimmer]

Does this mean that the fine-grained PATs can also be used (in the future) with packages using native clients, like mvn or npm, and not just the REST API endpoints?

[hpsin]

@reiniertimmer , those native clients should just be calling the REST APIs behind the scenes, so yep, you'll be able to use it there too!

[LukeAskew]

@hpsin Any update on support of Packages? This is a pretty significant piece of missing functionality. It prevents my org from using Packages altogether.

[ViacheslavKudinov]

Hello,
are there any plans to have API to regenerate/rotate these fine-grained or even classic tokens?
Especially it is good to have for fine-grained as they by design have expiration day (not forever).

PS Am I "blind" to find and it is in place?