diff --git a/content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md b/content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md index 55164f2b33..e4e9939b8e 100644 --- a/content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md +++ b/content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md @@ -298,7 +298,8 @@ To build this link, you'll need your OAuth Apps `client_id` that you received fr * "[Troubleshooting authorization request errors](/apps/managing-oauth-apps/troubleshooting-authorization-request-errors)" * "[Troubleshooting OAuth App access token request errors](/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)" -* "[Device flow errors](#errors-for-the-device-flow)" +{% ifversion fpt or ghae or ghes > 3.0 %}* "[Device flow errors](#error-codes-for-the-device-flow)"{% endif %} +* "[Token expiration and revocation](/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation)" ## Further reading diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md index 9049313022..72c71f4eb7 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md @@ -77,3 +77,4 @@ Instead of manually entering your PAT for every HTTPS Git operation, you can cac ## Further reading - "[About authentication to GitHub](/github/authenticating-to-github/about-authentication-to-github)" +- "[Token expiration and revocation](/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation)" diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md index aa75edef20..9de4bcc41d 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md @@ -22,6 +22,7 @@ children: - /reviewing-your-authorized-integrations - /connecting-with-third-party-applications - /reviewing-your-authorized-applications-oauth + - /token-expiration-and-revocation - /reviewing-your-security-log - /removing-sensitive-data-from-a-repository - /about-anonymized-urls diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md index 5510ce7c18..0f6146a4bd 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md @@ -118,12 +118,12 @@ An overview of some of the most common actions that are recorded as events in th {% endif %} -### `oauth_access` category actions +### `oauth_authorization` category actions | Action | Description |------------------|------------------- | `create` | Triggered when you [grant access to an {% data variables.product.prodname_oauth_app %}](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps). -| `destroy` | Triggered when you [revoke an {% data variables.product.prodname_oauth_app %}'s access to your account](/articles/reviewing-your-authorized-integrations). +| `destroy` | Triggered when you [revoke an {% data variables.product.prodname_oauth_app %}'s access to your account](/articles/reviewing-your-authorized-integrations) and when [authorizations are revoked or expire](/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation). {% ifversion fpt %} diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation.md new file mode 100644 index 0000000000..7351e1f3e7 --- /dev/null +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation.md @@ -0,0 +1,62 @@ +--- +title: Token expiration and revocation +intro: Your tokens can expire and can also be revoked by you, applications you have authorized, and {% data variables.product.product_name %} itself. +versions: + fpt: '*' + ghes: '*' + ghae: '*' +topics: + - Identity + - Access management +shortTitle: Token expiration +--- + +When a token has expired or has been revoked, it can no longer be used to authenticate Git and API requests. It is not possible to restore an expired or revoked token, you or the application will need to create a new token. + +This article explains the possible reasons your {% data variables.product.product_name %} token might be revoked or expire. + +{% note %} + +**Note:** When a personal access token or OAuth token expires or is revoked, you may see an `oauth_authorization.destroy` action in your security log. For more information, see "[Reviewing your security log](/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log)." + +{% endnote %} + +{% ifversion fpt or ghae-issue-4374 or ghes > 3.1 %} +## Token revoked after reaching its expiration date + +When you create a personal access token, we recommend that you set an expiration for your token. Upon reaching your token's expiration date, the token is automatically revoked. For more information, see "[Creating a personal access token](/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)." +{% endif %} + +{% ifversion fpt %} +## Token revoked when pushed to a public repository or public gist + +If a valid OAuth token, {% data variables.product.prodname_github_app %} token, or personal access token is pushed to a public repository or public gist, the token will be automatically revoked. + +OAuth tokens and personal access tokens pushed to public repositories and public gists will only be revoked if the token has scopes. +{% endif %} + +{% ifversion fpt %} +## Token expired due to lack of use + +{% data variables.product.product_name %} will automatically revoke an OAuth token or personal access token when the token hasn't been used in one year. +{% endif %} + +## Token revoked by the user + +You can revoke your authorization of a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} from your account settings which will revoke any tokens associated with the app. For more information, see "[Reviewing your authorized integrations](/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations)" and "[Reviewing your authorized applications (OAuth)](/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-authorized-applications-oauth)." + +Once an authorization is revoked, any tokens associated with the authorization will be revoked as well. To re-authorize an application, follow the instructions from the third-party application or website to connect your {% data variables.product.product_name %} account again. + +## Token revoked by the {% data variables.product.prodname_oauth_app %} + +The owner of an {% data variables.product.prodname_oauth_app %} can revoke an account's authorization of their app, this will also revoke any tokens associated with the authorization. For more information about revoking authorizations of your OAuth app, see "[Delete an app authorization](/rest/reference/apps#delete-an-app-authorization)." + +## Token revoked due to excess of tokens for an {% data variables.product.prodname_oauth_app %} with the same scope + +{% data reusables.apps.oauth-token-limit %} + +{% ifversion fpt or ghae or ghes > 3.1 %} +## User token revoked due to {% data variables.product.prodname_github_app %} configuration + +User-to-server tokens created by a {% data variables.product.prodname_github_app %} will expire after eight hours by default. Owners of {% data variables.product.prodname_github_apps %} can configure their apps so that user-to-server tokens do not expire. For more information about changing how your {% data variables.product.prodname_dotcom %} App's user-to-server tokens behave, see "[Activating optional features for apps](/developers/apps/getting-started-with-apps/activating-optional-features-for-apps)." +{% endif %} diff --git a/content/rest/overview/troubleshooting.md b/content/rest/overview/troubleshooting.md index 91b7b377a7..3898705968 100644 --- a/content/rest/overview/troubleshooting.md +++ b/content/rest/overview/troubleshooting.md @@ -23,7 +23,7 @@ You might expect to see a `403 Forbidden` in these cases. However, since we don' want to provide _any_ information about private repositories, the API returns a `404` error instead. -To troubleshoot, ensure [you're authenticating correctly](/guides/getting-started/), [your OAuth access token has the required scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/), and [third-party application restrictions][oap-guide] are not blocking access. +To troubleshoot, ensure [you're authenticating correctly](/guides/getting-started/), [your OAuth access token has the required scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/), [third-party application restrictions][oap-guide] are not blocking access, and that [the token has not expired or been revoked](/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation). ## Not all results returned diff --git a/data/reusables/apps/oauth-token-limit.md b/data/reusables/apps/oauth-token-limit.md index c38d2156a6..ee6f47c536 100644 --- a/data/reusables/apps/oauth-token-limit.md +++ b/data/reusables/apps/oauth-token-limit.md @@ -1 +1 @@ -There is a limit of ten tokens that are issued per user/application/scope combination. If the application requests enough tokens to go over one of the limits, older tokens _with the same scope being requested_ will stop working. +There is a limit of ten tokens that are issued per user/application/scope combination. If an application creates more than 10 tokens for the same user and the same scopes, the oldest tokens with the same user/application/scope combination will be revoked. \ No newline at end of file