diff --git a/content/developers/apps/rate-limits-for-github-apps.md b/content/developers/apps/rate-limits-for-github-apps.md index e25d374ee18c..31607e2e14bb 100644 --- a/content/developers/apps/rate-limits-for-github-apps.md +++ b/content/developers/apps/rate-limits-for-github-apps.md @@ -34,8 +34,6 @@ Different server-to-server request rate limits apply to {% data variables.produc ### User-to-server requests -{% data reusables.apps.deprecating_password_auth %} - {% data variables.product.prodname_github_app %}s can also act [on behalf of a user](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#identifying-and-authorizing-users-for-github-apps), making user-to-server requests. {% if currentVersion == "free-pro-team@latest" %} @@ -52,7 +50,7 @@ User-to-server requests are rate limited at 5,000 requests per hour and per auth #### {% data variables.product.prodname_ghe_cloud %} user-to-server rate limits -When a user belongs to a {% data variables.product.prodname_ghe_cloud %} account, user-to-server requests to resources owned by the same {% data variables.product.prodname_ghe_cloud %} account are rate limited at 15,000 requests per hour and per authenticated user. All OAuth applications authorized by that user, personal access tokens owned by that user, and requests authenticated with that user's username and password share the same quota of 5,000 requests per hour for that user. +When a user belongs to a {% data variables.product.prodname_ghe_cloud %} account, user-to-server requests to resources owned by the same {% data variables.product.prodname_ghe_cloud %} account are rate limited at 15,000 requests per hour and per authenticated user. All OAuth applications authorized by that user, personal access tokens owned by that user, and {% data variables.product.prodname_ghe_cloud %} requests authenticated with that user's username and password share the same quota of 5,000 requests per hour for that user. {% endif %} diff --git a/content/rest/overview/other-authentication-methods.md b/content/rest/overview/other-authentication-methods.md index 5b70f6fd83a9..ec4a6ae19e50 100644 --- a/content/rest/overview/other-authentication-methods.md +++ b/content/rest/overview/other-authentication-methods.md @@ -46,11 +46,19 @@ $ curl -u username:token {% data variables.product.api_url_pre This approach is useful if your tools only support Basic Authentication but you want to take advantage of OAuth access token security features. -{% if enterpriseServerVersions contains currentVersion %} #### Via username and password -{% data reusables.apps.deprecating_password_auth %} +{% if currentVersion == "free-pro-team@latest" %} + +{% note %} +**Note:** {% data variables.product.prodname_dotcom %} has discontinued password authentication to the API starting on November 13, 2020 for all {% data variables.product.prodname_dotcom_the_website %} accounts, including those on a {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, or {% data variables.product.prodname_ghe_cloud %} plan. You must now authenticate to the {% data variables.product.prodname_dotcom %} API with an API token, such as an OAuth access token, GitHub App installation access token, or personal access token, depending on what you need to do with the token. For more information, see "[Troubleshooting](/rest/overview/troubleshooting#basic-authentication-errors)." + +{% endnote %} + +{% endif %} + +{% if enterpriseServerVersions contains currentVersion %} To use Basic Authentication with the {% data variables.product.product_name %} API, simply send the username and password associated with the account. @@ -100,14 +108,13 @@ The value `organizations` is a comma-separated list of organization IDs for orga {% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %} ### Working with two-factor authentication -{% data reusables.apps.deprecating_password_auth %} - -When you have two-factor authentication enabled, [Basic Authentication](#basic-authentication) for _most_ endpoints in the REST API requires that you use a personal access token or OAuth token instead of your username and password. - -You can generate a new personal access token {% if currentVersion == "free-pro-team@latest" %}with [{% data variables.product.product_name %} developer settings](https://github.com/settings/tokens/new){% endif %} or use the "[Create a new authorization][create-access]" endpoint in the OAuth Authorizations API to generate a new OAuth token. For more information, see "[Creating a personal access token for the command line](/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)". Then you would use these tokens to [authenticate using OAuth token][oauth-auth] with the GitHub API. The only time you need to authenticate with your username and password is when you create your OAuth token or use the OAuth Authorizations API. +When you have two-factor authentication enabled, [Basic Authentication](#basic-authentication) for _most_ endpoints in the REST API requires that you use a personal access token{% if enterpriseServerVersions contains currentVersion %} or OAuth token instead of your username and password{% endif %}. +You can generate a new personal access token {% if currentVersion == "free-pro-team@latest" %}using [{% data variables.product.product_name %} developer settings](https://github.com/settings/tokens/new){% endif %}{% if enterpriseServerVersions contains currentVersion %} or with the "[Create a new authorization][/rest/reference/oauth-authorizations#create-a-new-authorization]" endpoint in the OAuth Authorizations API to generate a new OAuth token{% endif %}. For more information, see "[Creating a personal access token for the command line](/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)". Then you would use these tokens to [authenticate using OAuth token][oauth-auth] with the {% data variables.product.prodname_dotcom %} API.{% if enterpriseServerVersions contains currentVersion %} The only time you need to authenticate with your username and password is when you create your OAuth token or use the OAuth Authorizations API.{% endif %} +{% endif %} +{% if enterpriseServerVersions contains currentVersion %} #### Using the OAuth Authorizations API with two-factor authentication When you make calls to the OAuth Authorizations API, Basic Authentication requires that you use a one-time password (OTP) and your username and password instead of tokens. When you attempt to authenticate with the OAuth Authorizations API, the server will respond with a `401 Unauthorized` and one of these headers to let you know that you need a two-factor authentication code: @@ -126,7 +133,6 @@ $ curl --request POST \ ``` {% endif %} -[create-access]: /v3/oauth_authorizations/#create-a-new-authorization [curl]: http://curl.haxx.se/ [oauth-auth]: /v3/#authentication [personal-access-tokens]: /articles/creating-a-personal-access-token-for-the-command-line diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index c275ff4b3a9a..103e4da35b85 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -150,9 +150,9 @@ the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with `403 Forbidden`: ```shell -$ curl -i {% data variables.product.api_url_pre %} -u valid_username:valid_password +$ curl -i {% data variables.product.api_url_pre %} -u {% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" %} +-u valid_username:valid_token {% endif %}{% if enterpriseServerVersions contains currentVersion %}-u valid_username:valid_password {% endif %} > HTTP/1.1 403 Forbidden - > { > "message": "Maximum number of login attempts exceeded. Please try again later.", > "documentation_url": "{% data variables.product.doc_url_pre %}/v3" @@ -185,19 +185,10 @@ $ curl -i -u username -d '{"scopes":["public_repo"]}' {% data variables.product. You can issue a `GET` request to the root endpoint to get all the endpoint categories that the REST API supports: ```shell -$ curl {% if currentVersion == "github-ae@latest" %}-u username:token {% endif %}{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}-u username:password {% endif %}{% data variables.product.api_url_pre %} +$ curl {% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" %} +-u username:token {% endif %}{% if enterpriseServerVersions contains currentVersion %}-u username:password {% endif %}{% data variables.product.api_url_pre %} ``` -{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %} - -{% note %} - -**Note:** For {% data variables.product.prodname_ghe_server %}, [as with all other endpoints](/v3/enterprise-admin/#endpoint-urls), you'll need to pass your username and password. - -{% endnote %} - -{% endif %} - ### GraphQL global node IDs See the guide on "[Using Global Node IDs](/v4/guides/using-global-node-ids)" for detailed information about how to find `node_id`s via the REST API and use them in GraphQL operations. diff --git a/content/rest/overview/troubleshooting.md b/content/rest/overview/troubleshooting.md index 24c83cfc3703..d3b262ece79a 100644 --- a/content/rest/overview/troubleshooting.md +++ b/content/rest/overview/troubleshooting.md @@ -14,7 +14,7 @@ versions: If you're encountering some oddities in the API, here's a list of resolutions to some of the problems you may be experiencing. -### Why am I getting a `404` error on a repository that exists? +### `404` error for an existing repository Typically, we send a `404` error when your client isn't properly authenticated. You might expect to see a `403 Forbidden` in these cases. However, since we don't @@ -23,7 +23,7 @@ want to provide _any_ information about private repositories, the API returns a 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. -### Why am I not seeing all my results? +### Not all results returned Most API calls accessing a list of resources (_e.g._, users, issues, _etc._) support pagination. If you're making requests and receiving an incomplete set of results, you're @@ -35,3 +35,40 @@ API call uses the same structure. Instead, extract the pagination information fr [the Link Header](/v3/#pagination), which is sent with every request. [oap-guide]: https://developer.github.com/changes/2015-01-19-an-integrators-guide-to-organization-application-policies/ + +{% if currentVersion == "free-pro-team@latest" %} +### Basic authentication errors + +On November 13, 2020 username and password authentication to the REST API and the OAuth Authorizations API were deprecated and no longer work. + +#### Using `username`/`password` for basic authentication + +If you're using `username` and `password` for API calls, then they are no longer able to authenticate. For example: + +```bash +curl -u my_user:my_password https://api.github.com/user/repos +``` + +Instead, use a [personal access token](/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) when testing endpoints or doing local development: + +```bash +curl -H 'Authorization: token my_access_token' https://api.github.com/user/repos +``` + +For OAuth Apps, you should use the [web application flow](/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to generate an OAuth token to use in the API call's header: + +```bash +curl -H 'Authorization: token my-oauth-token' https://api.github.com/user/repos +``` + +#### Calls to OAuth Authorizations API + +If you're making [OAuth Authorization API](/enterprise-server@2.22/rest/reference/oauth-authorizations) calls to manage your OAuth app's authorizations or to generate access tokens, similar to this example: + +```bash +curl -u my_username:my_password -X POST "https://api.github.com/authorizations" -d '{"scopes":["public_repo"], "note":"my token", "client_id":"my_client_id", "client_secret":"my_client_secret"}' +``` + +Then you must switch to the [web application flow](/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to generate access tokens. + +{% endif %} diff --git a/content/rest/reference/oauth-authorizations.md b/content/rest/reference/oauth-authorizations.md index 8bb3e8fa72cc..356309baff03 100644 --- a/content/rest/reference/oauth-authorizations.md +++ b/content/rest/reference/oauth-authorizations.md @@ -4,13 +4,9 @@ redirect_from: - /v3/oauth_authorizations - /v3/oauth-authorizations versions: - free-pro-team: '*' enterprise-server: '*' --- -{% data reusables.apps.deprecating_token_oauth_authorizations %} -{% data reusables.apps.deprecating_password_auth %} - You can use this API to manage the access OAuth applications have to your account. You can only access this API via [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) using your username and password, not tokens. If you or your users have two-factor authentication enabled, make sure you understand how to [work with two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication). diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md index f103bf3dcbc0..ee292691861c 100644 --- a/contributing/content-style-guide.md +++ b/contributing/content-style-guide.md @@ -193,8 +193,8 @@ Introduce links consistently using a standard format that clearly indicates wher Links should be meaningful and provide high value to the user’s journey - link out carefully. Move links that are helpful but not necessary to an article’s further reading section. Do not repeat the same link more than once in the same article or under the same H3 header. For accessibility and readability, avoid inline or midsentence links. -- **Use:** OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization)." -- **Avoid:** Read [more about OAuth2.](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization), for applications that are not websites. +- **Use:** OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization)." +- **Avoid:** Read [more about OAuth2.](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites. For more information on links and accessibility, see “[Links](https://readabilityguidelines.co.uk/content-design/links/)” in the Readability Guidelines project. diff --git a/contributing/localization-checklist.md b/contributing/localization-checklist.md index a44110425a54..31eba65e9a97 100644 --- a/contributing/localization-checklist.md +++ b/contributing/localization-checklist.md @@ -32,4 +32,4 @@ Use the following checklist to help make your files more translation-friendly. F | Avoid using ambiguous modal auxiliary verbs. | May, might, ought, could, used to, etc. | Be more clear when writing to avoid ambiguity. | | Avoid prepositional phrases. | "According to the repository log..." or "After trying many times..." | Write the sentence more directly. | | Avoid vague nouns and pronouns. | "Maintainers and contributors have access to files and comments. In the pull request they make changes to it." In this example it is not clear if the changes are being made to the file or to the comments. Another example “After saving the file in the folder, the user deleted it.” In this sentence it is not clear what was deleted (file or folder). | If a pronoun seems to refer to more than one antecedent, either reword the sentence to make the antecedent clear or replace the pronoun by a noun to eliminate ambiguity. | -| Keep inline links to a minimum. | Read [more about OAuth2.](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization), for applications that are not websites. | OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](https://developer.github.com/v3/oauth_authorizations/#create-a-new-authorization)." | +| Keep inline links to a minimum. | Read [more about OAuth2.](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites. | OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](https://docs.github.com/en/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization)." | diff --git a/data/reusables/apps/deprecating_password_auth.md b/data/reusables/apps/deprecating_password_auth.md deleted file mode 100644 index 402d3b14b62f..000000000000 --- a/data/reusables/apps/deprecating_password_auth.md +++ /dev/null @@ -1,9 +0,0 @@ -{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.19" or currentVersion == "github-ae@latest" %} -{% warning %} - -**Deprecation Notice:** {% data variables.product.prodname_dotcom %} will discontinue password authentication to the API. You must now authenticate to the {% data variables.product.prodname_dotcom %} API with an API token, such as an OAuth access token, GitHub App installation access token, or personal access token, depending on what you need to do with the token.{% if currentVersion == "free-pro-team@latest" %} Password authentication to the API will be removed on November 13, 2020.{% endif %} For more information,{% if currentVersion == "free-pro-team@latest" %} including scheduled brownouts,{% endif %} see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-password-auth/). - -{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} Authenticating to the API using a password is currently available and not yet deprecated in {% data variables.product.product_name %}. {% data variables.product.prodname_dotcom %} will announce the deprecation and provide advanced notice before removing support for this feature.{% endif %} - -{% endwarning %} -{% endif %} diff --git a/lib/redirects/get-docs-path-from-developer-path.js b/lib/redirects/get-docs-path-from-developer-path.js index 6de6323d1240..861e04155f27 100644 --- a/lib/redirects/get-docs-path-from-developer-path.js +++ b/lib/redirects/get-docs-path-from-developer-path.js @@ -18,6 +18,12 @@ module.exports = function getDocsPathFromDeveloperPath (oldDeveloperPath, allRed newPath = newPath.replace(v3OrgPreReceiveHooks, '/v3/enterprise-admin/org_pre_receive_hooks') } + // oneoff redirect for a dotcom developer path to Enterprise-only path on docs.github.com + const oauthAuthorizations = '/v3/oauth_authorizations' + if (newPath.endsWith(oauthAuthorizations)) { + newPath = newPath.replace(oauthAuthorizations, '/enterprise-server/v3/oauth_authorizations') + } + // Change /v4/foo/bar to /v4/foo#bar // Change /v3/foo/bar to /v3/foo#bar // Then we can look up the hashless path in the redirect object, diff --git a/script/README.md b/script/README.md index a9d3e7c624d1..e11c0b615fcb 100644 --- a/script/README.md +++ b/script/README.md @@ -368,6 +368,13 @@ An automated test checks for discrepancies between filenames and [autogenerated --- +### [`release-banner.js`](release-banner.js) + +This script creates or removes a release candidate banner for a specified version. + + +--- + ### [`remove-deprecated-enterprise-version-markup.js`](remove-deprecated-enterprise-version-markup.js) Run this script after an Enterprise deprecation to remove Liquid statements and frontmatter that contain the deprecated Enterprise version. See the Enterprise deprecation issue template for instructions. @@ -487,4 +494,3 @@ Run this script to: [upload individual files to S3](https://github.com/github/pr --- - diff --git a/tests/fixtures/rest-redirects.json b/tests/fixtures/rest-redirects.json index 771cd3f4d4e6..01470158f7cf 100644 --- a/tests/fixtures/rest-redirects.json +++ b/tests/fixtures/rest-redirects.json @@ -451,7 +451,7 @@ "/v3/migrations/orgs": "/en/free-pro-team@latest/rest/reference/migrations#orgs", "/v3/migrations/source_imports": "/en/free-pro-team@latest/rest/reference/migrations#source-imports", "/v3/migrations/users": "/en/free-pro-team@latest/rest/reference/migrations#users", - "/v3/oauth_authorizations": "/en/free-pro-team@latest/rest/reference/oauth-authorizations", + "/v3/oauth_authorizations": "/en/enterprise-server/rest/reference/oauth-authorizations", "/v3/orgs/blocking": "/en/free-pro-team@latest/rest/reference/orgs#blocking", "/v3/orgs/hooks": "/en/free-pro-team@latest/rest/reference/orgs#hooks", "/v3/orgs": "/en/free-pro-team@latest/rest/reference/orgs",