diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md index 68c73b213c..64955fd8a6 100644 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md +++ b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md @@ -9,20 +9,16 @@ redirect_from: - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise --- -> [!NOTE] -> {% data reusables.user-settings.pat-v2-beta %} -> -> During the {% data variables.release-phases.public_preview %}, enterprises must opt in to {% data variables.product.pat_v2_plural %}. 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 {% data variables.product.pat_v2_plural %}, even if the enterprise has not. All users, including {% data variables.product.prodname_emus %}, can create {% data variables.product.pat_v2_plural %} 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 {% data variables.product.pat_generic_plural %} Enterprise owners can prevent their members from using {% data variables.product.pat_generic_plural %} to access resources owned by the enterprise. You can configure these restrictions for {% data variables.product.pat_v1_plural %} and {% data variables.product.pat_v2_plural %} 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 {% data variables.product.pat_generic_plural %}. + +* **Allow organizations to configure access requirements:** Each organization owned by the enterprise can decide whether to restrict or permit access by {% data variables.product.pat_generic_plural %}. This is the default setting. * **Restrict access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_generic_caps_plural %} cannot access organizations owned by the enterprise. SSH keys created by these {% data variables.product.pat_generic_plural %} will continue to work. Organizations cannot override this setting. * **Allow access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_generic_caps_plural %} can access organizations owned by the enterprise. Organizations cannot override this setting. +By default, organizations and enterprises allow access by both {% data variables.product.pat_v2_plural %} and {% data variables.product.pat_v1_plural %}. + Regardless of the chosen policy, {% data variables.product.pat_generic_caps_plural %} will have access to public resources within the organizations managed by your enterprise. {% data reusables.enterprise-accounts.access-enterprise %} @@ -62,10 +58,13 @@ When you set a policy, tokens with non-compliant lifetimes will be blocked from ## Enforcing an approval policy for {% data variables.product.pat_v2_plural %} Enterprise owners can manage approval requirements for each {% data variables.product.pat_v2 %} 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. + +* **Allow organizations to configure approval requirements:** Enterprise owners can allow each organization in the enterprise to set its own approval requirements for the tokens. This is the default. * **Require approval:** Enterprise owners can require that all organizations within the enterprise must approve each {% data variables.product.pat_v2 %} that can access the organization. These tokens can still read public resources within the organization without needing approval. * **Disable approval:** {% data variables.product.pat_v2_caps %}s created by organization members can access organizations owned by the enterprise without prior approval. Organizations cannot override this setting. +By default, organizations require approval of {% data variables.product.pat_v2_plural %}, but are able to disable this requirement. Using the settings above, you can force your organizations to have approvals enabled or disabled. + > [!NOTE] > Only {% data variables.product.pat_v2 %}s, not {% data variables.product.pat_v1_plural %}, are subject to approval. Any {% data variables.product.pat_v1 %} can access organization resources without prior approval, unless the organization or enterprise has restricted access by {% data variables.product.pat_v1_plural %} For more information about restricting {% data variables.product.pat_v1_plural %}, see [Restricting access by {% data variables.product.pat_generic_plural %}](#restricting-access-by-personal-access-tokens) on this page and [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). diff --git a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md index 1bd76dab60..a569efd83e 100644 --- a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md +++ b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md @@ -35,20 +35,41 @@ topics: {% data variables.product.company_short %} currently supports two types of {% data variables.product.pat_generic %}s: {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible. +> [!NOTE] +> {% data variables.product.pat_v2_caps %}s, while more secure and controllable, cannot accomplish every task that a {% data variables.product.pat_v1 %} can. See the section on [{% data variables.product.pat_v2_caps_plural %} limitations](#fine-grained-personal-access-tokens-limitations) below to learn more. + Both {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} are tied to the user who generated them and will become inactive if the user loses access to the resource. Organization owners can set a policy to restrict the access of {% data variables.product.pat_v1_plural %} to their organization{% ifversion ghec or ghes %}, and enterprise owners can restrict the access of {% data variables.product.pat_v1_plural %} to the enterprise or organizations owned by the enterprise{% endif %}. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens). #### {% data variables.product.pat_v2_caps %}s -{% data variables.product.pat_v2_caps %}s have several security advantages over {% data variables.product.pat_v1_plural %}: +{% data variables.product.pat_v2_caps_plural %} have several security advantages over {% data variables.product.pat_v1_plural %}, but also have limitations that may prevent you from using them in every scenario. These limits, and our plans to fix them, can be found in the [section below](#fine-grained-personal-access-tokens-limitations). -* Each token can only access resources owned by a single user or organization. -* Each token can only access specific repositories. -* Each token is granted specific permissions, which offer more control than the scopes granted to {% data variables.product.pat_v1_plural %}. +If you can use a {% data variables.product.pat_v2 %} for your scenario, you'll benefit from these improvements: + +* Each token is limited to access resources owned by a single user or organization. +* Each token can be further limited to only access specific repositories for that user or organization. +* Each token is granted specific, fine-grained permissions, which offer more control than the scopes granted to {% data variables.product.pat_v1_plural %}. * Organization owners can require approval for any {% data variables.product.pat_v2 %}s that can access resources in the organization.{% ifversion ghec or ghes %} * Enterprise owners can require approval for any {% data variables.product.pat_v2 %}s that can access resources in organizations owned by the enterprise.{% endif %} +##### {% data variables.product.pat_v2_caps_plural %} limitations + +{% data variables.product.pat_v2_caps_plural %} do not support every feature of {% data variables.product.pat_v1_plural %}. These feature gaps are not permanent - {% data variables.product.company_short %} is working to close them. You can review [our public roadmap](https://github.com/github/roadmap) for more details on when these scenarios will be supported. + +The seven major gaps in {% data variables.product.pat_v2 %}s are: + +* Using {% data variables.product.pat_v2 %} to contribute to public repos where the user is not a member. +* Using {% data variables.product.pat_v2 %} to contribute to repositories where the user is an outside or repository collaborator. +* Using {% data variables.product.pat_v2 %} to access multiple organizations at once. +{% ifversion ghes or ghec %}* Using {% data variables.product.pat_v2 %} to access `internal` resources within an enterprise the user belongs to. +* Using {% data variables.product.pat_v2 %} to call APIs that manage the Enterprise account. +{% endif %}* Using {% data variables.product.pat_v2 %} to access Packages. +* Using {% data variables.product.pat_v2 %} to call the Checks API. + +All of these gaps will be solved over time, as {% data variables.product.company_short %} continues to invest in more secure access patterns. + #### {% data variables.product.pat_v1_caps_plural %} {% data reusables.user-settings.patv2-limitations %} @@ -73,9 +94,6 @@ For more information about best practices, see [AUTOTITLE](/rest/overview/keepin ## Creating a {% data variables.product.pat_v2 %} -> [!NOTE] -> {% data reusables.user-settings.pat-v2-beta %} - {% ifversion fpt or ghec %}1. [Verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address), if it hasn't been verified yet.{% endif %} {% data reusables.user-settings.access_settings %} {% data reusables.user-settings.developer_settings %} @@ -84,7 +102,7 @@ For more information about best practices, see [AUTOTITLE](/rest/overview/keepin 1. Under **Token name**, enter a name for the token. 1. Under **Expiration**, select an expiration for the token. Infinite lifetimes are allowed but may be blocked by a maximum lifetime policy set by your organization or enterprise owner. For more information, See [Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %}](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#enforcing-a-maximum-lifetime-policy-for-personal-access-tokens). 1. Optionally, under **Description**, add a note to describe the purpose of the token. -1. Under **Resource owner**, select a resource owner. The token will only be able to access resources owned by the selected resource owner. Organizations that you are a member of will not appear unless the organization opted in to {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).{% ifversion ghec %} You may be required to perform single sign-on (SSO) if the selected organization requires it and you do not already have an active session.{% endif %} +1. Under **Resource owner**, select a resource owner. The token will only be able to access resources owned by the selected resource owner. Organizations that you are a member of will not appear if the organization has blocked the use of {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).{% ifversion ghec %} You may be required to perform single sign-on (SSO) if the selected organization requires it and you do not already have an active session.{% endif %} 1. Optionally, if the resource owner is an organization that requires approval for {% data variables.product.pat_v2 %}s, below the resource owner, in the box, enter a justification for the request. 1. Under **Repository access**, select which repositories you want the token to access. You should choose the minimal repository access that meets your needs. Tokens always include read-only access to all public repositories on {% data variables.product.prodname_dotcom %}. 1. If you selected **Only select repositories** in the previous step, under the **Selected repositories** dropdown, select the repositories that you want the token to access. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md index d376232071..b7d252e7ff 100644 --- a/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md +++ b/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md @@ -8,8 +8,6 @@ versions: shortTitle: Manage token requests --- -{% data reusables.user-settings.pat-v2-org-opt-in %} - ## About {% data variables.product.pat_v2 %} requests When organization members create a {% data variables.product.pat_v2 %} to access resources owned by the organization, if the organization requires approval for {% data variables.product.pat_v2 %}s, then an organization owner must approve the token before it can be used to access any resources that are not public. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). diff --git a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md index d935c30153..3a1d445d68 100644 --- a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md +++ b/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md @@ -8,15 +8,13 @@ versions: shortTitle: Review token access --- -{% data reusables.user-settings.pat-v2-org-opt-in %} - ## About reviewing and revoking {% data variables.product.pat_v2 %}s Organization owners can view all {% data variables.product.pat_v2 %}s that can access resources owned by the organization. Organization owners can also revoke access by {% data variables.product.pat_v2 %}s. When a {% data variables.product.pat_v2 %} is revoked, SSH keys created by the token will continue to work and the token will still be able to read public resources within the organization. When a token is revoked, the user who created the token will receive an email notification. -Organization owners can only view and revoke {% data variables.product.pat_v2 %}s, not {% data variables.product.pat_v1_plural %}. Unless the organization {% ifversion ghec or ghes %}or enterprise {% endif %}has restricted access by {% data variables.product.pat_v1_plural %}, any {% data variables.product.pat_v1 %} can access organization resources until the token expires. For more information about restricting access by {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise){% endif %}. +Organization owners can only view and revoke {% data variables.product.pat_v2_plural %} in this UI, not {% data variables.product.pat_v1_plural %}. Unless the organization {% ifversion ghec or ghes %}or enterprise {% endif %}has restricted access by {% data variables.product.pat_v1_plural %}, any {% data variables.product.pat_v1 %} can access organization resources until the token expires. For more information about restricting access by {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise){% endif %}. {% ifversion ghec %} Organization owners can also view and revoke {% data variables.product.pat_v1_plural %} if their organization requires SAML single-sign on. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-authorized-credentials). For more information about using the REST API to do this, see [List SAML SSO authorizations for an organization](/rest/orgs/orgs#list-saml-sso-authorizations-for-an-organization) and [Remove a SAML SSO authorization for an organization](/rest/orgs/orgs#remove-a-saml-sso-authorization-for-an-organization).{% endif %} diff --git a/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md index 119f2dac88..25d0e8b492 100644 --- a/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md +++ b/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md @@ -3,20 +3,18 @@ title: Setting a personal access token policy for your organization intro: 'Organization owners can control access to resources by applying policies to {% data variables.product.pat_generic_plural %}' versions: fpt: '*' - ghes: '*' + ghes: '>3.10' ghec: '*' shortTitle: Set a token policy --- -{% data reusables.user-settings.pat-v2-org-opt-in %} - ## Restricting access by {% data variables.product.pat_generic_plural %} Organization owners can prevent {% data variables.product.pat_generic_plural %} from accessing resources owned by the organization with the following options: * **Restrict access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_v1_caps_plural %} or {% data variables.product.pat_v2_plural %} cannot access resources owned by the organization. SSH keys created by {% data variables.product.pat_generic_plural %} will continue to work. * **Allow access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_v1_caps_plural %} or {% data variables.product.pat_v2_plural %} can access resources owned by the organization. -Regardless of the chosen policy, {% data variables.product.pat_generic_caps_plural %} will have access to public resources within the organization. +Regardless of the chosen policy, {% data variables.product.pat_generic_caps_plural %} will have access to public resources within the organization. {% ifversion fpt or ghec or ghes > 3.16 %}By default, both {% data variables.product.pat_v1_caps_plural %} and {% data variables.product.pat_v2_plural %} are enabled.{% endif %} {% ifversion ghec or ghes %} If your organization is owned by an enterprise, and your enterprise owner has restricted access by {% data variables.product.pat_generic_caps_plural %}, you cannot override the policy in your organization. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise).{% endif %} @@ -48,10 +46,10 @@ When you set a policy, tokens with non-compliant lifetimes will be blocked from ## Enforcing an approval policy for {% data variables.product.pat_v2_plural %} Organization owners can manage approval requirements for each {% data variables.product.pat_v2 %} that can access the organization with the following options: - * **Require administrator approval:** An organization owner must approve each {% data variables.product.pat_v2 %} that can access the organization. {% data variables.product.pat_v2_caps_plural %} created by organization owners will not need approval. + * **Require administrator approval:** An organization owner must approve each {% data variables.product.pat_v2 %} that can access the organization. {% data variables.product.pat_v2_caps_plural %} created by organization owners will not need approval. This is the default value. * **Do not require administrator approval:** {% data variables.product.pat_v2_caps %}s created by organization members can access resources in the organization without prior approval. -{% data variables.product.pat_v2_caps %}s will still be able to read public resources within the organization without approval. +{% data variables.product.pat_v2_caps_plural %} will still be able to read public resources within the organization without approval. {% ifversion ghec or ghes %} If your organization is owned by an enterprise, and your enterprise owner has set an approval policy for {% data variables.product.pat_v2 %}s, then you cannot override the policy in your organization. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise).{% endif %} diff --git a/content/rest/orgs/personal-access-tokens.md b/content/rest/orgs/personal-access-tokens.md index 8fcb13f0a0..801d9c2ff8 100644 --- a/content/rest/orgs/personal-access-tokens.md +++ b/content/rest/orgs/personal-access-tokens.md @@ -12,7 +12,4 @@ autogenerated: rest allowTitleToDifferFromFilename: true --- -> [!NOTE] -> {% data reusables.user-settings.pat-v2-beta %} - diff --git a/data/features/pats-maximum-lifetime.yml b/data/features/pats-maximum-lifetime.yml index d03450ba74..5f551e6ff6 100644 --- a/data/features/pats-maximum-lifetime.yml +++ b/data/features/pats-maximum-lifetime.yml @@ -3,4 +3,4 @@ versions: fpt: '*' ghec: '*' - ghes: '>=3.16' + ghes: '>=3.17' diff --git a/data/reusables/user-settings/pat-v2-beta.md b/data/reusables/user-settings/pat-v2-beta.md deleted file mode 100644 index d45e8c5e6e..0000000000 --- a/data/reusables/user-settings/pat-v2-beta.md +++ /dev/null @@ -1 +0,0 @@ -{% data variables.product.pat_v2_caps %} are currently in {% data variables.release-phases.public_preview %} and subject to change. To leave feedback, see [the feedback discussion](https://github.com/community/community/discussions/36441). diff --git a/data/reusables/user-settings/pat-v2-org-opt-in.md b/data/reusables/user-settings/pat-v2-org-opt-in.md deleted file mode 100644 index 3bb75fd1d1..0000000000 --- a/data/reusables/user-settings/pat-v2-org-opt-in.md +++ /dev/null @@ -1,4 +0,0 @@ -> [!NOTE] -> {% data reusables.user-settings.pat-v2-beta %} -> -> During the {% data variables.release-phases.public_preview %}, organizations must opt in to {% data variables.product.pat_v2 %}s. {% ifversion ghec or ghes %}If your organization is owned by an enterprise, and the enterprise has opted in to {% data variables.product.pat_v2 %}s, then your organization is opted in by default. {% endif %}If your organization has not already opted-in, then you will be prompted to opt-in and set policies when you follow the steps below.