Merge branch 'oauth-pkce' into 'master'

Enable PKCE OAuth flow

See merge request gitlab-org/gitlab!49756

app/views/doorkeeper/authorizations/new.html.haml

@@ -38,6 +38,8 @@
             = hidden_field_tag :response_type, @pre_auth.response_type
             = hidden_field_tag :scope, @pre_auth.scope
             = hidden_field_tag :nonce, @pre_auth.nonce
+            = hidden_field_tag :code_challenge, @pre_auth.code_challenge
+            = hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method
             = submit_tag _("Deny"), class: "gl-button btn btn-danger"
           = form_tag oauth_authorization_path, method: :post, class: 'inline' do
             = hidden_field_tag :client_id, @pre_auth.client.uid
@@ -46,4 +48,6 @@
             = hidden_field_tag :response_type, @pre_auth.response_type
             = hidden_field_tag :scope, @pre_auth.scope
             = hidden_field_tag :nonce, @pre_auth.nonce
+            = hidden_field_tag :code_challenge, @pre_auth.code_challenge
+            = hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method
             = submit_tag _("Authorize"), class: "gl-button btn btn-success gl-ml-3", data: { qa_selector: 'authorization_button' }

changelogs/unreleased/oauth-pkce.yml

+---
+title: Enable OAuth PKCE flow
+merge_request: 49756
+author:
+type: added

db/migrate/20201209163958_add_code_challenge_to_oauth_access_grants.rb

+# frozen_string_literal: true
+
+class AddCodeChallengeToOauthAccessGrants < ActiveRecord::Migration[6.0]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  disable_ddl_transaction!
+
+  def up
+    add_column(:oauth_access_grants, :code_challenge, :text, null: true) unless column_exists?(:oauth_access_grants, :code_challenge)
+    # If `code_challenge_method` is 'plain' the length is at most 128 characters as per the spec
+    # https://tools.ietf.org/html/rfc7636#section-4.1
+    # Otherwise the max length of base64(SHA256(code_verifier)) is 44 characters
+    add_text_limit(:oauth_access_grants, :code_challenge, 128, constraint_name: 'oauth_access_grants_code_challenge')
+
+    add_column(:oauth_access_grants, :code_challenge_method, :text, null: true) unless column_exists?(:oauth_access_grants, :code_challenge_method)
+    # Values are either 'plain' or 'S256'
+    add_text_limit(:oauth_access_grants, :code_challenge_method, 5, constraint_name: 'oauth_access_grants_code_challenge_method')
+  end
+
+  def down
+    remove_column(:oauth_access_grants, :code_challenge)
+    remove_column(:oauth_access_grants, :code_challenge_method)
+  end
+end

db/schema_migrations/20201209163958

+4bdd5eba48a76d8feab948857ec32ef7fe25e04e8633ee7d94fd059e73703472
\ No newline at end of file

db/structure.sql

@@ -14373,7 +14373,11 @@ CREATE TABLE oauth_access_grants (
     redirect_uri text NOT NULL,
     created_at timestamp without time zone NOT NULL,
     revoked_at timestamp without time zone,
-    scopes character varying
+    scopes character varying,
+    code_challenge text,
+    code_challenge_method text,
+    CONSTRAINT oauth_access_grants_code_challenge CHECK ((char_length(code_challenge) <= 128)),
+    CONSTRAINT oauth_access_grants_code_challenge_method CHECK ((char_length(code_challenge_method) <= 5))
 );
 
 CREATE SEQUENCE oauth_access_grants_id_seq

doc/api/oauth2.md

@@ -2,7 +2,7 @@
 type: reference, howto
 stage: Manage
 group: Access
-info: To determine the technical writer assigned to the Stage/Group associated   with this page, see https://about.gitlab.com/handbook/engineering/ux/technica  l-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated   with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
 # GitLab as an OAuth2 provider
@@ -19,17 +19,26 @@ documentation. This functionality is based on the
 
 GitLab currently supports the following authorization flows:
 
-- **Web application flow:** Most secure and common type of flow, designed for
-  applications with secure server-side.
-- **Implicit grant flow:** This flow is designed for user-agent only apps (e.g., single
-  page web application running on GitLab Pages).
-- **Resource owner password credentials flow:** To be used **only** for securely
-  hosted, first-party services.
+- **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):** 
+  Most secure. Without PKCE, you'd have to include client secrets on mobile clients,
+  and is recommended for both client and server aoos.
+- **Authorization code:** Secure and common flow. Recommended option for secure 
+  server-side apps.
+- **Implicit grant:** Originally designed for user-agent only apps, such as 
+  single page web apps running on GitLab Pages).
+  The [IETF](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2)
+  recommends against Implicit grant flow.
+- **Resource owner password credentials:** To be used **only** for securely
+  hosted, first-party services. GitLab recommends against use of this flow.
+
+The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the
+Implicit grant and Resource Owner Password Credentials flows.
+  it will be deprecated in the next OAuth specification version.
 
 Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out
 how all those flows work and pick the right one for your use case.
 
-Both **web application** and **implicit grant** flows require `application` to be
+Both **authorization code** (with or without PKCE) and **implicit grant** flows require `application` to be
 registered first via the `/profile/applications` page in your user's account.
 During registration, by enabling proper scopes, you can limit the range of
 resources which the `application` can access. Upon creation, you'll obtain the
@@ -57,19 +66,84 @@ These factors are particularly important when using the
 In the following sections you will find detailed instructions on how to obtain
 authorization with each flow.
 
-### Web application flow
+### Authorization code with Proof Key for Code Exchange (PKCE)
+
+The [PKCE RFC](https://tools.ietf.org/html/rfc7636#section-1.1) includes a
+detailed flow description, from authorization request through access token.
+The following steps describe our implementation of the flow.
+
+The Authorization code with PKCE flow, PKCE for short, makes it possible to securely perform
+the OAuth exchange of client credentials for access tokens on public clients.
+
+Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `CODE_CHALLENGE`.
+
+- The `STATE` a value that can't be predicted used by the client to maintain
+  state between the request and callback. It should also be used as a CSRF token.
+- The `CODE_VERIFIER` is a random string, between 43 and 128 characters in length,
+  which use the characters `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, and `~`.
+- The `CODE_CHALLENGE` is an URL-safe base64-encoded string of the SHA256 hash of the
+  `CODE_VERIFIER`
+  - In Ruby, you can set that up with `Base64.urlsafe_encode64(Digest::SHA256.digest(CODE_VERIFIER))`.
+
+1. Request authorization code. To do that, you should redirect the user to the
+   `/oauth/authorize` page with the following query parameters:
+
+   ```plaintext
+   https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
+   ```
+
+   This page asks the user to approve the request from the app to access their
+   account based on the scopes specified in `REQUESTED_SCOPES`. The user is then
+   redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
+   is a space separated list of scopes associated with the user.
+   For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes.
+   The redirect includes the authorization `code`, for example:
+
+   ```plaintext
+   https://example.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH
+   ```
+
+1. With the authorization `code` returned from the previous request (denoted as
+   `RETURNED_CODE` in the following example), you can request an `access_token`, with
+   any HTTP client. The following example uses Ruby's `rest-client`:
+
+   ```ruby
+   parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
+   RestClient.post 'https://gitlab.example.com/oauth/token', parameters
+   ```
+
+   Example response:
+
+   ```json
+   {
+    "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
+    "token_type": "bearer",
+    "expires_in": 7200,
+    "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
+    "created_at": 1607635748
+   }
+   ```
+
+NOTE:
+The `redirect_uri` must match the `redirect_uri` used in the original
+authorization request.
+
+You can now make requests to the API with the access token.
+
+### Authorization code flow
 
 NOTE:
 Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.1) for a
 detailed flow description.
 
-The web application flow is:
+The authorization code flow is essentially the same as
+[authorization code flow with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce),
 
 1. Request authorization code. To do that, you should redirect the user to the
    `/oauth/authorize` endpoint with the following GET parameters:
 
    ```plaintext
-   https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
+   https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES
    ```
 
    This will ask the user to approve the applications access to their account
@@ -80,7 +154,7 @@ The web application flow is:
    include the GET `code` parameter, for example:
 
    ```plaintext
-   https://example.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH
+   https://example.com/oauth/redirect?code=1234567890&state=STATE
    ```
 
    You should then use `code` to request an access token.
@@ -101,7 +175,8 @@ The web application flow is:
     "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
     "token_type": "bearer",
     "expires_in": 7200,
-    "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
+    "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
+    "created_at": 1607635748
    }
    ```
 
@@ -114,19 +189,20 @@ You can now make requests to the API with the access token returned.
 ### Implicit grant flow
 
 NOTE:
-Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.2) for a
-detailed flow description.
+For a detailed flow diagram, see the [RFC specification](https://tools.ietf.org/html/rfc6749#section-4.2). 
 
 WARNING:
-Avoid using this flow for applications that store data outside of the GitLab
-instance. If you do, make sure to verify `application id` associated with the
-access token before granting access to the data
-(see [`/oauth/token/info`](#retrieving-the-token-information)).
-
-Unlike the web flow, the client receives an `access token` immediately as a
-result of the authorization request. The flow does not use the client secret
-or the authorization code because all of the application code and storage is
-easily accessible, therefore secrets can leak easily.
+The Implicit grant flow is inherently insecure. The IETF plans to remove it in
+[OAuth 2.1](https://oauth.net/2.1/).
+
+We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) instead. If you choose to use Implicit flow, be sure to verify the
+`application id` (or `client_id`) associated with the access token before granting
+access to the data, as described in [Retrieving the token information](#retrieving-the-token-information)).
+
+Unlike the authorization code flow, the client receives an `access token`
+immediately as a result of the authorization request. The flow does not use
+the client secret or the authorization code because all of the application code
+and storage is easily accessible on client browsers and mobile devices.
 
 To request the access token, you should redirect the user to the
 `/oauth/authorize` endpoint using `token` response type: