Merge pull request #18627 from ktoso/wip-directives-bonanza-ktoso
Akka HTTP Directives Documentation Bonanza
This commit is contained in:
Konrad Malawski
commit
de9262ab8a
48 changed files with 1451 additions and 193 deletions
|
|
@ -3,7 +3,7 @@
|
|||
extractLog
|
||||
==========
|
||||
|
||||
...
|
||||
Extracts a :class:`LoggingAdapter` from the request context which can be used for logging inside the route.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,10 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
The ``extractLog`` directive is used for providing logging to routes, such that they don't have to depend on
|
||||
closing over a logger provided in the class body.
|
||||
|
||||
See :ref:`-extract-` and :ref:`ProvideDirectives` for an overview of similar directives.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,11 @@
|
|||
extractRequestContext
|
||||
=====================
|
||||
|
||||
...
|
||||
Extracts the request's underlying :class:`RequestContext`.
|
||||
|
||||
This directive is used as a building block for most of the other directives,
|
||||
which extract the context and by inspecting some of it's values can decide
|
||||
what to do with the request - for example provide a value, or reject the request.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
extractSettings
|
||||
===============
|
||||
|
||||
...
|
||||
Extracts the ``RoutingSettings`` from the :class:`RequestContext`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,10 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Extracts the ``RoutingSettings`` from the :class:`RequestContext`.
|
||||
|
||||
By default the settings of the ``Http()`` extension running the route will be returned.
|
||||
It is possible to override the settings for specific sub-routes by using the :ref:`-withSettings-` directive.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
withExecutionContext
|
||||
====================
|
||||
|
||||
...
|
||||
Runs its inner route with the given alternative :class:`ExecutionContext`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,11 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Allows running an inner route using an alternative ``ExecutionContext`` in place of the default one.
|
||||
|
||||
The execution context can be extracted in an inner route using :ref:`-extractExecutionContext-` directly,
|
||||
or used by directives which internally extract the materializer without sufracing this fact in the API.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
withLog
|
||||
=======
|
||||
|
||||
...
|
||||
Runs its inner route with the given alternative :class:`LoggingAdapter`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,11 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Allows running an inner route using an alternative :class:`LoggingAdapter` in place of the default one.
|
||||
|
||||
The logging adapter can be extracted in an inner route using :ref:`-extractLog-` directly,
|
||||
or used by directives which internally extract the materializer without sufracing this fact in the API.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
withMaterializer
|
||||
================
|
||||
|
||||
...
|
||||
Runs its inner route with the given alternative ``Materializer``.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,11 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Allows running an inner route using an alternative ``Materializer`` in place of the default one.
|
||||
|
||||
The materializer can be extracted in an inner route using :ref:`-extractMaterializer-` directly,
|
||||
or used by directives which internally extract the materializer without sufracing this fact in the API
|
||||
(e.g. responding with a Chunked entity).
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
withSettings
|
||||
============
|
||||
|
||||
...
|
||||
Runs its inner route with the given alternative :class:`RoutingSettings`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,10 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Allows running an inner route using an alternative :class:`RoutingSettings` in place of the default one.
|
||||
|
||||
The execution context can be extracted in an inner route using :ref:`-extractSettings-` directly,
|
||||
or used by directives which internally extract the materializer without sufracing this fact in the API.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -11,3 +11,11 @@ Signature
|
|||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala
|
||||
:snippet: getFromBrowseableDirectory
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
|
||||
:snippet: 0extractSettings
|
||||
|
|
@ -24,3 +24,8 @@ To serve a single file use ``getFromFile``. To serve browsable directory listing
|
|||
To serve files from a classpath directory use ``getFromResourceDirectory`` instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
|
|
@ -20,4 +20,9 @@ some other thread !). If the file cannot be found or read the request is rejecte
|
|||
To serve files from a directory use ``getFromDirectory``, instead. To serve a file from a classpath resource
|
||||
use ``getFromResource`` instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
|
|
@ -14,10 +14,15 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread (but potentially
|
||||
The actual I/O operation is running detached in a ``Future``, so it doesn't block the current thread (but potentially
|
||||
some other thread !). If the file cannot be found or read the request is rejected.
|
||||
|
||||
To serve files from a classpath directory use ``getFromResourceDirectory`` instead. To serve files from a filesystem
|
||||
directory use ``getFromDirectory``, instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
|
|
@ -20,4 +20,9 @@ some other thread !). If the file cannot be found or read the request is rejecte
|
|||
To serve a single resource use ``getFromResource``, instead. To server files from a filesystem directory use
|
||||
``getFromDirectory`` instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
|
|
@ -21,4 +21,9 @@ instead.
|
|||
|
||||
The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
|
|
@ -17,3 +17,9 @@ Description
|
|||
|
||||
The ``optionalHeaderValue`` directive is similar to the ``headerValue`` directive but always extracts an ``Option``
|
||||
value instead of rejecting the request if no matching header could be found.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
|
||||
:snippet: optionalHeaderValue-0
|
||||
|
|
|
|||
|
|
@ -16,3 +16,9 @@ Description
|
|||
|
||||
The ``optionalHeaderValueByName`` directive is similar to the ``headerValueByName`` directive but always extracts
|
||||
an ``Option`` value instead of rejecting the request if no matching header could be found.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
|
||||
:snippet: optionalHeaderValueByName-0
|
||||
|
|
@ -17,3 +17,9 @@ Description
|
|||
|
||||
The ``optionalHeaderValuePF`` directive is similar to the ``headerValuePF`` directive but always extracts an ``Option``
|
||||
value instead of rejecting the request if no matching header could be found.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
|
||||
:snippet: optionalHeaderValuePF-0
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
extractMethod
|
||||
=============
|
||||
|
||||
...
|
||||
Extracts the :class:`HttpMethod` from the request context which can be used programatically in a route.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,10 +14,14 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Extracts the :class:`HttpMethod` from the request context and provides it for use for other directives explicitly.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
In the below example our route first matches all ``GET`` requests, and if an incoming request wasn't a ``GET``,
|
||||
the matching continues and the extractMethod route will be applied which we can use to programatically
|
||||
print what type of request it was - independent of what actual HttpMethod it was:
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
|
||||
:snippet: 0extractMethod
|
||||
:snippet: extractMethod-example
|
||||
|
|
|
|||
|
|
@ -3,8 +3,7 @@
|
|||
validate
|
||||
========
|
||||
|
||||
Checks an arbitrary condition and passes control to the inner route if it returns ``true``. Otherwise, rejects the
|
||||
request with a ``ValidationRejection`` containing the given error message.
|
||||
Allows validating a precondition before handling a route.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -12,6 +11,11 @@ Signature
|
|||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala
|
||||
:snippet: validate
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
Checks an arbitrary condition and passes control to the inner route if it returns ``true``.
|
||||
Otherwise, rejects the request with a ``ValidationRejection`` containing the given error message.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,10 @@
|
|||
redirectToNoTrailingSlashIfPresent
|
||||
==================================
|
||||
|
||||
...
|
||||
If the requested path does end with a trailing ``/`` character,
|
||||
redirects to the same path without that trailing slash..
|
||||
|
||||
Opposite of :ref:`-redirectToTrailingSlashIfMissing-`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,10 +17,22 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Redirects the HTTP Client to the same resource yet without the trailing ``/``, in case the request contained it.
|
||||
When redirecting an HttpResponse with the given redirect response code (i.e. ``MovedPermanently`` or ``TemporaryRedirect``
|
||||
etc.) as well as a simple HTML page containing a "*click me to follow redirect*" link to be used in case the client can not,
|
||||
or refuses to for security reasons, automatically follow redirects.
|
||||
|
||||
Please note that the inner paths **MUST NOT** end with an explicit trailing slash (e.g. ``"things"./``)
|
||||
for the re-directed-to route to match.
|
||||
|
||||
A good read on the subject of how to deal with trailing slashes is available on `Google Webmaster Central - To Slash or not to Slash`_.
|
||||
|
||||
.. _Google Webmaster Central - To Slash or not to Slash: http://googlewebmastercentral.blogspot.de/2010/04/to-slash-or-not-to-slash.html
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/PathDirectivesExamplesSpec.scala
|
||||
:snippet: 0redirectToNoTrailingSlashIfPresent
|
||||
:snippet: redirectToNoTrailingSlashIfPresent-0
|
||||
|
||||
See also :ref:`-redirectToTrailingSlashIfMissing-` which achieves the opposite - redirecting paths in case they do *not* have a trailing slash.
|
||||
|
|
@ -3,7 +3,10 @@
|
|||
redirectToTrailingSlashIfMissing
|
||||
================================
|
||||
|
||||
...
|
||||
If the requested path does not end with a trailing ``/`` character,
|
||||
redirects to the same path followed by such trailing slash.
|
||||
|
||||
Opposite of :ref:`-redirectToNoTrailingSlashIfPresent-`.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,10 +17,18 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Redirects the HTTP Client to the same resource yet followed by a trailing ``/``, in case the request did not contain it.
|
||||
When redirecting an HttpResponse with the given redirect response code (i.e. ``MovedPermanently`` or ``TemporaryRedirect``
|
||||
etc.) as well as a simple HTML page containing a "*click me to follow redirect*" link to be used in case the client can not,
|
||||
or refuses to for security reasons, automatically follow redirects.
|
||||
|
||||
Please note that the inner paths **MUST** end with an explicit trailing slash (e.g. ``"things"./``) for the
|
||||
re-directed-to route to match.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/PathDirectivesExamplesSpec.scala
|
||||
:snippet: 0redirectToTrailingSlashIfMissing
|
||||
:snippet: redirectToTrailingSlashIfMissing-0
|
||||
|
||||
See also :ref:`-redirectToNoTrailingSlashIfPresent-` which achieves the opposite - redirecting paths in case they do have a trailing slash.
|
||||
|
|
@ -20,11 +20,13 @@ Description
|
|||
This directive transforms ``HttpResponse`` and ``ChunkedResponseStart`` messages coming back from its inner route by
|
||||
potentially adding the given ``HttpHeader`` instance to the headers list.
|
||||
The header is only added if there is no header instance with the same name (case insensitively) already present in the
|
||||
response. If you'd like to add more than one header you can use the :ref:`-respondWithDefaultHeaders-` directive instead.
|
||||
response.
|
||||
|
||||
If you'd like to add more than one header you can use the :ref:`-respondWithDefaultHeaders-` directive instead.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/RespondWithDirectivesExamplesSpec.scala
|
||||
:snippet: respondWithDefaultHeader-examples
|
||||
:snippet: respondWithDefaultHeader-0
|
||||
|
|
|
|||
|
|
@ -26,4 +26,17 @@ response. If you'd like to add only a single header you can use the :ref:`-respo
|
|||
Example
|
||||
-------
|
||||
|
||||
The ``respondWithDefaultHeaders`` directive is equivalent to the ``respondWithDefaultHeader`` directive which
|
||||
is shown in the example below, however it allows including multiple default headers at once in the directive, like so::
|
||||
|
||||
respondWithDefaultHeaders(
|
||||
Origin(HttpOrigin("http://akka.io"),
|
||||
RawHeader("X-Fish-Name", "Blippy"))) { /*...*/ }
|
||||
|
||||
|
||||
The semantics remain the same however, as explained by the following example:
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/RespondWithDirectivesExamplesSpec.scala
|
||||
:snippet: respondWithDefaultHeader-0
|
||||
|
||||
See the :ref:`-respondWithDefaultHeader-` directive for an example with only one header.
|
||||
|
|
@ -25,4 +25,4 @@ Example
|
|||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/RespondWithDirectivesExamplesSpec.scala
|
||||
:snippet: respondWithHeader-examples
|
||||
:snippet: respondWithHeader-0
|
||||
|
|
@ -25,4 +25,4 @@ Example
|
|||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/RespondWithDirectivesExamplesSpec.scala
|
||||
:snippet: respondWithHeaders-examples
|
||||
:snippet: respondWithHeaders-0
|
||||
|
|
@ -3,21 +3,41 @@
|
|||
authenticateBasic
|
||||
=================
|
||||
|
||||
...
|
||||
Wraps the inner route with Http Basic authentication support using a given ``Authenticator[T]``.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateBasic
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
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 :class:`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 :ref:`-authenticateBasicAsync-`
|
||||
variant of this directive which allows it to run without blocking routing layer of Akka HTTP, freeing it for other requests.
|
||||
|
||||
The ``authenticate*`` directives themselfs are not tied to any HTTP-specific
|
||||
details so that various authentication schemes can be implemented on top of authenticate.
|
||||
|
||||
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``.
|
||||
|
||||
.. warning::
|
||||
Make sure to use basic authentication only over SSL because credentials are transferred in plaintext.
|
||||
|
||||
.. _HTTP Basic Authentication: https://en.wikipedia.org/wiki/Basic_auth
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: 0authenticateBasic
|
||||
:snippet: authenticateBasic-0
|
||||
|
|
|
|||
|
|
@ -1,23 +1,41 @@
|
|||
.. _-authenticateBasicAsync-:
|
||||
|
||||
authenticateBasicAsync
|
||||
=======================
|
||||
======================
|
||||
|
||||
...
|
||||
Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticator[T]``.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#async-authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateBasicAsync
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
This variant of the :ref:`authenticateBasic` directive returns a ``Future[Option[T]]`` which allows freeing up the routing
|
||||
layer of Akka HTTP, freeing it for other requests. It should be used whenever an authentication is expected to take
|
||||
a longer amount of time (e.g. looking up the user in a database).
|
||||
|
||||
In case the returned option is ``None`` the request is rejected with a :class:`AuthenticationFailedRejection`,
|
||||
which by default is mapped to an ``401 Unauthorized`` response.
|
||||
|
||||
The ``authenticate*`` directives themselfs are not tied to any HTTP-specific
|
||||
details so that various authentication schemes can be implemented on top of authenticate.
|
||||
|
||||
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``.
|
||||
|
||||
.. warning::
|
||||
Make sure to use basic authentication only over SSL because credentials are transferred in plaintext.
|
||||
|
||||
.. _HTTP Basic Authentication: https://en.wikipedia.org/wiki/Basic_auth
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: 0authenticateBasicAsync
|
||||
:snippet: authenticateBasicAsync-0
|
||||
|
|
|
|||
|
|
@ -3,18 +3,32 @@
|
|||
authenticateBasicPF
|
||||
===================
|
||||
|
||||
...
|
||||
Wraps the inner route with Http Basic authentication support using a given ``AuthenticatorPF[T]``.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator-pf
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateBasicPF
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Provides support for handling `HTTP Basic Authentication`_.
|
||||
|
||||
Refer to :ref:`-authenticateBasic-` for a detailed description of this dictive.
|
||||
It's semantics are equivalent to ``authenticateBasicPF`` 's, where not handling a case in the Partial Function (PF)
|
||||
leaves the request to be rejected with a :class:`AuthenticationFailedRejection` rejection.
|
||||
|
||||
Longer-running authentication tasks (like looking up credentials in a database) should use :ref:`authenticateBasicAsync`
|
||||
or :ref:`-authenticateBasicPFAsync-` if you prefer to use the ``PartialFunction`` syntax.
|
||||
|
||||
.. warning::
|
||||
Make sure to use basic authentication only over SSL because credentials are transferred in plaintext.
|
||||
|
||||
.. _HTTP Basic Authentication: https://en.wikipedia.org/wiki/Basic_auth
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -1,20 +1,34 @@
|
|||
.. _-authenticateBasicPFAsync-:
|
||||
|
||||
authenticateBasicPFAsync
|
||||
=========================
|
||||
========================
|
||||
|
||||
...
|
||||
Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticatorPF[T]``.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#async-authenticator-pf
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateBasicPFAsync
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Provides support for handling `HTTP Basic Authentication`_.
|
||||
|
||||
Refer to :ref:`-authenticateBasic-` for a detailed description of this dictive.
|
||||
It's semantics are equivalent to ``authenticateBasicPF`` 's, where not handling a case in the Partial Function (PF)
|
||||
leaves the request to be rejected with a :class:`AuthenticationFailedRejection` rejection.
|
||||
|
||||
Longer-running authentication tasks (like looking up credentials in a database) should use :ref:`authenticateBasicAsync`
|
||||
or :ref:`-authenticateBasicPFAsync-` if you prefer to use the ``PartialFunction`` syntax.
|
||||
|
||||
.. warning::
|
||||
Make sure to use basic authentication only over SSL because credentials are transferred in plaintext.
|
||||
|
||||
.. _HTTP Basic Authentication: https://en.wikipedia.org/wiki/Basic_auth
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -0,0 +1,25 @@
|
|||
.. _-authenticateOAuth2-:
|
||||
|
||||
authenticateOAuth2
|
||||
==================
|
||||
|
||||
...
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateOAuth2
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: authenticateOAuth2-0
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
.. _-authenticateOAuth2Async-:
|
||||
|
||||
authenticateOAuth2Async
|
||||
=======================
|
||||
|
||||
...
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateOAuth2Async
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: authenticateOAuth2Async-0
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
.. _-authenticateOAuth2AsyncPF-:
|
||||
|
||||
authenticateOAuth2AsyncPF
|
||||
=========================
|
||||
|
||||
...
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateOAuth2AsyncPF
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: authenticateOAuth2AsyncPF-0
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
.. _-authenticateOAuth2PF-:
|
||||
|
||||
authenticateOAuth2PF
|
||||
====================
|
||||
|
||||
...
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateOAuth2PF
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: authenticateOAuth2PF-0
|
||||
|
|
@ -3,21 +3,29 @@
|
|||
authenticateOrRejectWithChallenge
|
||||
=================================
|
||||
|
||||
...
|
||||
Lifts an authenticator function into a directive.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authentication-result
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authenticateOrRejectWithChallenge
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
This directive allows implementing the low level challange-response type of authentication that some services may require.
|
||||
|
||||
More details about challange-response authentication are available in the `RFC 2617`_, `RFC 7616`_ and `RFC 7617`_.
|
||||
|
||||
.. _RFC 2617: http://tools.ietf.org/html/rfc2617
|
||||
.. _RFC 7616: http://tools.ietf.org/html/rfc7616
|
||||
.. _RFC 7617: http://tools.ietf.org/html/rfc7617
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/SecurityDirectivesExamplesSpec.scala
|
||||
:snippet: 0authenticateOrRejectWithChallenge
|
||||
:snippet: authenticateOrRejectWithChallenge-0
|
||||
|
|
|
|||
|
|
@ -3,18 +3,33 @@
|
|||
authorize
|
||||
=========
|
||||
|
||||
...
|
||||
Applies the given authorization check to the request.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
||||
.. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authorize
|
||||
|
||||
.. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
|
||||
:snippet: authorize
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
The user-defined authorization check can either be supplied as a ``=> Boolean`` value which is calculated
|
||||
just from information out of the lexical scope, or as a function ``RequestContext => Boolean`` which can also
|
||||
take information from the request itself into account.
|
||||
|
||||
If the check returns ``true`` the request is passed on to the inner route unchanged, otherwise an
|
||||
``AuthorizationFailedRejection`` is created, triggering a ``403 Forbidden`` response by default
|
||||
(the same as in the case of an ``AuthenticationFailedRejection``).
|
||||
|
||||
In a common use-case you would check if a user (e.g. supplied by any of the ``authenticate*`` family of directives,
|
||||
e.g. :ref:`-authenticateBasic-`) is allowed to access the inner routes, e.g. by checking if the user has the needed permissions.
|
||||
|
||||
|
||||
.. note::
|
||||
See also :ref:`authentication-vs-authorization-scala` to understand the differences between those.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
extractCredentials
|
||||
==================
|
||||
|
||||
...
|
||||
Extracts the potentially present ``HttpCredentials`` provided with the request's ``Authorization`` header.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,7 +14,8 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
...
|
||||
Extracts the potentially present ``HttpCredentials`` provided with the request's ``Authorization`` header,
|
||||
which can be then used to implement some custom authentication or authorization logic.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -15,14 +15,16 @@ SecurityDirectives
|
|||
extractCredentials
|
||||
|
||||
|
||||
.. _authentication-vs-authorization-scala:
|
||||
|
||||
Authentication vs. Authorization
|
||||
--------------------------------
|
||||
|
||||
*Authentication* is the process of establishing a known identity for the user, whereby 'identity' is defined in the
|
||||
**Authentication** is the process of establishing a known identity for the user, whereby 'identity' is defined in the
|
||||
context of the application. This may be done with a username/password combination, a cookie, a pre-defined IP or some
|
||||
other mechanism. After authentication the system believes that it knows who the user is.
|
||||
|
||||
*Authorization* is the process of determining, whether a given user is allowed access to a given resource or not. In
|
||||
**Authorization** is the process of determining, whether a given user is allowed access to a given resource or not. In
|
||||
most cases, in order to be able to authorize a user (i.e. allow access to some part of the system) the users identity
|
||||
must already have been established, i.e. he/she must have been authenticated. Without prior authentication the
|
||||
authorization would have to be very crude, e.g. "allow access for *all* users" or "allow access for *noone*". Only after
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue