Added PKCE support

.gitignore

@@ -14,4 +14,7 @@ _book
 *.epub
 *.mobi
 *.pdf
-.idea
+.idea
+.vscode
+vendor
+composer.lock

README.md

@@ -6,6 +6,26 @@ This plugin uses the OAuth 2 protocol to allow delegated authorization; that is,
 
 This plugin only supports WordPress >= 4.8.
 
+## Proof Key for Code Exchange
+OAuth2 plugin supports PKCE as a protection against authorization code interception attack (relevant only for authorization code grant type). In order to use PKCE, on the initial authorization request, add two fields: 
+* _code_challenge_ 
+* _code_challenge_method_ (optional). 
+
+Code verifier is a 43-128 length random string consisting of [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~". Code challenge is derived from the code verifier depending on the challenge method. Two types are supported, 's256' and 'plain'. Plain is just code_challenge = code_verifier. s256 method uses SHA256 to hash the code verifier and then do a base64 encoding of the resulting hash. e.g.
+
+code_verifier = 052edd3941bb8040ecac75d2359d7cd1abe2518911b<br>
+code_challenge = base64( sha256( code_verifier ) ) = MmNmZTJlNGZhYmNmYzQ3YTI4MmRhY2Q1NGEwZDUzZTFiZGFhNTNlODI4MGY3NjM0YWUwNjA1YjYzMmQwNDMxNQ==<br>
+code_challenge_method = s256
+
+In the next step, when using the code received from the server to obtain an access token, code_verifier must be passed in as an additional field to the request, and it must be using the code_verifier value that was used to calculate the code_challenge in the initial request.
+
+## CLI Commands
+
+### PKCE
+
+A custom WP CLI helper command to generate a random code verifier and a code challenge.
+
+```wp oauth2 generate-code-challenge```
 
 ## Warning
 

inc/class-client.php

@@ -229,8 +229,8 @@ public function check_redirect_uri( $uri ) {
 	 *
 	 * @return Authorization_Code|WP_Error
 	 */
-	public function generate_authorization_code( WP_User $user ) {
-		return Authorization_Code::create( $this, $user );
+	public function generate_authorization_code( WP_User $user, $data ) {
+		return Authorization_Code::create( $this, $user, $data );
 	}
 
 	/**

inc/endpoints/class-token.php

@@ -31,6 +31,11 @@ public function register_routes() {
 					'type' => 'string',
 					'validate_callback' => 'rest_validate_request_arg',
 				],
+				'code_verifier' => [
+					'required' => false,
+					'type' => 'string',
+					'validate_callback' => 'rest_validate_request_arg',
+				],
 			],
 		] );
 	}
@@ -71,7 +76,7 @@ public function exchange_token( WP_REST_Request $request ) {
 			return $auth_code;
 		}
 
-		$is_valid = $auth_code->validate();
+		$is_valid = $auth_code->validate( $request );
 		if ( is_wp_error( $is_valid ) ) {
 			// Invalid request, but code itself exists, so we should delete
 			// (and silently ignore errors).

inc/namespace.php

@@ -21,6 +21,12 @@ function bootstrap() {
 	// Admin-related.
 	add_action( 'init', __NAMESPACE__ . '\\rest_oauth2_load_authorize_page' );
 	add_action( 'admin_menu', __NAMESPACE__ . '\\Admin\\register' );
+
+	// WP-Cli
+	if ( class_exists( __NAMESPACE__ . '\\Utilities\\Oauth2_Wp_Cli' ) ) {
+		\WP_CLI::add_command( 'oauth2', __NAMESPACE__ . '\\Utilities\\Oauth2_Wp_Cli' );
+	}
+
 	Admin\Profile\bootstrap();
 }
 

inc/tokens/class-authorization-code.php

@@ -108,6 +108,36 @@ public function get_expiration() {
 		return (int) $value['expiration'];
 	}
 
+	private function validate_code_verifier( $args ) {
+		$value = $this->get_value();
+
+		if ( empty( $value['code_challenge'] ) ) {
+			return true;
+		}
+
+		$code_verifier = $args['code_verifier'];
+		$is_valid = false;
+
+		switch ( strtolower( $value['code_challenge_method'] ) ) {
+			case 's256':
+				$decoded = base64_encode( hash( 'sha256', $code_verifier ) );
+				$is_valid = $decoded === $value['code_challenge'];
+				break;
+			case 'plain':
+				$is_valid = $code_verifier === $value['code_challenge'];
+			break;
+		}
+
+		if ( ! $is_valid ) {
+			return new WP_Error(
+				'oauth2.tokens.authorization_code.validate_code_verifier.invalid_grant',
+				__( 'Invalid code verifier.', 'oauth2' )
+			);
+		}
+
+		return true;
+	}
+
 	/**
 	 * Validate the code for use.
 	 *
@@ -129,7 +159,15 @@ public function validate( $args = [] ) {
 			);
 		}
 
-		return true;
+		$code_verifier = $this->validate_code_verifier( [
+				'code_verifier' => $args['code_verifier'],
+			]
+		);
+		if ( is_wp_error( $code_verifier ) ) {
+			return $code_verifier;
+		}
+
+		return $code_verifier;
 	}
 
 	/**
@@ -183,13 +221,13 @@ public static function get_by_code( Client $client, $code ) {
 	 *
 	 * @return Authorization_Code|WP_Error Authorization code instance, or error on failure.
 	 */
-	public static function create( Client $client, WP_User $user ) {
+	public static function create( Client $client, WP_User $user, $data ) {
 		$code = wp_generate_password( static::KEY_LENGTH, false );
 		$meta_key = static::KEY_PREFIX . $code;
-		$data = [
+		$data = \array_merge( [
 			'user'       => (int) $user->ID,
 			'expiration' => time() + static::MAX_AGE,
-		];
+		], $data );
 		$result = add_post_meta( $client->get_post_id(), wp_slash( $meta_key ), wp_slash( $data ), true );
 		if ( ! $result ) {
 			return new WP_Error(

inc/types/class-authorization-code.php

@@ -33,7 +33,7 @@ protected function handle_authorization_submission( $submit, Client $client, $da
 			case 'authorize':
 				// Generate authorization code and redirect back.
 				$user = wp_get_current_user();
-				$code = $client->generate_authorization_code( $user );
+				$code = $client->generate_authorization_code( $user, $data );
 				if ( is_wp_error( $code ) ) {
 					return $code;
 				}

inc/types/class-base.php

@@ -7,6 +7,7 @@
 use WP\OAuth2\Client;
 
 abstract class Base implements Type {
+
 	/**
 	 * Handle submission of authorisation page.
 	 *
@@ -25,6 +26,8 @@ abstract protected function handle_authorization_submission( $submit, Client $cl
 	 * Handle authorisation page.
 	 */
 	public function handle_authorisation() {
+		// Should probably keep this as an option in the application (e.g. force PKCE)
+		$pkce = true;
 
 		if ( empty( $_GET['client_id'] ) ) {
 			return new WP_Error(
@@ -34,10 +37,20 @@ public function handle_authorisation() {
 		}
 
 		// Gather parameters.
-		$client_id    = wp_unslash( $_GET['client_id'] );
-		$redirect_uri = isset( $_GET['redirect_uri'] ) ? wp_unslash( $_GET['redirect_uri'] ) : null;
-		$scope        = isset( $_GET['scope'] ) ? wp_unslash( $_GET['scope'] ) : null;
-		$state        = isset( $_GET['state'] ) ? wp_unslash( $_GET['state'] ) : null;
+		$client_id    			= wp_unslash( $_GET['client_id'] );
+		$redirect_uri 			= isset( $_GET['redirect_uri'] ) ? wp_unslash( $_GET['redirect_uri'] ) : null;
+		$scope        			= isset( $_GET['scope'] ) ? wp_unslash( $_GET['scope'] ) : null;
+		$state        			= isset( $_GET['state'] ) ? wp_unslash( $_GET['state'] ) : null;
+
+		if ( $pkce ) {
+			$pkce_data = $this->handle_pkce();
+			if ( is_wp_error( $pkce_data ) ) {
+				return $pkce_data;
+			}
+
+			$code_challenge = $pkce_data['code_challenge'];
+			$code_challenge_method = $pkce_data['code_challenge_method'];
+		}
 
 		$client = Client::get_by_id( $client_id );
 		if ( empty( $client ) ) {
@@ -70,7 +83,7 @@ public function handle_authorisation() {
 
 		// Check nonce.
 		$nonce_action = $this->get_nonce_action( $client );
-		if ( ! wp_verify_nonce( wp_unslash( $_POST['_wpnonce'] ), $none_action ) ) {
+		if ( ! wp_verify_nonce( wp_unslash( $_POST['_wpnonce'] ), $this->get_nonce_action( $client ) ) ) {
 			return new WP_Error(
 				'oauth2.types.authorization_code.handle_authorisation.invalid_nonce',
 				__( 'Invalid nonce.', 'oauth2' )
@@ -93,7 +106,7 @@ public function handle_authorisation() {
 
 		$submit = wp_unslash( $_POST['wp-submit'] );
 
-		$data = compact( 'redirect_uri', 'scope', 'state' );
+		$data = compact( 'redirect_uri', 'scope', 'state', 'code_challenge', 'code_challenge_method' );
 		return $this->handle_authorization_submission( $submit, $client, $data );
 	}
 
@@ -152,4 +165,44 @@ protected function render_form( Client $client, WP_Error $errors = null ) {
 	protected function get_nonce_action( Client $client ) {
 		return sprintf( 'oauth2_authorize:%s', $client->get_id() );
 	}
+
+	/**
+	 * Get and validate PKCE parameters from a request.
+	 *
+	 * @return string[] code_challenge and code_challenge_method
+	 */
+	private function handle_pkce() {
+		$code_challenge        	= isset( $_GET['code_challenge'] ) ? wp_unslash( $_GET['code_challenge'] ) : null;
+		$code_challenge_method 	= isset( $_GET['code_challenge_method'] ) ? wp_unslash( $_GET['code_challenge_method'] ) : null;
+
+		if ( ! is_null( $code_challenge ) ) {
+			if ( '' === \trim( $code_challenge ) ) {
+				return new WP_Error(
+					'oauth2.types.authorization_code.handle_authorisation.code_challenge_empty',
+					sprintf( __( 'Code challenge cannot be empty', 'oauth2' ), $client_id ),
+					[
+						'status' => WP_Http::BAD_REQUEST,
+						'client_id' => $client_id,
+					]
+				);
+			}
+
+			$code_challenge_method = is_null( $code_challenge_method ) ? 'plain' : $code_challenge_method;
+
+			if ( ! \in_array( \strtolower( $code_challenge_method ), [ 'plain', 's256' ], true ) ) {
+				return new WP_Error(
+					'oauth2.types.authorization_code.handle_authorisation.wrong_challenge_method',
+					sprintf( __( 'Challenge method must be S256 or plain', 'oauth2' ), $client_id ),
+					[
+						'status' => WP_Http::BAD_REQUEST,
+						'client_id' => $client_id,
+					]
+				);
+			}
+
+			return [ 'code_challenge' => $code_challenge, 'code_challenge_method' => $code_challenge_method ];
+		}
+
+		return false;
+	}
 }

inc/utilities/class-oauth2-wp-cli.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace WP\OAuth2\Utilities;
+
+class Oauth2_Wp_Cli extends \WP_CLI_Command {
+	/**
+	* Generate a code challenge.
+	*
+	* ## OPTIONS
+	*
+	* [<random_string>]
+	* : The string to be hashed.
+	*
+	*
+	* [--length=<length>]
+	* : The length of the random seed string.
+	* ---
+	* default: 64
+	* ---
+	*
+	* ## EXAMPLES
+	*
+	*     wp oauth2 generate-code-challenge --length=64
+	*
+	* @alias generate-code-challenge
+	*/
+	function generate_code_challenge( $args, $assoc_args ) {
+		if ( ! empty( $args[0] ) && ! empty( $assoc_args['length'] ) ) {
+			\WP_CLI::warning( 'Length parameter will be ignored since the input string was provided.' );
+		}
+
+		$length = empty( $assoc_args['length'] ) ? 64 : intval( $assoc_args['length'] );
+
+		if ( $length < 43 || $length > 128 ) {
+			\WP_CLI::error( 'Length should be >= 43 and <= 128.' );
+		}
+
+		if ( ! empty( $args[0] ) ) {
+			$random_seed = $args[0];
+
+			if ( strlen( $random_seed ) < 43 || strlen( $random_seed ) > 128 ) {
+				\WP_CLI::error( 'Length of the provided random seed should be >= 43 and <= 128.' );
+			}
+
+			\WP_CLI::warning( "Using provided string {$random_seed} as a random seed. It is recommended to use this command without parameters, 64 characters long random key will be generated automatically." );
+		} else {
+			$is_strong_crypto = true;
+			$random_seed = \bin2hex( \openssl_random_pseudo_bytes( $length / 2 + $length % 2, $is_strong_crypto ) );
+			$random_seed = \substr( $random_seed, 0, $length );
+
+			if ( ! $is_strong_crypto ) {
+				\WP_CLI::error( 'openssl_random_pseudo_bytes failed to generate a cryptographically strong random string.' );
+			}
+		}
+
+		$code_challenge = \base64_encode( hash( 'sha256', $random_seed ) );
+
+		$items = [
+			[
+				'code_verifier' => $random_seed,
+				'code_challenge = base64( sha256( code_verifier ) )' => $code_challenge,
+			],
+		];
+
+		\WP_CLI\Utils\format_items( 'table', $items, [ 'code_verifier', 'code_challenge = base64( sha256( code_verifier ) )' ] );
+	}
+}

plugin.php

@@ -28,4 +28,8 @@
 require __DIR__ . '/inc/admin/namespace.php';
 require __DIR__ . '/inc/admin/profile/namespace.php';
 
+if ( defined( 'WP_CLI' ) && WP_CLI ) {
+	require __DIR__ . '/inc/utilities/class-oauth2-wp-cli.php';
+}
+
 bootstrap();