authenticateBasic

Signature

type Authenticator[T] = Credentials ⇒ Option[T]

def authenticateBasic[T](realm: String, authenticator: Authenticator[T]): AuthenticationDirective[T]

Description

Wraps the inner route with Http Basic authentication support using a given Authenticator[T].

Provides support for handling HTTP Basic Authentication.

Given a function returning Some[T] upon successful authentication and None otherwise, respectively applies the inner route or rejects the request with a AuthenticationFailedRejection rejection, which by default is mapped to an 401 Unauthorized response.

Longer-running authentication tasks (like looking up credentials in a database) should use the authenticateBasicAsync variant of this directive which allows it to run without blocking routing layer of Akka HTTP, freeing it for other requests.

Standard HTTP-based authentication which uses the WWW-Authenticate header containing challenge data and Authorization header for receiving credentials is implemented in subclasses of HttpAuthenticator.

See Credentials and password timing attacks for details about verifying the secret.

Example

def myUserPassAuthenticator(credentials: Credentials): Option[String] =
  credentials match {
    case p @ Credentials.Provided(id) if p.verify("p4ssw0rd") => Some(id)
    case _ => None
  }

val route =
  Route.seal {
    path("secured") {
      authenticateBasic(realm = "secure site", myUserPassAuthenticator) { userName =>
        complete(s"The user is '$userName'")
      }
    }
  }

// tests:
Get("/secured") ~> route ~> check {
  status shouldEqual StatusCodes.Unauthorized
  responseAs[String] shouldEqual "The resource requires authentication, which was not supplied with the request"
  header[`WWW-Authenticate`].get.challenges.head shouldEqual HttpChallenge("Basic", Some("secure site"), Map("charset" → "UTF-8"))
}

val validCredentials = BasicHttpCredentials("John", "p4ssw0rd")
Get("/secured") ~> addCredentials(validCredentials) ~> // adds Authorization header
  route ~> check {
    responseAs[String] shouldEqual "The user is 'John'"
  }

val invalidCredentials = BasicHttpCredentials("Peter", "pan")
Get("/secured") ~>
  addCredentials(invalidCredentials) ~> // adds Authorization header
  route ~> check {
    status shouldEqual StatusCodes.Unauthorized
    responseAs[String] shouldEqual "The supplied authentication is invalid"
    header[`WWW-Authenticate`].get.challenges.head shouldEqual HttpChallenge("Basic", Some("secure site"), Map("charset" → "UTF-8"))
  }