Documentation

§OAuth

OAuth is a simple way to publish and interact with protected data. It’s also a safer and more secure way for people to give you access. For example, it can be used to access your users’ data on Twitter.

There are two very different versions of OAuth: OAuth 1.0 and OAuth 2.0. Version 2 is simple enough to be implemented easily without library or helpers, so Play only provides support for OAuth 1.0.

§Usage

To use OAuth, first add ws to your build.sbt file:

libraryDependencies ++= Seq(
  ws
)

§Required Information

OAuth requires you to register your application to the service provider. Make sure to check the callback URL that you provide, because the service provider may reject your calls if they don’t match. When working locally, you can use /etc/hosts to fake a domain on your local machine.

The service provider will give you:

§Authentication Flow

Most of the flow will be done by the Play library.

  1. Get a request token from the server (in a server-to-server call)
  2. Redirect the user to the service provider, where he will grant your application rights to use his data
  3. The service provider will redirect the user back, giving you a /verifier/
  4. With that verifier, exchange the /request token/ for an /access token/ (server-to-server call)

Now the /access token/ can be passed to any call to access protected data.

More details on OAuth’s process flow are available at The OAuth Bible.

§Example

To implement the flow in a controller, define the key and the consumer secret and retrieve the token and secret:

val KEY = ConsumerKey("xxxxx", "xxxxx")

val oauth = OAuth(
  ServiceInfo(
    "https://api.twitter.com/oauth/request_token",
    "https://api.twitter.com/oauth/access_token",
    "https://api.twitter.com/oauth/authorize",
    KEY
  ),
  true
)

def sessionTokenPair(implicit request: RequestHeader): Option[RequestToken] = {
  for {
    token  <- request.session.get("token")
    secret <- request.session.get("secret")
  } yield {
    RequestToken(token, secret)
  }
}

def authenticate = Action { (request: Request[AnyContent]) =>
  request
    .getQueryString("oauth_verifier")
    .map { verifier =>
      val tokenPair = sessionTokenPair(request).get
      // We got the verifier; now get the access token, store it and back to index
      oauth.retrieveAccessToken(tokenPair, verifier) match {
        case Right(t) => {
          // We received the authorized tokens in the OAuth object - store it before we proceed
          Redirect(routes.Application.index).withSession("token" -> t.token, "secret" -> t.secret)
        }
        case Left(e) => throw e
      }
    }
    .getOrElse(oauth.retrieveRequestToken("https://localhost:9000/auth") match {
      case Right(t) => {
        // We received the unauthorized tokens in the OAuth object - store it before we proceed
        Redirect(oauth.redirectUrl(t.token)).withSession("token" -> t.token, "secret" -> t.secret)
      }
      case Left(e) => throw e
    })
}

After implementing the flow, the timeline is available by signing requests through WS:

def timeline = Action.async { implicit request: Request[AnyContent] =>
  sessionTokenPair match {
    case Some(credentials) => {
      wsClient
        .url("https://api.twitter.com/1.1/statuses/home_timeline.json")
        .sign(OAuthCalculator(KEY, credentials))
        .get()
        .map(result => Ok(result.json))
    }
    case _ => Future.successful(Redirect(routes.Application.authenticate))
  }
}

Note: OAuth does not provide any protection against MITM attacks. This example shows the OAuth token and secret stored in a session cookie – for the best security, always use HTTPS with play.http.session.cookie.secure=true defined.

Next: Integrating with Pekko

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.