Note
Fine-grained personal access token are currently in public preview and subject to change. To leave feedback, see the feedback discussion.
During the public preview, enterprises must opt in to fine-grained personal access tokens. If your enterprise has not already opted-in, then you will be prompted to opt-in and set policies when you follow the steps below.
Organizations within an enterprise can opt in to fine-grained personal access tokens, even if the enterprise has not. All users, including Enterprise Managed Users, can create fine-grained personal access tokens that can access resources owned by the user (such as repositories created under their account) regardless of the enterprise's opt in status.
Restricting access by personal access tokens
Enterprise owners can prevent their members from using personal access tokens to access resources owned by the enterprise. You can configure these restrictions for personal access tokens (classic) and fine-grained personal access tokens independently with the following options:
- Allow organizations to configure access requirements: Each organization owned by the enterprise can decide whether to restrict or permit access by personal access tokens.
- Restrict access via personal access tokens: Personal access tokens cannot access organizations owned by the enterprise. SSH keys created by these personal access tokens will continue to work. Organizations cannot override this setting.
- Allow access via personal access tokens: Personal access tokens can access organizations owned by the enterprise. Organizations cannot override this setting.
Regardless of the chosen policy, Personal access tokens will have access to public resources within the organizations managed by your enterprise.
- In the top-right corner of GitHub, click your profile photo.
- Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
- On the left side of the page, in the enterprise account sidebar, click Policies.
- Under Policies, click Personal access tokens.
- Select either the Fine-grained tokens or Tokens (classic) tab to enforce this policy based on the token type.
- Under Fine-grained personal access tokens or Restrict personal access tokens (classic) from accessing your organizations, select your access policy.
- Click Save.
Enforcing a maximum lifetime policy for personal access tokens
Enterprise owners can set and remove maximum lifetime allowances for both fine-grained personal access tokens and personal access tokens (classic) to help protect enterprise resources. Organization owners within the enterprise can further restrict the lifetime policies for their organizations. See "Enforcing a maximum lifetime policy for personal access tokens".
For fine-grained personal access tokens, the default the maximum lifetime policy for organizations and enterprises is set to expire within 366 days. Personal access tokens (classic) do not have an expiration requirement.
Policy enforcement details
For Enterprise Managed Users, the enterprise-level policies apply to user namespaces as well because the enterprise owns the user accounts.
The policies around maximum lifetimes are enforced slightly differently for fine-grained personal access tokens and personal access tokens (classic). For tokens (classic), enforcement occurs when the token is used and when SSO credential authorization is attempted, and errors will prompt users to adjust the lifetime. For fine-grained personal access tokens, the target organization is known at the time of token creation. In both cases, users will be prompted to regenerate tokens with compliant lifetimes if the current one exceeds the policy limit.
When you set a policy, tokens with non-compliant lifetimes will be blocked from accessing your organization if the token belongs to a member of your organization. Setting this policy does not revoke or disable these tokens. Users will learn that their existing token is non-compliant when API calls for your organization are rejected.
Setting a maximum lifetime policy
- In the top-right corner of GitHub, click your profile photo.
- Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
- On the left side of the page, in the enterprise account sidebar, click Policies., then click Personal access tokens.
- Select either the Fine-grained tokens or Tokens (classic) tab to enforce this policy based on the token type.
- Under Set maximum lifetimes for personal access tokens, set the maximum lifetime. Tokens must be created with a lifetime less than or equal to this many days.
- Optionally, to exempt your enterprise administrators from this policy, check the Exempt administrators checkbox. You should exempt them from this policy if you use SCIM for user provisioning or have automation that has not migrated to GitHub App yet.
Warning
If you use Enterprise Managed Users, you will be asked to accept the risk of service interruption unless you exempt your enterprise administrators. This ensures you are aware of the potential risk.
- Click Save.
Enforcing an approval policy for fine-grained personal access tokens
Enterprise owners can manage approval requirements for each fine-grained personal access token with the following options:
- Allow organizations to configure approval requirements: Enterprise owners can allow each organization in the enterprise to set its own approval requirements for the tokens.
- Require approval: Enterprise owners can require that all organizations within the enterprise must approve each fine-grained personal access token that can access the organization. These tokens can still read public resources within the organization without needing approval.
- Disable approval: Fine-grained personal access tokens created by organization members can access organizations owned by the enterprise without prior approval. Organizations cannot override this setting.
Note
Only fine-grained personal access tokens, not personal access tokens (classic), are subject to approval. Any personal access token (classic) can access organization resources without prior approval, unless the organization or enterprise has restricted access by personal access tokens (classic) For more information about restricting personal access tokens (classic), see "Restricting access by personal access tokens" on this page and "Setting a personal access token policy for your organization."
- In the top-right corner of GitHub, click your profile photo.
- Depending on your environment, click Your enterprise, or click Your enterprises then click the enterprise you want to view.
- On the left side of the page, in the enterprise account sidebar, click Policies.
- Under Policies, click Personal access tokens.
- Select the Fine-grained tokens tab.
- Under Require approval of fine-grained personal access tokens, select your approval policy:
- Click Save.