Add support for PKCE (RFC 7636) (#130)

* Add support for PKCE (RFC 7636)

* Enhanced the AuthInfo type to also contain `codeChallenge` and `codeChallengeMethod` that would be passed to the Auth server during an authorization request if the request was using PKCE. These fields default to None, which should allow backwards compatibility with all existing implementations. The auth server that uses this library would need to decide if they were supporting PKCE and capture these values from an authorization request and set these values in the `AuthInfo` type
* Adds support for PKCE by enhancing the AuthorizationCode grant handler. The grant handler now checks the AuthInfo for a contained PKCE `codeChallenge`. If one is set, the auth code grant handler validates the PKCE challenge as part of the standard validations

* switch travis to only use openjdk for both 8 and 11

* Added toString overrides on case objects for CodeChallengeMethod

useful when serializing the type, apply method can still be used for deserialization / taking user input from authorization request launch

* Update readme.

Author: rmmeans

.travis.yml

@@ -4,7 +4,7 @@ scala:
   - 2.11.12
   - 2.13.0
 jdk:
-  - oraclejdk8
+  - openjdk8
   - openjdk11
 notifications:
   webhooks:

README.md

@@ -10,7 +10,7 @@ The idea of this library originally comes from [oauth2-server](https://github.co
 
 This library supports all grant types.
 
-- Authorization Code Grant
+- Authorization Code Grant (PKCE Authorization Code Grants are supported)
 - Resource Owner Password Credentials Grant
 - Client Credentials Grant
 - Implicit Grant
@@ -86,7 +86,9 @@ case class AuthInfo[User](
   user: User,
   clientId: Option[String],
   scope: Option[String],
-  redirectUri: Option[String]
+  redirectUri: Option[String],
+  codeChallenge: Option[String] = None,
+  codeChallengeMethod: Option[CodeChallengeMethod] = None
 )
 ```
 
@@ -100,3 +102,9 @@ case class AuthInfo[User](
   - inform the client of the scope of the access token issued
 - redirectUri
   - This value must be enabled on authorization code grant
+- codeChallenge:
+  - This value is OPTIONAL. Only set this value if doing a PKCE authorization request. When set, PKCE rules apply on the AuthorizationCode Grant Handler
+  - This value is from a PKCE authorization request. This is the challenge supplied during the auth request if given.
+- codeChallengeMethod:
+  - This value is OPTIONAL and used only by PKCE when a codeChallenge value is also set.
+  - This value is from a PKCE authorization request. This is the method used to transform the code verifier. Must be either Plain or S256. If not specified and codeChallenge is provided then Plain is assumed (per RFC7636)

src/main/scala/scalaoauth2/provider/AuthorizationRequest.scala

@@ -88,6 +88,13 @@ case class AuthorizationCodeRequest(request: AuthorizationRequest) extends Autho
    * @return redirect_uri
    */
   def redirectUri: Option[String] = param("redirect_uri")
+
+  /**
+   * Returns code_verifier
+   *
+   * @return
+   */
+  def codeVerifier: Option[String] = param("code_verifier")
 }
 
 case class ImplicitRequest(request: AuthorizationRequest) extends AuthorizationRequest(request.headers, request.params)

src/main/scala/scalaoauth2/provider/DataHandler.scala

@@ -2,6 +2,8 @@ package scalaoauth2.provider
 
 import java.util.Date
 
+import scala.util.{ Failure, Success, Try }
+
 /**
  * Provide accessing to data storage for using OAuth 2.0.
  */
@@ -29,12 +31,32 @@ case class AccessToken(token: String, refreshToken: Option[String], scope: Optio
   }
 }
 
+sealed trait CodeChallengeMethod
+case object Plain extends CodeChallengeMethod {
+  override def toString: String = "plain"
+}
+case object S256 extends CodeChallengeMethod {
+  override def toString: String = "S256"
+}
+
+object CodeChallengeMethod {
+  def apply(value: String): Try[CodeChallengeMethod] = {
+    value match {
+      case "S256" => Success(S256)
+      case "plain" => Success(Plain)
+      case _ => Failure(new InvalidRequest("transform algorithm not supported"))
+    }
+  }
+}
+
 /**
  * Authorized information
  *
  * @param user Authorized user which is registered on system.
  * @param clientId Using client id which is registered on system.
  * @param scope Inform the client of the scope of the access token issued.
  * @param redirectUri This value is used by Authorization Code Grant.
+ * @param codeChallenge This value is used by Authorization Code Grant for PKCE support.
+ * @param codeChallengeMethod This value is used by Authorization Code Grant for PKCE support.
  */
-case class AuthInfo[+U](user: U, clientId: Option[String], scope: Option[String], redirectUri: Option[String])
+case class AuthInfo[+U](user: U, clientId: Option[String], scope: Option[String], redirectUri: Option[String], codeChallenge: Option[String] = None, codeChallengeMethod: Option[CodeChallengeMethod] = None)

src/main/scala/scalaoauth2/provider/GrantHandler.scala

@@ -1,5 +1,8 @@
 package scalaoauth2.provider
 
+import java.util.Base64
+import java.security.MessageDigest
+
 import scala.concurrent.{ ExecutionContext, Future }
 
 case class GrantHandlerResult[U](
@@ -78,7 +81,7 @@ class Password extends GrantHandler {
       handler.findUser(maybeValidatedClientCred, passwordRequest).flatMap { maybeUser =>
         val user = maybeUser.getOrElse(throw new InvalidGrant("username or password is incorrect"))
         val scope = passwordRequest.scope
-        val authInfo = AuthInfo(user, maybeValidatedClientCred.map(_.clientId), scope, None)
+        val authInfo = AuthInfo(user, maybeValidatedClientCred.map(_.clientId), scope, None, None, None)
 
         issueAccessToken(handler, authInfo)
       }
@@ -95,7 +98,7 @@ class ClientCredentials extends GrantHandler {
 
     handler.findUser(maybeValidatedClientCred, clientCredentialsRequest).flatMap { optionalUser =>
       val user = optionalUser.getOrElse(throw new InvalidGrant("client_id or client_secret or scope is incorrect"))
-      val authInfo = AuthInfo(user, Some(clientId), scope, None)
+      val authInfo = AuthInfo(user, Some(clientId), scope, None, None, None)
 
       issueAccessToken(handler, authInfo)
     }
@@ -121,10 +124,27 @@ class AuthorizationCode extends GrantHandler {
         throw new RedirectUriMismatch
       }
 
+      authInfo.codeChallenge.foreach { codeChallenge =>
+        val codeVerifier = authorizationCodeRequest.codeVerifier.getOrElse(throw new InvalidGrant("PKCE validation failed, no verifier included in request"))
+
+        val isValid: Boolean = authInfo.codeChallengeMethod.getOrElse(Plain) match {
+          case Plain => codeVerifier == codeChallenge
+          case S256 =>
+            val codeVerifierBytes = codeVerifier.getBytes("ASCII")
+            val digest = MessageDigest.getInstance("SHA-256").digest(codeVerifierBytes)
+            val computedChallenge = Base64.getUrlEncoder.withoutPadding().encodeToString(digest)
+
+            computedChallenge == codeChallenge
+        }
+
+        if (!isValid)
+          throw new InvalidGrant("PKCE validation failed, values not equal.")
+      }
+
       val f = issueAccessToken(handler, authInfo)
       for {
         accessToken <- f
-        deleteResult <- handler.deleteAuthCode(code)
+        _ <- handler.deleteAuthCode(code)
       } yield accessToken
     }
   }
@@ -140,7 +160,7 @@ class Implicit extends GrantHandler {
     handler.findUser(maybeValidatedClientCred, implicitRequest).flatMap { maybeUser =>
       val user = maybeUser.getOrElse(throw new InvalidGrant("user cannot be authenticated"))
       val scope = implicitRequest.scope
-      val authInfo = AuthInfo(user, Some(clientId), scope, None)
+      val authInfo = AuthInfo(user, Some(clientId), scope, None, None, None)
 
       issueAccessToken(handler, authInfo)
     }

src/test/scala/scalaoauth2/provider/AuthorizationCodeSpec.scala

@@ -60,6 +60,103 @@ class AuthorizationCodeSpec extends FlatSpec with ScalaFutures with OptionValues
     }
   }
 
+  it should "handle a PKCE plain (implicit) request" in {
+    val authorizationCode = new AuthorizationCode()
+    val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/"), "code_verifier" -> Seq("4g94A5mKbcP1zv313x6JmVQjDJ1FiwVFBnLepwk1BLk")))
+    val clientCred = request.parseClientCredential.fold[Option[ClientCredential]](None)(_.fold(_ => None, c => Some(c)))
+    val f = authorizationCode.handleRequest(clientCred, request, new MockDataHandler() {
+
+      override def findAuthInfoByCode(code: String): Future[Option[AuthInfo[MockUser]]] = Future.successful(Some(
+        AuthInfo(user = MockUser(10000, "username"), clientId = Some("clientId1"), scope = Some("all"), redirectUri = None, codeChallenge = Some("4g94A5mKbcP1zv313x6JmVQjDJ1FiwVFBnLepwk1BLk"))))
+
+      override def createAccessToken(authInfo: AuthInfo[User]): Future[AccessToken] = Future.successful(AccessToken("token1", Some("refreshToken1"), Some("all"), Some(3600), new java.util.Date()))
+    })
+
+    whenReady(f) { result =>
+      result.tokenType shouldBe "Bearer"
+      result.accessToken shouldBe "token1"
+      result.expiresIn.value should (be <= 3600L and be > 2595L)
+      result.refreshToken shouldBe Some("refreshToken1")
+      result.scope shouldBe Some("all")
+    }
+  }
+
+  it should "handle a PKCE plain (explicit) request" in {
+    val authorizationCode = new AuthorizationCode()
+    val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/"), "code_verifier" -> Seq("4g94A5mKbcP1zv313x6JmVQjDJ1FiwVFBnLepwk1BLk")))
+    val clientCred = request.parseClientCredential.fold[Option[ClientCredential]](None)(_.fold(_ => None, c => Some(c)))
+    val f = authorizationCode.handleRequest(clientCred, request, new MockDataHandler() {
+
+      override def findAuthInfoByCode(code: String): Future[Option[AuthInfo[MockUser]]] = Future.successful(Some(
+        AuthInfo(user = MockUser(10000, "username"), clientId = Some("clientId1"), scope = Some("all"), redirectUri = None, codeChallenge = Some("4g94A5mKbcP1zv313x6JmVQjDJ1FiwVFBnLepwk1BLk"), codeChallengeMethod = Some(Plain))))
+
+      override def createAccessToken(authInfo: AuthInfo[User]): Future[AccessToken] = Future.successful(AccessToken("token1", Some("refreshToken1"), Some("all"), Some(3600), new java.util.Date()))
+    })
+
+    whenReady(f) { result =>
+      result.tokenType shouldBe "Bearer"
+      result.accessToken shouldBe "token1"
+      result.expiresIn.value should (be <= 3600L and be > 2595L)
+      result.refreshToken shouldBe Some("refreshToken1")
+      result.scope shouldBe Some("all")
+    }
+  }
+
+  it should "handle a PKCE S256 request" in {
+    val authorizationCode = new AuthorizationCode()
+    val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/"), "code_verifier" -> Seq("4g94A5mKbcP1zv313x6JmVQjDJ1FiwVFBnLepwk1BLk")))
+    val clientCred = request.parseClientCredential.fold[Option[ClientCredential]](None)(_.fold(_ => None, c => Some(c)))
+    val f = authorizationCode.handleRequest(clientCred, request, new MockDataHandler() {
+
+      override def findAuthInfoByCode(code: String): Future[Option[AuthInfo[MockUser]]] = Future.successful(Some(
+        AuthInfo(user = MockUser(10000, "username"), clientId = Some("clientId1"), scope = Some("all"), redirectUri = None, codeChallenge = Some("aLE640XFc4YAPoVB3KCUhcjoMRDQhyILWy9k9qpiBfo"), codeChallengeMethod = Some(S256))))
+
+      override def createAccessToken(authInfo: AuthInfo[User]): Future[AccessToken] = Future.successful(AccessToken("token1", Some("refreshToken1"), Some("all"), Some(3600), new java.util.Date()))
+    })
+
+    whenReady(f) { result =>
+      result.tokenType shouldBe "Bearer"
+      result.accessToken shouldBe "token1"
+      result.expiresIn.value should (be <= 3600L and be > 2595L)
+      result.refreshToken shouldBe Some("refreshToken1")
+      result.scope shouldBe Some("all")
+    }
+  }
+
+  it should "return a InvalidGrant if PKCE validation fails for equality" in {
+    val authorizationCode = new AuthorizationCode()
+    val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/"), "code_verifier" -> Seq("iB3OM4lYP6k03yT_sMGr1o_Mf-lOX84mrM7jRkm21Ak")))
+    val clientCred = request.parseClientCredential.fold[Option[ClientCredential]](None)(_.fold(_ => None, c => Some(c)))
+    val f = authorizationCode.handleRequest(clientCred, request, new MockDataHandler() {
+
+      override def findAuthInfoByCode(code: String): Future[Option[AuthInfo[MockUser]]] = Future.successful(Some(
+        AuthInfo(user = MockUser(10000, "username"), clientId = Some("clientId1"), scope = Some("all"), redirectUri = None, codeChallenge = Some("aLE640XFc4YAPoVB3KCUhcjoMRDQhyILWy9k9qpiBfo"), codeChallengeMethod = Some(S256))))
+
+      override def createAccessToken(authInfo: AuthInfo[User]): Future[AccessToken] = Future.successful(AccessToken("token1", Some("refreshToken1"), Some("all"), Some(3600), new java.util.Date()))
+    })
+
+    whenReady(f.failed) { e =>
+      e shouldBe a[InvalidGrant]
+    }
+  }
+
+  it should "return a InvalidGrant if code_verifier is not included when AuthInfo contains a codeChallenge" in {
+    val authorizationCode = new AuthorizationCode()
+    val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/")))
+    val clientCred = request.parseClientCredential.fold[Option[ClientCredential]](None)(_.fold(_ => None, c => Some(c)))
+    val f = authorizationCode.handleRequest(clientCred, request, new MockDataHandler() {
+
+      override def findAuthInfoByCode(code: String): Future[Option[AuthInfo[MockUser]]] = Future.successful(Some(
+        AuthInfo(user = MockUser(10000, "username"), clientId = Some("clientId1"), scope = Some("all"), redirectUri = None, codeChallenge = Some("aLE640XFc4YAPoVB3KCUhcjoMRDQhyILWy9k9qpiBfo"))))
+
+      override def createAccessToken(authInfo: AuthInfo[User]): Future[AccessToken] = Future.successful(AccessToken("token1", Some("refreshToken1"), Some("all"), Some(3600), new java.util.Date()))
+    })
+
+    whenReady(f.failed) { e =>
+      e shouldBe a[InvalidGrant]
+    }
+  }
+
   it should "return a Failure Future" in {
     val authorizationCode = new AuthorizationCode()
     val request = new AuthorizationRequest(Map(), Map("client_id" -> Seq("clientId1"), "client_secret" -> Seq("clientSecret1"), "code" -> Seq("code1"), "redirect_uri" -> Seq("http://example.com/")))

src/test/scala/scalaoauth2/provider/DataHandlerSpec.scala

@@ -0,0 +1,34 @@
+package scalaoauth2.provider
+
+import org.scalatest.Matchers._
+import org.scalatest._
+
+import scala.util.Success
+
+class DataHandlerSpec extends FlatSpec with TryValues {
+
+  it should "parse a PKCE code challenge method of plain" in {
+    CodeChallengeMethod("plain") should be(Success(Plain))
+  }
+
+  it should "parse a PKCE code challenge method of S256" in {
+    CodeChallengeMethod("S256") should be(Success(S256))
+  }
+
+  it should "turn a PKCE code challenge method type of S256 back to a string value of S256" in {
+    val method: CodeChallengeMethod = S256
+    method.toString should be("S256")
+  }
+
+  it should "turn a PKCE code challenge method type of plain back to a string value of plain" in {
+    val method: CodeChallengeMethod = Plain
+    method.toString should be("plain")
+  }
+
+  it should "return a failure if non valid PKCE code challenge method" in {
+    val attempt = CodeChallengeMethod("made-up")
+    attempt.isFailure shouldBe true
+    attempt.failure.exception.isInstanceOf[InvalidRequest]
+    attempt.failure.exception.getMessage should be("transform algorithm not supported")
+  }
+}