Merge branch '2979-document-2fa-auth-changes' into 'master'

Add notices about disabling auth features for users with 2FA.

Related to #2979

- Document the proposed changes to the GitLab authentication system.
- This is done because currently, users with 2FA enabled are allowed API access without a 2FA token.

# Tasks

- [ ]  #2979 !xxxx - Document proposed auth changes for 2FA users
    - [x]  Wait for replies on "[potential avenues for documenting the planned changes](https://gitlab.com/gitlab-org/gitlab-ce/issues/2979#note_12591578)"
    - [x]  Update documentation
    - [ ]  CHANGELOG entry?
    - [ ]  Merge conflicts

See merge request !4815

doc/api/oauth2.md

@@ -65,6 +65,13 @@ curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
 
 ## Resource Owner Password Credentials
 
+## Deprecation Notice
+
+1. Starting in GitLab 9.0, the Resource Owner Password Credentials will be *disabled* for users with two-factor authentication turned on.
+2. These users can access the API using [personal access tokens] instead.
+
+---
+
 In this flow, a token is requested in exchange for the resource owner credentials (username and password). 
 The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the
 client is part of the device operating system or a highly privileged application), and when other authorization grant types are not
@@ -100,3 +107,5 @@ client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http
 access_token = client.password.get_token('user@example.com', 'sekret')
 puts access_token.token
 ```
+
+[personal access tokens]: ./README.md#personal-access-tokens

doc/api/session.md

 # Session
 
+## Deprecation Notice
+
+1. Starting in GitLab 9.0, this feature will be *disabled* for users with two-factor authentication turned on.
+2. These users can access the API using [personal access tokens] instead.
+
+---
+
 You can login with both GitLab and LDAP credentials in order to obtain the
 private token.
 
@@ -45,3 +52,5 @@ Example response:
   "private_token": "9koXpg98eAheJpvBs5tK"
 }
 ```
+
+[personal access tokens]: ./README.md#personal-access-tokens