Password authentication and OAuth Authorizations API deprecation (github#16375)

* Version password examples for GHES only

* Remove unnecessary note

* Versioned deprecation reusable for GHES only?

* Update troubleshooting article

* Version OAuthorizations REST API page for enterprise-only

* Remove deprecations reusable

* Add tentative note

* Rework two-factor authentication sections

* Fix double redirect reference

* versioning tweak

* Versioning tweaks

* adding back the endifs

* random link reformatting

* OAuth Authorization API versioned for 2.22

* /

* Fix internal docs links

* remove static redirect for dotcom

* Try deleting redirect

* Apply @martin389's suggested changes

Co-authored-by: Martin Lopes <[email protected]>

* Remove best practice assumptions

* Apply suggestions from code review

Co-authored-by: Martin Lopes <[email protected]>

* Add note

* restore redirects in content file and remove free-pro-team expected path from test fixture

* change note position

* handle path that was available on dotcom in developer site but is now GHES only

Co-authored-by: Martin Lopes <[email protected]>
Co-authored-by: Sarah Schneider <[email protected]>

Author: 3 people

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 %}
 

content/rest/overview/other-authentication-methods.md

@@ -46,11 +46,19 @@ $ curl -u <em>username</em>:<em>token</em> {% 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

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 <em>valid_username</em>:<em>valid_token</em> {% endif %}{% if enterpriseServerVersions contains currentVersion %}-u <em>valid_username</em>:<em>valid_password</em> {% 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 <em>username</em>:<em>token</em> {% endif %}{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}-u <em>username</em>:<em>password</em> {% endif %}{% data variables.product.api_url_pre %}
+$ curl {% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" %}
+-u <em>username</em>:<em>token</em> {% endif %}{% if enterpriseServerVersions contains currentVersion %}-u <em>username</em>:<em>password</em> {% 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.

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](/[email protected]/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 %}

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).

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/[email protected]/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/[email protected]/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.
 

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/[email protected]/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/[email protected]/rest/reference/oauth-authorizations/#create-a-new-authorization)." |

data/reusables/apps/deprecating_password_auth.md

@@ -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,

lib/redirects/get-docs-path-from-developer-path.js

@@ -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",