=doc #18968 Document auth options for Java DSL

akka-docs-dev/rst/java/http/routing-dsl/request-vals/http-basic-authenticator.rst

@@ -0,0 +1,38 @@
+.. _http-basic-authenticator-java:
+
+Request Values: Http Basic Auth
+===============================
+
+An abstract class to implement HTTP basic authentication
+
+Description
+-----------
+Http basic auth allows for protection of one or more routes with a username and password.
+
+To use it you subclass ``HttpBasicAuthenticator`` and provide your authentication logic.
+There are two factory methods to create the authentication results to return from the authentication logic:
+``authenticateAs(T)`` and ``refuseAccess()``. If the authentication is not very quick in memory, for example
+calls a database, make sure you do not block the web server thread by executing that in a separate ``Future``
+and then ``flatMap`` the result into the authentication result.
+
+When you use the authenticator in your routes you must reference the concrete authenticator twice,
+first as a directive wrapping all the routes it should be required for, and then as a request
+value to extract the user object for use inside the logic of the handler.
+
+Note that to protect developers from opening up for a timing attack on the password it is not available
+directly, instead a constant time string comparison is provided. For more information about timing attacks
+on passwords see for example `Timing Attacks Explained`_ .
+
+.. _Timing Attacks Explained: http://emerose.com/timing-attacks-explained
+
+
+Example
+-------
+
+Authenticating or refusing access to a user based on a hardcoded password and using a ``String`` with the
+username as internal representation of a user (in a real application it would probably be an instance of
+a richer class describing an authenticated user).
+
+
+.. includecode:: ../../../code/docs/http/javadsl/server/HttpBasicAuthenticatorExample.java
+   :include: basic-authenticator-java

akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst

@@ -43,6 +43,10 @@ akka.http.javadsl.server.values.FormFieldsPathMatchers
   Contains request values to match and access URI path segments.
 akka.http.javadsl.server.values.FormFieldsCustomRequestVal
   An abstract class to implement arbitrary custom request values.
+:ref:`akka.http.javadsl.server.values.HttpBasicAuthenticator.scala <http-basic-authenticator-java>`
+  An abstract class to implement HTTP basic authentication
+:ref:`akka.http.javadsl.server.values.OAuth2Authenticator <oauth2-authenticator-java>`
+  An abstract class to implement Oauth 2 bearer token authentication
 
 See also
 --------
@@ -52,3 +56,5 @@ See also
 
   form-field-request-vals
   header-request-vals
+  http-basic-authenticator
+  oauth2-authenticator

akka-docs-dev/rst/java/http/routing-dsl/request-vals/oauth2-authenticator.rst

@@ -0,0 +1,47 @@
+.. _oauth2-authenticator-java:
+
+Request Values: OAuth 2 Bearer Token Authentication
+===================================================
+
+An abstract class to implement Oauth 2 bearer token authentication
+
+Description
+-----------
+Allows to protect one of more routes with authentication in the form of a OAuth2 Bearer Token. For more information
+about OAuth 2 Bearer Token see `RFC6750`_.
+
+.. _RFC6750: https://tools.ietf.org/html/rfc6750
+
+To use it you subclass ``OAutht2Authenticator`` and implement the ``authenticate`` method
+to provide your own logic which verifies the OAuth2 credentials. When verification is done
+the request can either be refused by returning the return value of ``refuseAccess()`` or completed
+with an object that is application specific by returning the return value of ``authenticateAs(T)``.
+
+If the authentication is not very quick in memory, for example calls a separate authentication server
+to verify the token, make sure you do not block the web server thread by executing that in a separate ``Future``
+and then ``flatMap`` the result into the authentication result.
+
+.. note:: OAuth2 Bearer Token sends the token as clear text and should ONLY EVER be used over
+          SSL/TLS
+
+When you use the OAuth2 authenticator in your routes you must reference the concrete authenticator twice,
+first as a directive wrapping all the routes it should be required for, and then as a request
+value to extract the user object for use inside the logic of the handler.
+
+Note that to protect developers from opening up for a timing attack on the token it is not available
+directly, instead a constant time string comparison is provided. For more information about timing attacks
+on passwords see for example `Timing Attacks Explained`_ .
+
+.. _Timing Attacks Explained: http://emerose.com/timing-attacks-explained
+
+
+Example
+-------
+
+Authenticating or refusing access to a user based on a hardcoded token and using a ``String`` with the
+identity as internal representation of a user (in a real application it would probably be an instance of
+a richer class describing an authenticated user).
+
+
+.. includecode:: ../../../code/docs/http/javadsl/server/OAuth2AuthenticatorExample.java
+   :include: oauth2-authenticator-java