Implementing authorization for API on the top of Play Framework 2.4*

The article considers the implementation of an easy to use authorization mechanism based on Play Framework 2.4* Actions architecture with full power of classical Actions

Introduction

It is a very oft-repeated task while we are creating public API, we need a mechanism for authorization of requests. Ideally, it should not depend on the type of requests, so that we can check sign for all API calls. In this article, we take a look at approaches how can we do that in Play framework, problems that can appear and we propose one of the possible solutions, that from the point of the author seems to be comfortable in use.

I like the approach of SecureSocial, and of course, we can use it. However, SecureSocail is too huge for such simple task; I do not need functionality with all oAuth and oAuth2 logic, and there is much stuff that I should implement to get it working. So we just get some approaches from there, and write own authorization with BlackJack and Friends ;)

Authorization with Blackjack and Friends

First, let's define our Authorization trait. To simplify task( we do not want to write separate authorization logic for different content types), let’s define isAuthorized method with input parameter request, already parameterized by String - that means that we handle body only as a string: Request[String]

trait Authorization {

  /**
    * Checks whether the API client is authorized to execute an action or not.
    *
    * @return
    */
  def isAuthorized(request: Request[String]): Boolean

}

Note: The other way was to parameterise request with AnyContent, it sounds like a more general way - because we can parse such request with default body parser to any supported content type. In the case of simplicity, I decided to choose String.

Next, we define some implementation of Authorization trait; let's assume that we want to sign each request with some token constructed as “${signature}_${publicKey}”(where signature - calculated sign for request data and publicKey - public key for API):

import play.api.Logger
import play.api.mvc.{ Request}

object Authorization {
  val TOKEN_PARAM = "token"
}

class TokenAuthorization(signatureCalculator: ApiSignatureCalculator, store: TokenStore) extends Authorization {

  import Authorization._
  val log = Logger(getClass)
  /**
    * Checks whether the API client is authorized to execute an action or not.
    *
    * @return
    */
  override def isAuthorized(request: Request[String]): Boolean = {
    log.info(s">>>> isAuthorized - Params : [$request]")
    request.getQueryString(TOKEN_PARAM).exists { signString =>
      val splittedString:List[String] = signString.split("_").toList
      val sign = splittedString.headOption.getOrElse("")
      val publicKey = splittedString.tail.headOption.getOrElse("")
      val tokenOpt = store.token(publicKey)
      log.info(s"---- isAuthorized - sign: [$sign] token: [$tokenOpt] ")
      log.info(s"---- isAuthorized - request uri: ${request.uri}")
      tokenOpt.exists { token =>
        signatureCalculator.sign(
          privateKey = token.privateKey,
          method = request.method,
          uri = request.uri.replaceAll("\\?.*", ""),
          queryParams = request.queryString.mapValues(_.headOption).collect {
            case (key, Some(value)) => (key, value)
          } - TOKEN_PARAM,
          body = request.body
        ).map(_ == sign).getOrElse(false)
      }
    }
  }
  
}

Where TokenStore - store of mapping between public and private keys:

case class Token(publicKey: String, privateKey: String)

trait TokenStore {
  def tokens: Seq[Token]

  def token(publicKey: String): Option[Token]
}

moreover, ApiSignatureCalculator - implements the logic how to sign request data

trait ApiSignatureCalculator {

  def sign(privateKey: String,
              method: String,
              uri: String,
              queryParams: Map[String, String],
              body: String):Try[String]
}

Controllers in Play Framework

In Play Framework controllers consist of methods that create Action objects to handle the incoming requests. For example in the HelloController below the helloWorld and hello methods create actions that return a “hello” message to the client. In this case, the action objects are constructed using the apply factory method of the Action singleton object.

import play.api.Logger
import play.api.mvc._

class HelloController extends Controller {

  def helloWorld = Action { request =>
     val body: AnyContent = request.body
     val jsonBody: Option[JsValue] = body.asJson
     // …. some logic with body
    Ok("Hello World")
  }

  def hello(name: String) = Action(parse.json) { request => 
   // here request.body is already an instance of JsValue
    // …. some logic with body
    Ok(s"Hello $name")
  }
}

Also, as you can see in the example above Play Framework has a powerful concept of Body parsers.

So, what we need?

class HelloController extends SecuredController {

  def helloWorld = SecuredAction { request =>
     val body: AnyContent = request.body
     val jsonBody: Option[JsValue] = body.asJson
     // …. some logic 
    Ok("Hello World")
  }

  def hello(name: String) = SecuredAction(parse.json) { request =>
    // …. some logic 
    Ok(s"Hello $name")
  }
}

What problems may appear?

DualBodyParser

final case class DualBodyParser[+A, +B](
                                           a: BodyParser[A],
                                           b: BodyParser[B]
                                         )(
                                           implicit ec: ExecutionContext = defaultContext
                                         )
    extends BodyParser[(A, B)]
  {
    def apply(v1: RequestHeader): Iteratee[Array[Byte], Either[Result, (A, B)]] =
      Enumeratee.zipWith(a(v1), b(v1)) {
        case (Left(va), _) => Left(va)
        case (_, Left(vb)) => Left(vb)
        case (Right(va), Right(vb)) => Right((va, vb))
      }
  }

SecuredRequest, SecuredActionBuilder and SecuredAction

object SecuredController {
  case class SecuredRequest[A](request: Request[A]) extends WrappedRequest(request)
}

abstract class SecuredController(authorize: Authorization) extends Controller {
    // …. here we will define SecuredActionBuilder and SecuredAction
}

final def async[A](bodyParser: BodyParser[A])(block: R[A] => Future[Result]): Action[A] = composeAction(new Action[A] {
    def parser = composeParser(bodyParser)
    def apply(request: Request[A]) = try {
      invokeBlock(request, block)
    } catch {
      // NotImplementedError is not caught by NonFatal, wrap it
      case e: NotImplementedError => throw new RuntimeException(e)
      // LinkageError is similarly harmless in Play Framework, since automatic reloading could easily trigger it
      case e: LinkageError => throw new RuntimeException(e)
    }
    override def executionContext = ActionBuilder.this.executionContext
  })

class SecuredActionBuilder(authorizeOpt: Option[Authorization]) extends ActionFunction[Request, Request] {
    self =>

    val log = Logger(getClass)

    final def async[A](bodyParser: BodyParser[A])(block: Request[A] => Future[Result]): Action[(String,A)] =
      composeAction(
        new Action[(String, A)] {
          def parser = DualBodyParser(parse.tolerantText, composeParser(bodyParser))
          def apply(request: Request[(String,A)]) = try {
            log.info(s"---- async - authorize: $authorizeOpt")
            if (authorizeOpt.isEmpty || authorizeOpt.get.isAuthorized(request map (_._1))) {
              invokeBlock(request map (_._2), block)
            } else {
              failUnauthorized("Not Authorized")
            }
          } catch {
            case e: NotImplementedError => throw new RuntimeException(e)
            case e: LinkageError => throw new RuntimeException(e)
          }
          override def executionContext = self.executionContext
        }
      )

    // here you should define your own logic how to handle unathorized requests
    def failUnauthorized(error: String): Future[Result] = Future.successful{
       Ok(Json.stringify(Json.obj(
         "result" -> "error",
         "code" -> 401,
         "message" -> error
       )))
    }

    // Note: the result Actions now will be parameterized with tuple (String, A) - where A - content parsed with body parser
    final def apply[A](bodyParser: BodyParser[A])(block: Request[A] => Result): Action[(String,A)] = async(bodyParser) { req: Request[A] =>
      Future.successful(block(req))
    }
    final def apply(block: Request[AnyContent] => Result): Action[(String,AnyContent)] = apply(BodyParsers.parse.default)(block)
    final def apply(block: => Result): Action[(String,AnyContent)] = apply(_ => block)
    final def async(block: => Future[Result]): Action[(String,AnyContent)] = async(_ => block)
    final def async(block: Request[AnyContent] => Future[Result]): Action[(String,AnyContent)] = async(BodyParsers.parse.default)(block)

    //  standard implemetation of the ActionBuilder
    protected def composeParser[A](bodyParser: BodyParser[A]): BodyParser[A] = bodyParser
    protected def composeAction[A](action: Action[A]): Action[A] = action
    override def andThen[Q[_]](other: ActionFunction[Request, Q]): ActionBuilder[Q] = new ActionBuilder[Q] {
      def invokeBlock[A](request: Request[A], block: Q[A] => Future[Result]) =
        self.invokeBlock[A](request, other.invokeBlock[A](_, block))
      override protected def composeParser[A](bodyParser: BodyParser[A]): BodyParser[A] = self.composeParser(bodyParser)
      override protected def composeAction[A](action: Action[A]): Action[A] = self.composeAction(action)
    }
    override def invokeBlock[A](request: Request[A], block: (Request[A]) => Future[Result]): Future[Result] = block(request)
}  

object SecuredAction extends SecuredActionBuilder(Some(authorize)) {
    
    def apply[A]() = new SecuredActionBuilder(Some(authorize))

    def apply[A](authorize: Authorization) = new SecuredActionBuilder(Some(authorize))
}

import play.api.Logger
import play.api.libs.iteratee.{Enumeratee, Iteratee}
import play.api.libs.json.Json
import play.api.mvc._
import play.api.libs.concurrent.Execution.defaultContext
import scala.concurrent.{ExecutionContext, Future}

object SecuredController {
  case class SecuredRequest[A](request: Request[A]) extends WrappedRequest(request)
}

abstract class SecuredController(authorize: Authorization) extends Controller {

  object SecuredAction extends SecuredActionBuilder(Some(authorize)) {

    def apply[A]() = new SecuredActionBuilder(Some(authorize))

    def apply[A](authorize: Authorization) = new SecuredActionBuilder(Some(authorize))
  }

  final case class DualBodyParser[+A, +B](
                                           a: BodyParser[A],
                                           b: BodyParser[B]
                                         )(
                                           implicit ec: ExecutionContext = defaultContext
                                         )
    extends BodyParser[(A, B)]
  {
    def apply(v1: RequestHeader): Iteratee[Array[Byte], Either[Result, (A, B)]] =
      Enumeratee.zipWith(a(v1), b(v1)) {
        case (Left(va), _) => Left(va)
        case (_, Left(vb)) => Left(vb)
        case (Right(va), Right(vb)) => Right((va, vb))
      }
  }

  class SecuredActionBuilder(authorizeOpt: Option[Authorization]) extends ActionFunction[Request, Request] {
    self =>

    val log = Logger(getClass)
    final def apply[A](bodyParser: BodyParser[A])(block: Request[A] => Result): Action[(String,A)] = async(bodyParser) { req: Request[A] =>
      Future.successful(block(req))
    }
    final def apply(block: Request[AnyContent] => Result): Action[(String,AnyContent)] = apply(BodyParsers.parse.default)(block)
    final def apply(block: => Result): Action[(String,AnyContent)] = apply(_ => block)
    final def async(block: => Future[Result]): Action[(String,AnyContent)] = async(_ => block)
    final def async(block: Request[AnyContent] => Future[Result]): Action[(String,AnyContent)] = async(BodyParsers.parse.default)(block)

    final def async[A](bodyParser: BodyParser[A])(block: Request[A] => Future[Result]): Action[(String,A)] =
      composeAction(
        new Action[(String, A)] {
          def parser = DualBodyParser(parse.tolerantText, composeParser(bodyParser))
          def apply(request: Request[(String,A)]) = try {
            log.info(s"---- async - authorize: $authorizeOpt")
            if (authorizeOpt.isEmpty || authorizeOpt.get.isAuthorized(request map (_._1))) {
              invokeBlock(request map (_._2), block)
            } else {
              failUnauthorized("Not Authorized")
            }
          } catch {
            case e: NotImplementedError => throw new RuntimeException(e)
            case e: LinkageError => throw new RuntimeException(e)
          }
          override def executionContext = self.executionContext
        }
      )


    def failUnauthorized(error: String): Future[Result] = Future.successful{
      Ok(Json.stringify(Json.obj(
        "result" -> "error",
        "code" -> 401,
        "message" -> error
      )))
    }
    protected def composeParser[A](bodyParser: BodyParser[A]): BodyParser[A] = bodyParser
    protected def composeAction[A](action: Action[A]): Action[A] = action
    override def andThen[Q[_]](other: ActionFunction[Request, Q]): ActionBuilder[Q] = new ActionBuilder[Q] {
      def invokeBlock[A](request: Request[A], block: Q[A] => Future[Result]) =
        self.invokeBlock[A](request, other.invokeBlock[A](_, block))
      override protected def composeParser[A](bodyParser: BodyParser[A]): BodyParser[A] = self.composeParser(bodyParser)
      override protected def composeAction[A](action: Action[A]): Action[A] = self.composeAction(action)
    }
    override def invokeBlock[A](request: Request[A], block: (Request[A]) => Future[Result]): Future[Result] = block(request)
  }


}

Results

import com.google.inject.{Inject, Provider}
import com.typesafe.config.Config
import net.codingwell.scalaguice.ScalaModule

case class TokenStoreImplementation(tokens: Seq[Token]) extends TokenStore {

  val tokenMap = tokens.map(t => (t.publicKey, t)).toMap

  def token(publicKey: String): Option[Token] = tokenMap.get(publicKey)
}

class TokenStoreProvider @Inject()(conf: Config) extends Provider[TokenStore] {
  def get() = {
    TokenStoreImplementation(
      tokens = // get your tokens from config or db etc.
    )
  }
}

class AuthorizationProvider @Inject()(store: TokenStore) extends Provider[Authorization] {
  def get() = new TokenAuthorization(
    signatureCalculator = // provide your logic for calculating sign
    store = store
  )
}

object AuthorizationModule extends ScalaModule {
  def configure(): Unit = {
    bind[TokenStore].toProvider[TokenStoreProvider].asEagerSingleton()
    bind[Authorization].toProvider[AuthorizationProvider].asEagerSingleton()
  }
}

class HelloController @Inject() (authorize: Authorization) extends SecuredController(authorize) {

  def helloWorld = SecuredAction { request =>
     val body: AnyContent = request.body
     val jsonBody: Option[JsValue] = body.asJson
     // …. some logic
    Ok("Hello World")
  }

  def hello(name: String) = SecuredAction(parse.json) { request =>
    // …. some logic
    Ok(s"Hello $name")
  }
}

Voilà, that is it! I hope you have enjoyed this article, and it will be helpful for you .
Cheers!

Resources:

• SecureSocial
• Stackoverflow
• Actions Composition
• Scala Body Parsers